Add the library sources for Haskell 2010, generated by Haddock
authorSimon Marlow <marlowsd@gmail.com>
Tue, 29 Jun 2010 15:02:49 +0000 (15:02 +0000)
committerSimon Marlow <marlowsd@gmail.com>
Tue, 29 Jun 2010 15:02:49 +0000 (15:02 +0000)
29 files changed:
report/libs/Control-Monad.tex [new file with mode: 0644]
report/libs/Data-Array.tex [new file with mode: 0644]
report/libs/Data-Bits.tex [new file with mode: 0644]
report/libs/Data-Char.tex [new file with mode: 0644]
report/libs/Data-Complex.tex [new file with mode: 0644]
report/libs/Data-Int.tex [new file with mode: 0644]
report/libs/Data-Ix.tex [new file with mode: 0644]
report/libs/Data-List.tex [new file with mode: 0644]
report/libs/Data-Maybe.tex [new file with mode: 0644]
report/libs/Data-Ratio.tex [new file with mode: 0644]
report/libs/Data-Word.tex [new file with mode: 0644]
report/libs/Foreign-C-Error.tex [new file with mode: 0644]
report/libs/Foreign-C-String.tex [new file with mode: 0644]
report/libs/Foreign-C-Types.tex [new file with mode: 0644]
report/libs/Foreign-C.tex [new file with mode: 0644]
report/libs/Foreign-ForeignPtr.tex [new file with mode: 0644]
report/libs/Foreign-Marshal-Alloc.tex [new file with mode: 0644]
report/libs/Foreign-Marshal-Array.tex [new file with mode: 0644]
report/libs/Foreign-Marshal-Error.tex [new file with mode: 0644]
report/libs/Foreign-Marshal-Utils.tex [new file with mode: 0644]
report/libs/Foreign-Marshal.tex [new file with mode: 0644]
report/libs/Foreign-Ptr.tex [new file with mode: 0644]
report/libs/Foreign-StablePtr.tex [new file with mode: 0644]
report/libs/Foreign-Storable.tex [new file with mode: 0644]
report/libs/Foreign.tex [new file with mode: 0644]
report/libs/System-Environment.tex [new file with mode: 0644]
report/libs/System-Exit.tex [new file with mode: 0644]
report/libs/System-IO-Error.tex [new file with mode: 0644]
report/libs/System-IO.tex [new file with mode: 0644]

diff --git a/report/libs/Control-Monad.tex b/report/libs/Control-Monad.tex
new file mode 100644 (file)
index 0000000..45c3311
--- /dev/null
@@ -0,0 +1,519 @@
+\chapter{\texttt{Control.Monad}}
+\label{module:Control.Monad}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Control.Monad (
+    Functor(fmap),  Monad((>>=), (>>), return, fail),  MonadPlus(mzero, mplus), 
+    mapM,  mapM_,  forM,  forM_,  sequence,  sequence_,  (=<<),  (>=>),  (<=<), 
+    forever,  void,  join,  msum,  filterM,  mapAndUnzipM,  zipWithM, 
+    zipWithM_,  foldM,  foldM_,  replicateM,  replicateM_,  guard,  when, 
+    unless,  liftM,  liftM2,  liftM3,  liftM4,  liftM5,  ap
+  ) where\end{verbatim}}
+\haddockendheader
+
+The \haddocktt{Control.Monad} module provide the \haddockid{Functor}, \haddockid{Monad} and
+ \haddockid{MonadPlus} classes, together with some useful operations on monads.
+\par
+
+\section{Functor and monad classes
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+class\ Functor\ f\ where
+\end{tabular}]\haddockbegindoc
+The \haddockid{Functor} class is used for types that can be mapped over.
+Instances of \haddockid{Functor} should satisfy the following laws:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ fmap id  ==  id
+ fmap (f . g)  ==  fmap f . fmap g
+\end{verbatim}}
+\end{quote}
+The instances of \haddockid{Functor} for lists, \haddocktt{Data.Maybe.Maybe} and \haddocktt{System.IO.IO}
+defined in the \haddocktt{Prelude} satisfy these laws.
+\par
+
+\haddockpremethods{}\textbf{Methods}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+fmap\ ::\ (a\ ->\ b)\ ->\ f\ a\ ->\ f\ b
+\end{tabular}]
+\end{haddockdesc}
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Functor\ {\char 91}{\char 93}\\instance\ Functor\ IO\\instance\ Functor\ ReadP\\instance\ Functor\ Maybe\\instance\ Ix\ i\ =>\ Functor\ (Array\ i)
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+class\ Monad\ m\ where
+\end{tabular}]\haddockbegindoc
+The \haddockid{Monad} class defines the basic operations over a \emph{monad},
+a concept from a branch of mathematics known as \emph{category theory}.
+From the perspective of a Haskell programmer, however, it is best to
+think of a monad as an \emph{abstract datatype} of actions.
+Haskell's \haddocktt{do} expressions provide a convenient syntax for writing
+monadic expressions.
+\par
+Minimal complete definition: \haddockid{>>=} and \haddockid{return}.
+\par
+Instances of \haddockid{Monad} should satisfy the following laws:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ return a >>= k  ==  k a
+ m >>= return  ==  m
+ m >>= (\x -> k x >>= h)  ==  (m >>= k) >>= h
+\end{verbatim}}
+\end{quote}
+Instances of both \haddockid{Monad} and \haddockid{Functor} should additionally satisfy the law:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ fmap f xs  ==  xs >>= return . f
+\end{verbatim}}
+\end{quote}
+The instances of \haddockid{Monad} for lists, \haddocktt{Data.Maybe.Maybe} and \haddocktt{System.IO.IO}
+defined in the \haddocktt{Prelude} satisfy these laws.
+\par
+
+\haddockpremethods{}\textbf{Methods}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(>>=)\ ::\ m\ a\ ->\ (a\ ->\ m\ b)\ ->\ m\ b
+\end{tabular}]\haddockbegindoc
+Sequentially compose two actions, passing any value produced
+ by the first as an argument to the second.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(>>)\ ::\ m\ a\ ->\ m\ b\ ->\ m\ b
+\end{tabular}]\haddockbegindoc
+Sequentially compose two actions, discarding any value produced
+ by the first, like sequencing operators (such as the semicolon)
+ in imperative languages.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+return\ ::\ a\ ->\ m\ a
+\end{tabular}]\haddockbegindoc
+Inject a value into the monadic type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+fail\ ::\ String\ ->\ m\ a
+\end{tabular}]\haddockbegindoc
+Fail with a message.  This operation is not part of the
+ mathematical definition of a monad, but is invoked on pattern-match
+ failure in a \haddocktt{do} expression.
+\par
+
+\end{haddockdesc}
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Monad\ {\char 91}{\char 93}\\instance\ Monad\ IO\\instance\ Monad\ P\\instance\ Monad\ ReadP\\instance\ Monad\ Maybe
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+class\ Monad\ m\ =>\ MonadPlus\ m\ where
+\end{tabular}]\haddockbegindoc
+Monads that also support choice and failure.
+\par
+
+\haddockpremethods{}\textbf{Methods}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mzero\ ::\ m\ a
+\end{tabular}]\haddockbegindoc
+the identity of \haddockid{mplus}.  It should also satisfy the equations
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ mzero >>= f  =  mzero
+ v >> mzero   =  mzero
+\end{verbatim}}
+\end{quote}
+(but the instance for \haddocktt{System.IO.IO} defined in Control.Monad.Error
+ in the mtl package does not satisfy the second one).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mplus\ ::\ m\ a\ ->\ m\ a\ ->\ m\ a
+\end{tabular}]\haddockbegindoc
+an associative operation
+\par
+
+\end{haddockdesc}
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ MonadPlus\ {\char 91}{\char 93}\\instance\ MonadPlus\ P\\instance\ MonadPlus\ ReadP\\instance\ MonadPlus\ Maybe
+\end{tabular}]
+\end{haddockdesc}
+\section{Functions
+}
+\subsection{Naming conventions
+}
+The functions in this library use the following naming conventions: 
+\par
+\begin{itemize}
+\item
+ A postfix '\haddocktt{M}' always stands for a function in the Kleisli category:
+  The monad type constructor \haddocktt{m} is added to function results
+  (modulo currying) and nowhere else.  So, for example, 
+\par
+
+\end{itemize}
+\begin{quote}
+{\haddockverb\begin{verbatim}
+  filter  ::              (a ->   Bool) -> [a] ->   [a]
+  filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]
+\end{verbatim}}
+\end{quote}
+\begin{itemize}
+\item
+ A postfix '\haddocktt{{\char '137}}' changes the result type from \haddocktt{(m\ a)} to \haddocktt{(m\ ())}.
+  Thus, for example: 
+\par
+
+\end{itemize}
+\begin{quote}
+{\haddockverb\begin{verbatim}
+  sequence  :: Monad m => [m a] -> m [a] 
+  sequence_ :: Monad m => [m a] -> m () 
+\end{verbatim}}
+\end{quote}
+\begin{itemize}
+\item
+ A prefix '\haddocktt{m}' generalizes an existing function to a monadic form.
+  Thus, for example: 
+\par
+
+\end{itemize}
+\begin{quote}
+{\haddockverb\begin{verbatim}
+  sum  :: Num a       => [a]   -> a
+  msum :: MonadPlus m => [m a] -> m a
+\end{verbatim}}
+\end{quote}
+
+\subsection{Basic \haddocktt{Monad} functions
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mapM\ ::\ Monad\ m\ =>\ (a\ ->\ m\ b)\ ->\ {\char 91}a{\char 93}\ ->\ m\ {\char 91}b{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddocktt{mapM\ f} is equivalent to \haddocktt{sequence\ .\ map\ f}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mapM{\char '137}\ ::\ Monad\ m\ =>\ (a\ ->\ m\ b)\ ->\ {\char 91}a{\char 93}\ ->\ m\ ()
+\end{tabular}]\haddockbegindoc
+\haddocktt{mapM{\char '137}\ f} is equivalent to \haddocktt{sequence{\char '137}\ .\ map\ f}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+forM\ ::\ Monad\ m\ =>\ {\char 91}a{\char 93}\ ->\ (a\ ->\ m\ b)\ ->\ m\ {\char 91}b{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{forM} is \haddockid{mapM} with its arguments flipped
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+forM{\char '137}\ ::\ Monad\ m\ =>\ {\char 91}a{\char 93}\ ->\ (a\ ->\ m\ b)\ ->\ m\ ()
+\end{tabular}]\haddockbegindoc
+\haddockid{forM{\char '137}} is \haddockid{mapM{\char '137}} with its arguments flipped
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+sequence\ ::\ Monad\ m\ =>\ {\char 91}m\ a{\char 93}\ ->\ m\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+Evaluate each action in the sequence from left to right,
+ and collect the results.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+sequence{\char '137}\ ::\ Monad\ m\ =>\ {\char 91}m\ a{\char 93}\ ->\ m\ ()
+\end{tabular}]\haddockbegindoc
+Evaluate each action in the sequence from left to right,
+ and ignore the results.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(=<<)\ ::\ Monad\ m\ =>\ (a\ ->\ m\ b)\ ->\ m\ a\ ->\ m\ b
+\end{tabular}]\haddockbegindoc
+Same as \haddockid{>>=}, but with the arguments interchanged.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(>=>)\ ::\ Monad\ m\ =>\ (a\ ->\ m\ b)\ ->\ (b\ ->\ m\ c)\ ->\ a\ ->\ m\ c
+\end{tabular}]\haddockbegindoc
+Left-to-right Kleisli composition of monads.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(<=<)\ ::\ Monad\ m\ =>\ (b\ ->\ m\ c)\ ->\ (a\ ->\ m\ b)\ ->\ a\ ->\ m\ c
+\end{tabular}]\haddockbegindoc
+Right-to-left Kleisli composition of monads. \haddocktt{(>=>)}, with the arguments flipped
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+forever\ ::\ Monad\ m\ =>\ m\ a\ ->\ m\ b
+\end{tabular}]\haddockbegindoc
+\haddocktt{forever\ act} repeats the action infinitely.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+void\ ::\ Functor\ f\ =>\ f\ a\ ->\ f\ ()
+\end{tabular}]\haddockbegindoc
+\haddocktt{void\ value} discards or ignores the result of evaluation, such as the return value of an \haddockid{IO} action.
+\par
+
+\end{haddockdesc}
+\subsection{Generalisations of list functions
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+join\ ::\ Monad\ m\ =>\ m\ (m\ a)\ ->\ m\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{join} function is the conventional monad join operator. It is used to
+ remove one level of monadic structure, projecting its bound argument into the
+ outer level.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+msum\ ::\ MonadPlus\ m\ =>\ {\char 91}m\ a{\char 93}\ ->\ m\ a
+\end{tabular}]\haddockbegindoc
+This generalizes the list-based \haddockid{concat} function.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+filterM\ ::\ Monad\ m\ =>\ (a\ ->\ m\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ m\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+This generalizes the list-based \haddockid{filter} function.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mapAndUnzipM\ ::\ Monad\ m\ =>\ (a\ ->\ m\ (b,\ c))\ ->\ {\char 91}a{\char 93}\ ->\ m\ ({\char 91}b{\char 93},\ {\char 91}c{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{mapAndUnzipM} function maps its first argument over a list, returning
+ the result as a pair of lists. This function is mainly used with complicated
+ data structures or a state-transforming monad.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zipWithM\ ::\ Monad\ m\ =>\ (a\ ->\ b\ ->\ m\ c)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ m\ {\char 91}c{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zipWithM} function generalizes \haddockid{zipWith} to arbitrary monads.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zipWithM{\char '137}\ ::\ Monad\ m\ =>\ (a\ ->\ b\ ->\ m\ c)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ m\ ()
+\end{tabular}]\haddockbegindoc
+\haddockid{zipWithM{\char '137}} is the extension of \haddockid{zipWithM} which ignores the final result.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+foldM\ ::\ Monad\ m\ =>\ (a\ ->\ b\ ->\ m\ a)\ ->\ a\ ->\ {\char 91}b{\char 93}\ ->\ m\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{foldM} function is analogous to \haddockid{foldl}, except that its result is
+encapsulated in a monad. Note that \haddockid{foldM} works from left-to-right over
+the list arguments. This could be an issue where \haddocktt{(>>)} and the `folded
+function' are not commutative.
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+       foldM f a1 [x1, x2, ..., xm ]
+\end{verbatim}}
+\end{quote}
+==  
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+       do
+         a2 <- f a1 x1
+         a3 <- f a2 x2
+         ...
+         f am xm
+\end{verbatim}}
+\end{quote}
+If right-to-left evaluation is required, the input list should be reversed.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+foldM{\char '137}\ ::\ Monad\ m\ =>\ (a\ ->\ b\ ->\ m\ a)\ ->\ a\ ->\ {\char 91}b{\char 93}\ ->\ m\ ()
+\end{tabular}]\haddockbegindoc
+Like \haddockid{foldM}, but discards the result.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+replicateM\ ::\ Monad\ m\ =>\ Int\ ->\ m\ a\ ->\ m\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddocktt{replicateM\ n\ act} performs the action \haddocktt{n} times,
+ gathering the results.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+replicateM{\char '137}\ ::\ Monad\ m\ =>\ Int\ ->\ m\ a\ ->\ m\ ()
+\end{tabular}]\haddockbegindoc
+Like \haddockid{replicateM}, but discards the result.
+\par
+
+\end{haddockdesc}
+\subsection{Conditional execution of monadic expressions
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+guard\ ::\ MonadPlus\ m\ =>\ Bool\ ->\ m\ ()
+\end{tabular}]\haddockbegindoc
+\haddocktt{guard\ b} is \haddocktt{return\ ()} if \haddocktt{b} is \haddockid{True},
+ and \haddockid{mzero} if \haddocktt{b} is \haddockid{False}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+when\ ::\ Monad\ m\ =>\ Bool\ ->\ m\ ()\ ->\ m\ ()
+\end{tabular}]\haddockbegindoc
+Conditional execution of monadic expressions. For example, 
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+       when debug (putStr "Debugging\n")
+\end{verbatim}}
+\end{quote}
+will output the string \haddocktt{Debugging{\char '134}n} if the Boolean value \haddocktt{debug} is \haddockid{True},
+and otherwise do nothing.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unless\ ::\ Monad\ m\ =>\ Bool\ ->\ m\ ()\ ->\ m\ ()
+\end{tabular}]\haddockbegindoc
+The reverse of \haddockid{when}.
+\par
+
+\end{haddockdesc}
+\subsection{Monadic lifting operators
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+liftM\ ::\ Monad\ m\ =>\ (a1\ ->\ r)\ ->\ m\ a1\ ->\ m\ r
+\end{tabular}]\haddockbegindoc
+Promote a function to a monad.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+liftM2\ ::\ Monad\ m\ =>\ (a1\ ->\ a2\ ->\ r)\ ->\ m\ a1\ ->\ m\ a2\ ->\ m\ r
+\end{tabular}]\haddockbegindoc
+Promote a function to a monad, scanning the monadic arguments from
+ left to right.  For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+    liftM2 (+) [0,1] [0,2] = [0,2,1,3]
+    liftM2 (+) (Just 1) Nothing = Nothing
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+liftM3\ ::\ Monad\ m\ =>\ (a1\ ->\ a2\ ->\ a3\ ->\ r)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ m\ a1\ ->\ m\ a2\ ->\ m\ a3\ ->\ m\ r
+\end{tabular}]\haddockbegindoc
+Promote a function to a monad, scanning the monadic arguments from
+ left to right (cf. \haddockid{liftM2}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+liftM4\ ::\ Monad\ m\ =>\ (a1\ ->\ a2\ ->\ a3\ ->\ a4\ ->\ r)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ m\ a1\ ->\ m\ a2\ ->\ m\ a3\ ->\ m\ a4\ ->\ m\ r
+\end{tabular}]\haddockbegindoc
+Promote a function to a monad, scanning the monadic arguments from
+ left to right (cf. \haddockid{liftM2}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+liftM5\ ::\ Monad\ m\ =>\ (a1\ ->\ a2\ ->\ a3\ ->\ a4\ ->\ a5\ ->\ r)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ m\ a1\ ->\ m\ a2\ ->\ m\ a3\ ->\ m\ a4\ ->\ m\ a5\ ->\ m\ r
+\end{tabular}]\haddockbegindoc
+Promote a function to a monad, scanning the monadic arguments from
+ left to right (cf. \haddockid{liftM2}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+ap\ ::\ Monad\ m\ =>\ m\ (a\ ->\ b)\ ->\ m\ a\ ->\ m\ b
+\end{tabular}]\haddockbegindoc
+In many situations, the \haddockid{liftM} operations can be replaced by uses of
+\haddockid{ap}, which promotes function application. 
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+       return f `ap` x1 `ap` ... `ap` xn
+\end{verbatim}}
+\end{quote}
+is equivalent to 
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+       liftMn f x1 x2 ... xn
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Data-Array.tex b/report/libs/Data-Array.tex
new file mode 100644 (file)
index 0000000..fcb2960
--- /dev/null
@@ -0,0 +1,336 @@
+\chapter{\texttt{Data.Array}}
+\label{module:Data.Array}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.Array (
+    module Data.Ix,  Array,  array,  listArray,  accumArray,  (!),  bounds, 
+    indices,  elems,  assocs,  (//),  accum,  ixmap
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{Immutable non-strict arrays
+}
+Haskell provides indexable \emph{arrays}, which may be thought of as functions
+whose domains are isomorphic to contiguous subsets of the integers.
+Functions restricted in this way can be implemented efficiently;
+in particular, a programmer may reasonably expect rapid access to
+the components.  To ensure the possibility of such an implementation,
+arrays are treated as data, not as general functions.
+\par
+Since most array functions involve the class \haddockid{Ix}, this module is exported
+from \haddocktt{Data.Array} so that modules need not import both \haddocktt{Data.Array} and
+\haddocktt{Data.Ix}.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+module\ Data.Ix
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Ix\ i\ =>\ Array\ i\ e
+\end{tabular}]\haddockbegindoc
+The type of immutable non-strict (boxed) arrays
+ with indices in \haddocktt{i} and elements in \haddocktt{e}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Ix\ i\ =>\ Functor\ (Array\ i)\\instance\ (Ix\ i,\ Eq\ e)\ =>\ Eq\ (Array\ i\ e)\\instance\ (Ix\ i,\ Ord\ e)\ =>\ Ord\ (Array\ i\ e)\\instance\ (Ix\ a,\ Read\ a,\ Read\ b)\ =>\ Read\ (Array\ a\ b)\\instance\ (Ix\ a,\ Show\ a,\ Show\ b)\ =>\ Show\ (Array\ a\ b)
+\end{tabular}]
+\end{haddockdesc}
+\section{Array construction
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+array
+\end{tabular}]\haddockbegindoc
+\haddockbeginargs
+\haddockdecltt{::} & \haddockdecltt{Ix i} \\
+                     \haddockdecltt{=>} & \haddockdecltt{(i, i)} & a pair of \emph{bounds}, each of the index type
+ of the array.  These bounds are the lowest and
+ highest indices in the array, in that order.
+ For example, a one-origin vector of length
+ '10' has bounds '(1,10)', and a one-origin '10'
+ by '10' matrix has bounds '((1,1),(10,10))'.
+ \\
+                                                                   \haddockdecltt{->} & \haddockdecltt{[(i, e)]} & a list of \emph{associations} of the form
+ (\emph{index}, \emph{value}).  Typically, this list will
+ be expressed as a comprehension.  An
+ association '(i, x)' defines the value of
+ the array at index \haddocktt{i} to be \haddocktt{x}.
+ \\
+                                                                                                                   \haddockdecltt{->} & \haddockdecltt{Array i e} & \\
+\haddockendargs\par
+Construct an array with the specified bounds and containing values
+ for given indices within these bounds.
+\par
+The array is undefined (i.e. bottom) if any index in the list is
+ out of bounds.  The Haskell 98 Report further specifies that if any
+ two associations in the list have the same index, the value at that
+ index is undefined (i.e. bottom).  However in GHC's implementation,
+ the value at such an index is the value part of the last association
+ with that index in the list.
+\par
+Because the indices must be checked for these errors, \haddockid{array} is
+ strict in the bounds argument and in the indices of the association
+ list, but nonstrict in the values.  Thus, recurrences such as the
+ following are possible:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ a = array (1,100) ((1,1) : [(i, i * a!(i-1)) | i <- [2..100]])
+\end{verbatim}}
+\end{quote}
+Not every index within the bounds of the array need appear in the
+ association list, but the values associated with indices that do not
+ appear will be undefined (i.e. bottom).
+\par
+If, in any dimension, the lower bound is greater than the upper bound,
+ then the array is legal, but empty.  Indexing an empty array always
+ gives an array-bounds error, but \haddockid{bounds} still yields the bounds
+ with which the array was constructed.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+listArray\ ::\ Ix\ i\ =>\ (i,\ i)\ ->\ {\char 91}e{\char 93}\ ->\ Array\ i\ e
+\end{tabular}]\haddockbegindoc
+Construct an array from a pair of bounds and a list of values in
+ index order.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+accumArray
+\end{tabular}]\haddockbegindoc
+\haddockbeginargs
+\haddockdecltt{::} & \haddockdecltt{Ix i} \\
+                     \haddockdecltt{=>} & \haddockdecltt{(e
+                                                          -> a
+                                                             -> e)} & accumulating function
+ \\
+                                                                      \haddockdecltt{->} & \haddockdecltt{e} & initial value
+ \\
+                                                                                                               \haddockdecltt{->} & \haddockdecltt{(i, i)} & bounds of the array
+ \\
+                                                                                                                                                             \haddockdecltt{->} & \haddockdecltt{[(i, a)]} & association list
+ \\
+                                                                                                                                                                                                             \haddockdecltt{->} & \haddockdecltt{Array i e} & \\
+\haddockendargs\par
+The \haddockid{accumArray} function deals with repeated indices in the association
+ list using an \emph{accumulating function} which combines the values of
+ associations with the same index.
+ For example, given a list of values of some index type, \haddocktt{hist}
+ produces a histogram of the number of occurrences of each index within
+ a specified range:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ hist :: (Ix a, Num b) => (a,a) -> [a] -> Array a b
+ hist bnds is = accumArray (+) 0 bnds [(i, 1) | i<-is, inRange bnds i]
+\end{verbatim}}
+\end{quote}
+If the accumulating function is strict, then \haddockid{accumArray} is strict in
+ the values, as well as the indices, in the association list.  Thus,
+ unlike ordinary arrays built with \haddockid{array}, accumulated arrays should
+ not in general be recursive.
+\par
+
+\end{haddockdesc}
+\section{Accessing arrays
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(!)\ ::\ Ix\ i\ =>\ Array\ i\ e\ ->\ i\ ->\ e
+\end{tabular}]\haddockbegindoc
+The value at the given index in an array.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+bounds\ ::\ Ix\ i\ =>\ Array\ i\ e\ ->\ (i,\ i)
+\end{tabular}]\haddockbegindoc
+The bounds with which an array was constructed.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+indices\ ::\ Ix\ i\ =>\ Array\ i\ e\ ->\ {\char 91}i{\char 93}
+\end{tabular}]\haddockbegindoc
+The list of indices of an array in ascending order.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+elems\ ::\ Ix\ i\ =>\ Array\ i\ e\ ->\ {\char 91}e{\char 93}
+\end{tabular}]\haddockbegindoc
+The list of elements of an array in index order.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+assocs\ ::\ Ix\ i\ =>\ Array\ i\ e\ ->\ {\char 91}(i,\ e){\char 93}
+\end{tabular}]\haddockbegindoc
+The list of associations of an array in index order.
+\par
+
+\end{haddockdesc}
+\section{Incremental array updates
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(//)\ ::\ Ix\ i\ =>\ Array\ i\ e\ ->\ {\char 91}(i,\ e){\char 93}\ ->\ Array\ i\ e
+\end{tabular}]\haddockbegindoc
+Constructs an array identical to the first argument except that it has
+ been updated by the associations in the right argument.
+ For example, if \haddocktt{m} is a 1-origin, \haddocktt{n} by \haddocktt{n} matrix, then
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ m//[((i,i), 0) | i <- [1..n]]
+\end{verbatim}}
+\end{quote}
+is the same matrix, except with the diagonal zeroed.
+\par
+Repeated indices in the association list are handled as for \haddockid{array}:
+ Haskell 98 specifies that the resulting array is undefined (i.e. bottom),
+ but GHC's implementation uses the last association for each index.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+accum\ ::\ Ix\ i\ =>\ (e\ ->\ a\ ->\ e)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ Array\ i\ e\ ->\ {\char 91}(i,\ a){\char 93}\ ->\ Array\ i\ e
+\end{tabular}]\haddockbegindoc
+\haddocktt{accum\ f} takes an array and an association list and accumulates
+ pairs from the list into the array with the accumulating function \haddocktt{f}.
+ Thus \haddockid{accumArray} can be defined using \haddockid{accum}:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ accumArray f z b = accum f (array b [(i, z) | i <- range b])
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\section{Derived arrays
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+ixmap\ ::\ (Ix\ i,\ Ix\ j)\ =>\ (i,\ i)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ (i\ ->\ j)\ ->\ Array\ j\ e\ ->\ Array\ i\ e
+\end{tabular}]\haddockbegindoc
+\haddockid{ixmap} allows for transformations on array indices.
+ It may be thought of as providing function composition on the right
+ with the mapping that the original array embodies.
+\par
+A similar transformation of array values may be achieved using \haddockid{fmap}
+ from the \haddockid{Array} instance of the \haddockid{Functor} class.
+\par
+
+\end{haddockdesc}
+\section{Specification
+}
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ module  Array ( 
+     module Ix,  -- export all of Ix 
+     Array, array, listArray, (!), bounds, indices, elems, assocs, 
+     accumArray, (//), accum, ixmap ) where
+ import Ix
+ import List( (\\) )
+ infixl 9  !, //
+ data (Ix a) => Array a b = MkArray (a,a) (a -> b) deriving ()
+ array       :: (Ix a) => (a,a) -> [(a,b)] -> Array a b
+ array b ivs =
+     if and [inRange b i | (i,_) <- ivs]
+         then MkArray b
+                      (\j -> case [v | (i,v) <- ivs, i == j] of
+                             [v]   -> v
+                             []    -> error "Array.!: >                                            \undefined array element"
+\end{verbatim}}
+\end{quote}
+\begin{quote}
+{\haddockverb\begin{verbatim}
+                             _     -> error "Array.!: >                                            \multiply defined array element")
+\end{verbatim}}
+\end{quote}
+\begin{quote}
+{\haddockverb\begin{verbatim}
+         else error "Array.array: out-of-range array association"
+ listArray             :: (Ix a) => (a,a) -> [b] -> Array a b
+ listArray b vs        =  array b (zipWith (\ a b -> (a,b)) (range b) vs)
+ (!)                   :: (Ix a) => Array a b -> a -> b
+ (!) (MkArray _ f)     =  f
+ bounds                :: (Ix a) => Array a b -> (a,a)
+ bounds (MkArray b _)  =  b
+ indices               :: (Ix a) => Array a b -> [a]
+ indices               =  range . bounds
+ elems                 :: (Ix a) => Array a b -> [b]
+ elems a               =  [a!i | i <- indices a]
+ assocs                :: (Ix a) => Array a b -> [(a,b)]
+ assocs a              =  [(i, a!i) | i <- indices a]
+ (//)                  :: (Ix a) => Array a b -> [(a,b)] -> Array a b
+ a // new_ivs          = array (bounds a) (old_ivs ++ new_ivs)
+                       where
+                       old_ivs = [(i,a!i) | i <- indices a,
+                                              i `notElem` new_is]
+                       new_is  = [i | (i,_) <- new_ivs]
+ accum                 :: (Ix a) => (b -> c -> b) -> Array a b -> [(a,c)]
+                                    -> Array a b
+ accum f               =  foldl (\a (i,v) -> a // [(i,f (a!i) v)])
+ accumArray            :: (Ix a) => (b -> c -> b) -> b -> (a,a) -> [(a,c)]
+                                    -> Array a b
+ accumArray f z b      =  accum f (array b [(i,z) | i <- range b])
+ ixmap                 :: (Ix a, Ix b) => (a,a) -> (a -> b) -> Array b c
+                                          -> Array a c
+ ixmap b f a           = array b [(i, a ! f i) | i <- range b]
+ instance  (Ix a)          => Functor (Array a) where
+     fmap fn (MkArray b f) =  MkArray b (fn . f) 
+ instance  (Ix a, Eq b)  => Eq (Array a b)  where
+     a == a' =  assocs a == assocs a'
+ instance  (Ix a, Ord b) => Ord (Array a b)  where
+     a <= a' =  assocs a <= assocs a'
+ instance  (Ix a, Show a, Show b) => Show (Array a b)  where
+     showsPrec p a = showParen (p > arrPrec) (
+                     showString "array " .
+                     showsPrec (arrPrec+1) (bounds a) . showChar ' ' .
+                     showsPrec (arrPrec+1) (assocs a)                  )
+ instance  (Ix a, Read a, Read b) => Read (Array a b)  where
+     readsPrec p = readParen (p > arrPrec)
+            (\r -> [ (array b as, u) 
+                   | ("array",s) <- lex r,
+                     (b,t)       <- readsPrec (arrPrec+1) s,
+                     (as,u)      <- readsPrec (arrPrec+1) t ])
+ -- Precedence of the 'array' function is that of application itself
+ arrPrec = 10
+\end{verbatim}}
+\end{quote}
diff --git a/report/libs/Data-Bits.tex b/report/libs/Data-Bits.tex
new file mode 100644 (file)
index 0000000..e5d348e
--- /dev/null
@@ -0,0 +1,231 @@
+\chapter{\texttt{Data.Bits}}
+\label{module:Data.Bits}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.Bits (
+    Bits((.&.),
+         (.|.),
+         xor,
+         complement,
+         shift,
+         rotate,
+         bit,
+         setBit,
+         clearBit,
+         complementBit,
+         testBit,
+         bitSize,
+         isSigned,
+         shiftL,
+         shiftR,
+         rotateL,
+         rotateR)
+  ) where\end{verbatim}}
+\haddockendheader
+
+This module defines bitwise operations for signed and unsigned
+ integers.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+class\ Num\ a\ =>\ Bits\ a\ where
+\end{tabular}]\haddockbegindoc
+The \haddockid{Bits} class defines bitwise operations over integral types.
+\par
+\begin{itemize}
+\item
+ Bits are numbered from 0 with bit 0 being the least
+  significant bit.
+\par
+
+\end{itemize}
+Minimal complete definition: \haddockid{.{\char '46}.}, \haddockid{.|.}, \haddockid{xor}, \haddockid{complement},
+(\haddockid{shift} or (\haddockid{shiftL} and \haddockid{shiftR})), (\haddockid{rotate} or (\haddockid{rotateL} and \haddockid{rotateR})),
+\haddockid{bitSize} and \haddockid{isSigned}.
+\par
+
+\haddockpremethods{}\textbf{Methods}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(.{\char '46}.)\ ::\ a\ ->\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+Bitwise "and"
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(.|.)\ ::\ a\ ->\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+Bitwise "or"
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+xor\ ::\ a\ ->\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+Bitwise "xor"
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+complement\ ::\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+Reverse all the bits in the argument 
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+shift\ ::\ a\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddocktt{shift\ x\ i} shifts \haddocktt{x} left by \haddocktt{i} bits if \haddocktt{i} is positive,
+        or right by \haddocktt{-i} bits otherwise.
+        Right shifts perform sign extension on signed number types;
+        i.e. they fill the top bits with 1 if the \haddocktt{x} is negative
+        and with 0 otherwise.
+\par
+An instance can define either this unified \haddockid{shift} or \haddockid{shiftL} and
+        \haddockid{shiftR}, depending on which is more convenient for the type in
+        question. 
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+rotate\ ::\ a\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddocktt{rotate\ x\ i} rotates \haddocktt{x} left by \haddocktt{i} bits if \haddocktt{i} is positive,
+        or right by \haddocktt{-i} bits otherwise.
+\par
+For unbounded types like \haddockid{Integer}, \haddockid{rotate} is equivalent to \haddockid{shift}.
+\par
+An instance can define either this unified \haddockid{rotate} or \haddockid{rotateL} and
+        \haddockid{rotateR}, depending on which is more convenient for the type in
+        question. 
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+bit\ ::\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddocktt{bit\ i} is a value with the \haddocktt{i}th bit set
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+setBit\ ::\ a\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddocktt{x\ `setBit`\ i} is the same as \haddocktt{x\ .|.\ bit\ i}
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+clearBit\ ::\ a\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddocktt{x\ `clearBit`\ i} is the same as \haddocktt{x\ .{\char '46}.\ complement\ (bit\ i)}
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+complementBit\ ::\ a\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddocktt{x\ `complementBit`\ i} is the same as \haddocktt{x\ `xor`\ bit\ i}
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+testBit\ ::\ a\ ->\ Int\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Return \haddockid{True} if the \haddocktt{n}th bit of the argument is 1
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+bitSize\ ::\ a\ ->\ Int
+\end{tabular}]\haddockbegindoc
+Return the number of bits in the type of the argument.  The actual
+        value of the argument is ignored.  The function \haddockid{bitSize} is
+        undefined for types that do not have a fixed bitsize, like \haddockid{Integer}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isSigned\ ::\ a\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Return \haddockid{True} if the argument is a signed type.  The actual
+        value of the argument is ignored 
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+shiftL\ ::\ a\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+Shift the argument left by the specified number of bits
+        (which must be non-negative).
+\par
+An instance can define either this and \haddockid{shiftR} or the unified
+        \haddockid{shift}, depending on which is more convenient for the type in
+        question. 
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+shiftR\ ::\ a\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+Shift the first argument right by the specified number of bits
+        (which must be non-negative).
+        Right shifts perform sign extension on signed number types;
+        i.e. they fill the top bits with 1 if the \haddocktt{x} is negative
+        and with 0 otherwise.
+\par
+An instance can define either this and \haddockid{shiftL} or the unified
+        \haddockid{shift}, depending on which is more convenient for the type in
+        question. 
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+rotateL\ ::\ a\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+Rotate the argument left by the specified number of bits
+        (which must be non-negative).
+\par
+An instance can define either this and \haddockid{rotateR} or the unified
+        \haddockid{rotate}, depending on which is more convenient for the type in
+        question. 
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+rotateR\ ::\ a\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+Rotate the argument right by the specified number of bits
+        (which must be non-negative).
+\par
+An instance can define either this and \haddockid{rotateL} or the unified
+        \haddockid{rotate}, depending on which is more convenient for the type in
+        question. 
+\par
+
+\end{haddockdesc}
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bits\ Int\\instance\ Bits\ Int8\\instance\ Bits\ Int16\\instance\ Bits\ Int32\\instance\ Bits\ Int64\\instance\ Bits\ Integer\\instance\ Bits\ Word\\instance\ Bits\ Word8\\instance\ Bits\ Word16\\instance\ Bits\ Word32\\instance\ Bits\ Word64\\instance\ Bits\ WordPtr\\instance\ Bits\ IntPtr\\instance\ Bits\ CChar\\instance\ Bits\ CSChar\\instance\ Bits\ CUChar\\instance\ Bits\ CShort\\instance\ Bits\ CUShort\\instance\ Bits\ CInt\\instance\ Bits\ CUInt\\instance\ Bits\ CLong\\instance\ Bits\ CULong\\instance\ Bits\ CLLong\\instance\ Bits\ CULLong\\instance\ Bits\ CPtrdiff\\instance\ Bits\ CSize\\instance\ Bits\ CWchar\\instance\ Bits\ CSigAtomic\\instance\ Bits\ CIntPtr\\instance\ Bits\ CUIntPtr\\instance\ Bits\ CIntMax\\instance\ Bits\ CUIntMax
+\end{tabular}]
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Data-Char.tex b/report/libs/Data-Char.tex
new file mode 100644 (file)
index 0000000..2bf05d1
--- /dev/null
@@ -0,0 +1,472 @@
+\chapter{\texttt{Data.Char}}
+\label{module:Data.Char}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.Char (
+    Char,  String,  isControl,  isSpace,  isLower,  isUpper,  isAlpha, 
+    isAlphaNum,  isPrint,  isDigit,  isOctDigit,  isHexDigit,  isLetter, 
+    isMark,  isNumber,  isPunctuation,  isSymbol,  isSeparator,  isAscii, 
+    isLatin1,  isAsciiUpper,  isAsciiLower, 
+    GeneralCategory(UppercaseLetter,
+                    LowercaseLetter,
+                    TitlecaseLetter,
+                    ModifierLetter,
+                    OtherLetter,
+                    NonSpacingMark,
+                    SpacingCombiningMark,
+                    EnclosingMark,
+                    DecimalNumber,
+                    LetterNumber,
+                    OtherNumber,
+                    ConnectorPunctuation,
+                    DashPunctuation,
+                    OpenPunctuation,
+                    ClosePunctuation,
+                    InitialQuote,
+                    FinalQuote,
+                    OtherPunctuation,
+                    MathSymbol,
+                    CurrencySymbol,
+                    ModifierSymbol,
+                    OtherSymbol,
+                    Space,
+                    LineSeparator,
+                    ParagraphSeparator,
+                    Control,
+                    Format,
+                    Surrogate,
+                    PrivateUse,
+                    NotAssigned), 
+    generalCategory,  toUpper,  toLower,  toTitle,  digitToInt,  intToDigit, 
+    ord,  chr,  showLitChar,  lexLitChar,  readLitChar
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{Characters and strings
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Char
+\end{tabular}]\haddockbegindoc
+The character type \haddockid{Char} is an enumeration whose values represent
+Unicode (or equivalently ISO/IEC 10646) characters
+(see \url{http://www.unicode.org/} for details).
+This set extends the ISO 8859-1 (Latin-1) character set
+(the first 256 charachers), which is itself an extension of the ASCII
+character set (the first 128 characters).
+A character literal in Haskell has type \haddockid{Char}.
+\par
+To convert a \haddockid{Char} to or from the corresponding \haddockid{Int} value defined
+by Unicode, use \haddocktt{Prelude.toEnum} and \haddocktt{Prelude.fromEnum} from the
+\haddocktt{Prelude.Enum} class respectively (or equivalently \haddocktt{ord} and \haddocktt{chr}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ Char\\instance\ Ord\ Char\\instance\ Read\ Char\\instance\ Show\ Char\\instance\ Ix\ Char\\instance\ Storable\ Char
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ String\ =\ {\char 91}Char{\char 93}
+\end{tabular}]\haddockbegindoc
+A \haddockid{String} is a list of characters.  String constants in Haskell are values
+ of type \haddockid{String}.
+\par
+
+\end{haddockdesc}
+\section{Character classification
+}
+Unicode characters are divided into letters, numbers, marks,
+ punctuation, symbols, separators (including spaces) and others
+ (including control characters).
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isControl\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects control characters, which are the non-printing characters of
+ the Latin-1 subset of Unicode.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isSpace\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Returns \haddockid{True} for any Unicode space character, and the control
+ characters \haddocktt{{\char '134}t}, \haddocktt{{\char '134}n}, \haddocktt{{\char '134}r}, \haddocktt{{\char '134}f}, \haddocktt{{\char '134}v}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isLower\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects lower-case alphabetic Unicode characters (letters).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isUpper\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects upper-case or title-case alphabetic Unicode characters (letters).
+ Title case is used by a small number of letter ligatures like the
+ single-character form of \emph{Lj}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isAlpha\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects alphabetic Unicode characters (lower-case, upper-case and
+ title-case letters, plus letters of caseless scripts and modifiers letters).
+ This function is equivalent to \haddocktt{Data.Char.isLetter}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isAlphaNum\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects alphabetic or numeric digit Unicode characters.
+\par
+Note that numeric digits outside the ASCII range are selected by this
+ function but not by \haddockid{isDigit}.  Such digits may be part of identifiers
+ but are not used by the printer and reader to represent numbers.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isPrint\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects printable Unicode characters
+ (letters, numbers, marks, punctuation, symbols and spaces).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isDigit\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects ASCII digits, i.e. \haddocktt{'0'}..\haddocktt{'9'}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isOctDigit\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects ASCII octal digits, i.e. \haddocktt{'0'}..\haddocktt{'7'}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isHexDigit\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects ASCII hexadecimal digits,
+ i.e. \haddocktt{'0'}..\haddocktt{'9'}, \haddocktt{'a'}..\haddocktt{'f'}, \haddocktt{'A'}..\haddocktt{'F'}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isLetter\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects alphabetic Unicode characters (lower-case, upper-case and
+ title-case letters, plus letters of caseless scripts and modifiers letters).
+ This function is equivalent to \haddocktt{Data.Char.isAlpha}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isMark\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects Unicode mark characters, e.g. accents and the like, which
+ combine with preceding letters.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isNumber\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects Unicode numeric characters, including digits from various
+ scripts, Roman numerals, etc.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isPunctuation\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects Unicode punctuation characters, including various kinds
+ of connectors, brackets and quotes.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isSymbol\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects Unicode symbol characters, including mathematical and
+ currency symbols.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isSeparator\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects Unicode space and separator characters.
+\par
+
+\end{haddockdesc}
+\subsection{Subranges
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isAscii\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects the first 128 characters of the Unicode character set,
+ corresponding to the ASCII character set.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isLatin1\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects the first 256 characters of the Unicode character set,
+ corresponding to the ISO 8859-1 (Latin-1) character set.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isAsciiUpper\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects ASCII upper-case letters,
+ i.e. characters satisfying both \haddockid{isAscii} and \haddockid{isUpper}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isAsciiLower\ ::\ Char\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Selects ASCII lower-case letters,
+ i.e. characters satisfying both \haddockid{isAscii} and \haddockid{isLower}.
+\par
+
+\end{haddockdesc}
+\subsection{Unicode general categories
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ GeneralCategory
+\end{tabular}]\haddockbegindoc
+\haddockbeginconstrs
+\haddockdecltt{=} & \haddockdecltt{UppercaseLetter} & Lu: Letter, Uppercase
+ \\
+\haddockdecltt{|} & \haddockdecltt{LowercaseLetter} & Ll: Letter, Lowercase
+ \\
+\haddockdecltt{|} & \haddockdecltt{TitlecaseLetter} & Lt: Letter, Titlecase
+ \\
+\haddockdecltt{|} & \haddockdecltt{ModifierLetter} & Lm: Letter, Modifier
+ \\
+\haddockdecltt{|} & \haddockdecltt{OtherLetter} & Lo: Letter, Other
+ \\
+\haddockdecltt{|} & \haddockdecltt{NonSpacingMark} & Mn: Mark, Non-Spacing
+ \\
+\haddockdecltt{|} & \haddockdecltt{SpacingCombiningMark} & Mc: Mark, Spacing Combining
+ \\
+\haddockdecltt{|} & \haddockdecltt{EnclosingMark} & Me: Mark, Enclosing
+ \\
+\haddockdecltt{|} & \haddockdecltt{DecimalNumber} & Nd: Number, Decimal
+ \\
+\haddockdecltt{|} & \haddockdecltt{LetterNumber} & Nl: Number, Letter
+ \\
+\haddockdecltt{|} & \haddockdecltt{OtherNumber} & No: Number, Other
+ \\
+\haddockdecltt{|} & \haddockdecltt{ConnectorPunctuation} & Pc: Punctuation, Connector
+ \\
+\haddockdecltt{|} & \haddockdecltt{DashPunctuation} & Pd: Punctuation, Dash
+ \\
+\haddockdecltt{|} & \haddockdecltt{OpenPunctuation} & Ps: Punctuation, Open
+ \\
+\haddockdecltt{|} & \haddockdecltt{ClosePunctuation} & Pe: Punctuation, Close
+ \\
+\haddockdecltt{|} & \haddockdecltt{InitialQuote} & Pi: Punctuation, Initial quote
+ \\
+\haddockdecltt{|} & \haddockdecltt{FinalQuote} & Pf: Punctuation, Final quote
+ \\
+\haddockdecltt{|} & \haddockdecltt{OtherPunctuation} & Po: Punctuation, Other
+ \\
+\haddockdecltt{|} & \haddockdecltt{MathSymbol} & Sm: Symbol, Math
+ \\
+\haddockdecltt{|} & \haddockdecltt{CurrencySymbol} & Sc: Symbol, Currency
+ \\
+\haddockdecltt{|} & \haddockdecltt{ModifierSymbol} & Sk: Symbol, Modifier
+ \\
+\haddockdecltt{|} & \haddockdecltt{OtherSymbol} & So: Symbol, Other
+ \\
+\haddockdecltt{|} & \haddockdecltt{Space} & Zs: Separator, Space
+ \\
+\haddockdecltt{|} & \haddockdecltt{LineSeparator} & Zl: Separator, Line
+ \\
+\haddockdecltt{|} & \haddockdecltt{ParagraphSeparator} & Zp: Separator, Paragraph
+ \\
+\haddockdecltt{|} & \haddockdecltt{Control} & Cc: Other, Control
+ \\
+\haddockdecltt{|} & \haddockdecltt{Format} & Cf: Other, Format
+ \\
+\haddockdecltt{|} & \haddockdecltt{Surrogate} & Cs: Other, Surrogate
+ \\
+\haddockdecltt{|} & \haddockdecltt{PrivateUse} & Co: Other, Private Use
+ \\
+\haddockdecltt{|} & \haddockdecltt{NotAssigned} & Cn: Other, Not Assigned
+ \\
+\haddockendconstrs\par
+Unicode General Categories (column 2 of the UnicodeData table)
+ in the order they are listed in the Unicode standard.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ GeneralCategory\\instance\ Enum\ GeneralCategory\\instance\ Eq\ GeneralCategory\\instance\ Ord\ GeneralCategory\\instance\ Read\ GeneralCategory\\instance\ Show\ GeneralCategory\\instance\ Ix\ GeneralCategory
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+generalCategory\ ::\ Char\ ->\ GeneralCategory
+\end{tabular}]\haddockbegindoc
+The Unicode general category of the character.
+\par
+
+\end{haddockdesc}
+\section{Case conversion
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+toUpper\ ::\ Char\ ->\ Char
+\end{tabular}]\haddockbegindoc
+Convert a letter to the corresponding upper-case letter, if any.
+ Any other character is returned unchanged.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+toLower\ ::\ Char\ ->\ Char
+\end{tabular}]\haddockbegindoc
+Convert a letter to the corresponding lower-case letter, if any.
+ Any other character is returned unchanged.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+toTitle\ ::\ Char\ ->\ Char
+\end{tabular}]\haddockbegindoc
+Convert a letter to the corresponding title-case or upper-case
+ letter, if any.  (Title case differs from upper case only for a small
+ number of ligature letters.)
+ Any other character is returned unchanged.
+\par
+
+\end{haddockdesc}
+\section{Single digit characters
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+digitToInt\ ::\ Char\ ->\ Int
+\end{tabular}]\haddockbegindoc
+Convert a single digit \haddockid{Char} to the corresponding \haddockid{Int}.  
+ This function fails unless its argument satisfies \haddockid{isHexDigit},
+ but recognises both upper and lower-case hexadecimal digits
+ (i.e. \haddocktt{'0'}..\haddocktt{'9'}, \haddocktt{'a'}..\haddocktt{'f'}, \haddocktt{'A'}..\haddocktt{'F'}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+intToDigit\ ::\ Int\ ->\ Char
+\end{tabular}]\haddockbegindoc
+Convert an \haddockid{Int} in the range \haddocktt{0}..\haddocktt{15} to the corresponding single
+ digit \haddockid{Char}.  This function fails on other inputs, and generates
+ lower-case hexadecimal digits.
+\par
+
+\end{haddockdesc}
+\section{Numeric representations
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+ord\ ::\ Char\ ->\ Int
+\end{tabular}]\haddockbegindoc
+The \haddocktt{Prelude.fromEnum} method restricted to the type \haddocktt{Data.Char.Char}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+chr\ ::\ Int\ ->\ Char
+\end{tabular}]\haddockbegindoc
+The \haddocktt{Prelude.toEnum} method restricted to the type \haddocktt{Data.Char.Char}.
+\par
+
+\end{haddockdesc}
+\section{String representations
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+showLitChar\ ::\ Char\ ->\ ShowS
+\end{tabular}]\haddockbegindoc
+Convert a character to a string using only printable characters,
+ using Haskell source-language escape conventions.  For example:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ showLitChar '\n' s  =  "\\n" ++ s
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+lexLitChar\ ::\ ReadS\ String
+\end{tabular}]\haddockbegindoc
+Read a string representation of a character, using Haskell
+ source-language escape conventions.  For example:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ lexLitChar  "\\nHello"  =  [("\\n", "Hello")]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+readLitChar\ ::\ ReadS\ Char
+\end{tabular}]\haddockbegindoc
+Read a string representation of a character, using Haskell
+ source-language escape conventions, and convert it to the character
+ that it encodes.  For example:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ readLitChar "\\nHello"  =  [('\n', "Hello")]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Data-Complex.tex b/report/libs/Data-Complex.tex
new file mode 100644 (file)
index 0000000..1f59559
--- /dev/null
@@ -0,0 +1,207 @@
+\chapter{\texttt{Data.Complex}}
+\label{module:Data.Complex}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.Complex (
+    Complex(:+),  realPart,  imagPart,  mkPolar,  cis,  polar,  magnitude, 
+    phase,  conjugate
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{Rectangular form
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ RealFloat\ a\ =>\ Complex\ a
+\end{tabular}]\haddockbegindoc
+\haddockbeginconstrs
+\haddockdecltt{=} & \haddockdecltt{!a :+ !a} & forms a complex number from its real and imaginary
+ rectangular components.
+ \\
+\haddockendconstrs\par
+Complex numbers are an algebraic type.
+\par
+For a complex number \haddocktt{z}, \haddocktt{abs\ z} is a number with the magnitude of \haddocktt{z},
+ but oriented in the positive real direction, whereas \haddocktt{signum\ z}
+ has the phase of \haddocktt{z}, but unit magnitude.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Typeable1\ Complex\\instance\ RealFloat\ a\ =>\ Eq\ (Complex\ a)\\instance\ RealFloat\ a\ =>\ Floating\ (Complex\ a)\\instance\ RealFloat\ a\ =>\ Fractional\ (Complex\ a)\\instance\ (Data\ a,\ RealFloat\ a)\ =>\ Data\ (Complex\ a)\\instance\ RealFloat\ a\ =>\ Num\ (Complex\ a)\\instance\ (Read\ a,\ RealFloat\ a)\ =>\ Read\ (Complex\ a)\\instance\ RealFloat\ a\ =>\ Show\ (Complex\ a)
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+realPart\ ::\ RealFloat\ a\ =>\ Complex\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+Extracts the real part of a complex number.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+imagPart\ ::\ RealFloat\ a\ =>\ Complex\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+Extracts the imaginary part of a complex number.
+\par
+
+\end{haddockdesc}
+\section{Polar form
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mkPolar\ ::\ RealFloat\ a\ =>\ a\ ->\ a\ ->\ Complex\ a
+\end{tabular}]\haddockbegindoc
+Form a complex number from polar components of magnitude and phase.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+cis\ ::\ RealFloat\ a\ =>\ a\ ->\ Complex\ a
+\end{tabular}]\haddockbegindoc
+\haddocktt{cis\ t} is a complex value with magnitude \haddocktt{1}
+ and phase \haddocktt{t} (modulo \haddocktt{2*pi}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+polar\ ::\ RealFloat\ a\ =>\ Complex\ a\ ->\ (a,\ a)
+\end{tabular}]\haddockbegindoc
+The function \haddockid{polar} takes a complex number and
+ returns a (magnitude, phase) pair in canonical form:
+ the magnitude is nonnegative, and the phase in the range \haddocktt{(-pi,\ pi{\char 93}};
+ if the magnitude is zero, then so is the phase.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+magnitude\ ::\ RealFloat\ a\ =>\ Complex\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+The nonnegative magnitude of a complex number.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+phase\ ::\ RealFloat\ a\ =>\ Complex\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+The phase of a complex number, in the range \haddocktt{(-pi,\ pi{\char 93}}.
+ If the magnitude is zero, then so is the phase.
+\par
+
+\end{haddockdesc}
+\section{Conjugate
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+conjugate\ ::\ RealFloat\ a\ =>\ Complex\ a\ ->\ Complex\ a
+\end{tabular}]\haddockbegindoc
+The conjugate of a complex number.
+\par
+
+\end{haddockdesc}
+\section{Specification
+}
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ module Complex(Complex((:+)), realPart, imagPart, conjugate, mkPolar,
+                cis, polar, magnitude, phase)  where
+ infix  6  :+
+ data  (RealFloat a)     => Complex a = !a :+ !a  deriving (Eq,Read,Show)
+ realPart, imagPart :: (RealFloat a) => Complex a -> a
+ realPart (x:+y)        =  x
+ imagPart (x:+y)        =  y
+ conjugate      :: (RealFloat a) => Complex a -> Complex a
+ conjugate (x:+y) =  x :+ (-y)
+ mkPolar                :: (RealFloat a) => a -> a -> Complex a
+ mkPolar r theta        =  r * cos theta :+ r * sin theta
+ cis            :: (RealFloat a) => a -> Complex a
+ cis theta      =  cos theta :+ sin theta
+ polar          :: (RealFloat a) => Complex a -> (a,a)
+ polar z                =  (magnitude z, phase z)
+ magnitude :: (RealFloat a) => Complex a -> a
+ magnitude (x:+y) =  scaleFloat k
+                    (sqrt ((scaleFloat mk x)^2 + (scaleFloat mk y)^2))
+                   where k  = max (exponent x) (exponent y)
+                         mk = - k
+ phase :: (RealFloat a) => Complex a -> a
+ phase (0 :+ 0) = 0
+ phase (x :+ y) = atan2 y x
+ instance  (RealFloat a) => Num (Complex a)  where
+     (x:+y) + (x':+y') =  (x+x') :+ (y+y')
+     (x:+y) - (x':+y') =  (x-x') :+ (y-y')
+     (x:+y) * (x':+y') =  (x*x'-y*y') :+ (x*y'+y*x')
+     negate (x:+y)     =  negate x :+ negate y
+     abs z             =  magnitude z :+ 0
+     signum 0          =  0
+     signum z@(x:+y)   =  x/r :+ y/r  where r = magnitude z
+     fromInteger n     =  fromInteger n :+ 0
+ instance  (RealFloat a) => Fractional (Complex a)  where
+     (x:+y) / (x':+y') =  (x*x''+y*y'') / d :+ (y*x''-x*y'') / d
+                          where x'' = scaleFloat k x'
+                                y'' = scaleFloat k y'
+                                k   = - max (exponent x') (exponent y')
+                                d   = x'*x'' + y'*y''
+     fromRational a    =  fromRational a :+ 0
+ instance  (RealFloat a) => Floating (Complex a)       where
+     pi             =  pi :+ 0
+     exp (x:+y)     =  expx * cos y :+ expx * sin y
+                       where expx = exp x
+     log z          =  log (magnitude z) :+ phase z
+     sqrt 0         =  0
+     sqrt z@(x:+y)  =  u :+ (if y < 0 then -v else v)
+                       where (u,v) = if x < 0 then (v',u') else (u',v')
+                             v'    = abs y / (u'*2)
+                             u'    = sqrt ((magnitude z + abs x) / 2)
+     sin (x:+y)     =  sin x * cosh y :+ cos x * sinh y
+     cos (x:+y)     =  cos x * cosh y :+ (- sin x * sinh y)
+     tan (x:+y)     =  (sinx*coshy:+cosx*sinhy)/(cosx*coshy:+(-sinx*sinhy))
+                       where sinx  = sin x
+                             cosx  = cos x
+                             sinhy = sinh y
+                             coshy = cosh y
+     sinh (x:+y)    =  cos y * sinh x :+ sin  y * cosh x
+     cosh (x:+y)    =  cos y * cosh x :+ sin y * sinh x
+     tanh (x:+y)    =  (cosy*sinhx:+siny*coshx)/(cosy*coshx:+siny*sinhx)
+                       where siny  = sin y
+                             cosy  = cos y
+                             sinhx = sinh x
+                             coshx = cosh x
+     asin z@(x:+y)  =  y':+(-x')
+                       where  (x':+y') = log (((-y):+x) + sqrt (1 - z*z))
+     acos z@(x:+y)  =  y'':+(-x'')
+                       where (x'':+y'') = log (z + ((-y'):+x'))
+                             (x':+y')   = sqrt (1 - z*z)
+     atan z@(x:+y)  =  y':+(-x')
+                       where (x':+y') = log (((1-y):+x) / sqrt (1+z*z))
+     asinh z        =  log (z + sqrt (1+z*z))
+     acosh z        =  log (z + (z+1) * sqrt ((z-1)/(z+1)))
+     atanh z        =  log ((1+z) / sqrt (1-z*z))
+\end{verbatim}}
+\end{quote}
diff --git a/report/libs/Data-Int.tex b/report/libs/Data-Int.tex
new file mode 100644 (file)
index 0000000..0b78187
--- /dev/null
@@ -0,0 +1,100 @@
+\chapter{\texttt{Data.Int}}
+\label{module:Data.Int}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.Int (
+    Int,  Int8,  Int16,  Int32,  Int64
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{Signed integer types
+}
+This module provides signed integer types of unspecified width (\haddockid{Int})
+and fixed widths (\haddockid{Int8}, \haddockid{Int16}, \haddockid{Int32} and \haddockid{Int64}).  All
+arithmetic is performed modulo 2{\char '136}n, where \haddocktt{n} is the number of bits in
+the type.
+\par
+For coercing between any two integer types, use
+\haddockid{fromIntegral}.  Coercing word types (see \haddocktt{Data.Word}) to and
+from integer types preserves representation, not sign.
+\par
+The rules that hold for \haddockid{Enum} instances over a bounded type
+such as \haddockid{Int} (see the section of the Haskell report dealing with
+arithmetic sequences) also hold for the \haddockid{Enum} instances over
+the various \haddockid{Int} types defined here.
+\par
+Right and left shifts by amounts greater than or equal to the width of
+the type result in either zero or -1, depending on the sign of the
+value being shifted.  This is contrary to the behaviour in C, which is
+undefined; a common interpretation is to truncate the shift count to
+the width of the type, for example \haddocktt{1\ <<\ 32\ ==\ 1} in some C
+implementations.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Int
+\end{tabular}]\haddockbegindoc
+A fixed-precision integer type with at least the range \haddocktt{{\char 91}-2{\char '136}29\ ..\ 2{\char '136}29-1{\char 93}}.
+ The exact range for a given implementation can be determined by using
+ \haddocktt{Prelude.minBound} and \haddocktt{Prelude.maxBound} from the \haddocktt{Prelude.Bounded} class.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ Int\\instance\ Integral\ Int\\instance\ Num\ Int\\instance\ Ord\ Int\\instance\ Read\ Int\\instance\ Real\ Int\\instance\ Show\ Int\\instance\ Ix\ Int\\instance\ Storable\ Int\\instance\ Bits\ Int
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Int8
+\end{tabular}]\haddockbegindoc
+8-bit signed integer type
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ Int8\\instance\ Enum\ Int8\\instance\ Eq\ Int8\\instance\ Integral\ Int8\\instance\ Num\ Int8\\instance\ Ord\ Int8\\instance\ Read\ Int8\\instance\ Real\ Int8\\instance\ Show\ Int8\\instance\ Ix\ Int8\\instance\ Storable\ Int8\\instance\ Bits\ Int8
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Int16
+\end{tabular}]\haddockbegindoc
+16-bit signed integer type
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ Int16\\instance\ Enum\ Int16\\instance\ Eq\ Int16\\instance\ Integral\ Int16\\instance\ Num\ Int16\\instance\ Ord\ Int16\\instance\ Read\ Int16\\instance\ Real\ Int16\\instance\ Show\ Int16\\instance\ Ix\ Int16\\instance\ Storable\ Int16\\instance\ Bits\ Int16
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Int32
+\end{tabular}]\haddockbegindoc
+32-bit signed integer type
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ Int32\\instance\ Enum\ Int32\\instance\ Eq\ Int32\\instance\ Integral\ Int32\\instance\ Num\ Int32\\instance\ Ord\ Int32\\instance\ Read\ Int32\\instance\ Real\ Int32\\instance\ Show\ Int32\\instance\ Ix\ Int32\\instance\ Storable\ Int32\\instance\ Bits\ Int32
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Int64
+\end{tabular}]\haddockbegindoc
+64-bit signed integer type
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ Int64\\instance\ Enum\ Int64\\instance\ Eq\ Int64\\instance\ Integral\ Int64\\instance\ Num\ Int64\\instance\ Ord\ Int64\\instance\ Read\ Int64\\instance\ Real\ Int64\\instance\ Show\ Int64\\instance\ Ix\ Int64\\instance\ Storable\ Int64\\instance\ Bits\ Int64
+\end{tabular}]
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Data-Ix.tex b/report/libs/Data-Ix.tex
new file mode 100644 (file)
index 0000000..433303d
--- /dev/null
@@ -0,0 +1,154 @@
+\chapter{\texttt{Data.Ix}}
+\label{module:Data.Ix}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.Ix (
+    Ix(range, index, inRange, rangeSize)
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{The \haddockid{Ix} class
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+class\ Ord\ a\ =>\ Ix\ a\ where
+\end{tabular}]\haddockbegindoc
+The \haddockid{Ix} class is used to map a contiguous subrange of values in
+ a type onto integers.  It is used primarily for array indexing
+ (see the array package).
+\par
+The first argument \haddocktt{(l,u)} of each of these operations is a pair
+ specifying the lower and upper bounds of a contiguous subrange of values.
+\par
+An implementation is entitled to assume the following laws about these
+ operations:
+\par
+\begin{itemize}
+\item
+\begin{quote}
+{\haddockverb\begin{verbatim}
+inRange (l,u) i == elem i (range (l,u))\end{verbatim}}
+\end{quote}
+
+\item
+ \haddocktt{range\ (l,u)\ !!\ index\ (l,u)\ i\ ==\ i}, when \haddocktt{inRange\ (l,u)\ i}
+\par
+
+\item
+\begin{quote}
+{\haddockverb\begin{verbatim}
+map (index (l,u)) (range (l,u))) == [0..rangeSize (l,u)-1]\end{verbatim}}
+\end{quote}
+
+\item
+\begin{quote}
+{\haddockverb\begin{verbatim}
+rangeSize (l,u) == length (range (l,u))\end{verbatim}}
+\end{quote}
+
+\end{itemize}
+Minimal complete instance: \haddockid{range}, \haddockid{index} and \haddockid{inRange}.
+\par
+
+\haddockpremethods{}\textbf{Methods}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+range\ ::\ (a,\ a)\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The list of values in the subrange defined by a bounding pair.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+index\ ::\ (a,\ a)\ ->\ a\ ->\ Int
+\end{tabular}]\haddockbegindoc
+The position of a subscript in the subrange.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+inRange\ ::\ (a,\ a)\ ->\ a\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Returns \haddockid{True} the given subscript lies in the range defined
+ the bounding pair.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+rangeSize\ ::\ (a,\ a)\ ->\ Int
+\end{tabular}]\haddockbegindoc
+The size of the subrange defined by a bounding pair.
+\par
+
+\end{haddockdesc}
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Ix\ Bool\\instance\ Ix\ Char\\instance\ Ix\ Int\\instance\ Ix\ Int8\\instance\ Ix\ Int16\\instance\ Ix\ Int32\\instance\ Ix\ Int64\\instance\ Ix\ Integer\\instance\ Ix\ Ordering\\instance\ Ix\ Word\\instance\ Ix\ Word8\\instance\ Ix\ Word16\\instance\ Ix\ Word32\\instance\ Ix\ Word64\\instance\ Ix\ ()\\instance\ Ix\ GeneralCategory\\instance\ Ix\ SeekMode\\instance\ Ix\ IOMode\\instance\ (Ix\ a,\ Ix\ b)\ =>\ Ix\ (a,\ b)\\instance\ (Ix\ a1,\ Ix\ a2,\ Ix\ a3)\ =>\ Ix\ (a1,\ a2,\ a3)\\instance\ (Ix\ a1,\ Ix\ a2,\ Ix\ a3,\ Ix\ a4)\ =>\ Ix\ (a1,\ a2,\ a3,\ a4)\\instance\ (Ix\ a1,\ Ix\ a2,\ Ix\ a3,\ Ix\ a4,\ Ix\ a5)\ =>\ Ix\ (a1,\ a2,\ a3,\ a4,\ a5)
+\end{tabular}]
+\end{haddockdesc}
+\section{Deriving Instances of \haddocktt{Ix}
+}
+It is possible to derive an instance of \haddocktt{Ix} automatically, using
+a \haddocktt{deriving} clause on a \haddocktt{data} declaration.
+Such derived instance declarations for the class \haddocktt{Ix} are only possible
+for enumerations (i.e. datatypes having
+only nullary constructors) and single-constructor datatypes,
+whose constituent types are instances of \haddocktt{Ix}.   A Haskell implementation
+must provide \haddocktt{Ix} instances for tuples up to at least size 15.
+\par
+For an \emph{enumeration}, the nullary constructors are assumed to be
+numbered left-to-right with the indices being 0 to n-1 inclusive.
+This is the same numbering defined by the \haddocktt{Enum} class.  For example,
+given the datatype:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ data Colour = Red | Orange | Yellow | Green | Blue | Indigo | Violet
+\end{verbatim}}
+\end{quote}
+we would have:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ range   (Yellow,Blue)        ==  [Yellow,Green,Blue]
+ index   (Yellow,Blue) Green  ==  1
+ inRange (Yellow,Blue) Red    ==  False
+\end{verbatim}}
+\end{quote}
+For \emph{single-constructor datatypes}, the derived instance declarations
+are as shown for tuples:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ instance  (Ix a, Ix b)  => Ix (a,b) where
+         range ((l,l'),(u,u'))
+                 = [(i,i') | i <- range (l,u), i' <- range (l',u')]
+         index ((l,l'),(u,u')) (i,i')
+                 =  index (l,u) i * rangeSize (l',u') + index (l',u') i'
+         inRange ((l,l'),(u,u')) (i,i')
+                 = inRange (l,u) i && inRange (l',u') i'
+ -- Instances for other tuples are obtained from this scheme:
+ --
+ --  instance  (Ix a1, Ix a2, ... , Ix ak) => Ix (a1,a2,...,ak)  where
+ --      range ((l1,l2,...,lk),(u1,u2,...,uk)) =
+ --          [(i1,i2,...,ik) | i1 <- range (l1,u1),
+ --                            i2 <- range (l2,u2),
+ --                            ...
+ --                            ik <- range (lk,uk)]
+ --
+ --      index ((l1,l2,...,lk),(u1,u2,...,uk)) (i1,i2,...,ik) =
+ --        index (lk,uk) ik + rangeSize (lk,uk) * (
+ --         index (lk-1,uk-1) ik-1 + rangeSize (lk-1,uk-1) * (
+ --          ...
+ --           index (l1,u1)))
+ --
+ --      inRange ((l1,l2,...lk),(u1,u2,...,uk)) (i1,i2,...,ik) =
+ --          inRange (l1,u1) i1 && inRange (l2,u2) i2 &&
+ --              ... && inRange (lk,uk) ik
+\end{verbatim}}
+\end{quote}
diff --git a/report/libs/Data-List.tex b/report/libs/Data-List.tex
new file mode 100644 (file)
index 0000000..e838c8e
--- /dev/null
@@ -0,0 +1,1386 @@
+\chapter{\texttt{Data.List}}
+\label{module:Data.List}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.List (
+    (++),  head,  last,  tail,  init,  null,  length,  map,  reverse, 
+    intersperse,  intercalate,  transpose,  subsequences,  permutations, 
+    foldl,  foldl',  foldl1,  foldl1',  foldr,  foldr1,  concat,  concatMap, 
+    and,  or,  any,  all,  sum,  product,  maximum,  minimum,  scanl,  scanl1, 
+    scanr,  scanr1,  mapAccumL,  mapAccumR,  iterate,  repeat,  replicate, 
+    cycle,  unfoldr,  take,  drop,  splitAt,  takeWhile,  dropWhile,  span, 
+    break,  stripPrefix,  group,  inits,  tails,  isPrefixOf,  isSuffixOf, 
+    isInfixOf,  elem,  notElem,  lookup,  find,  filter,  partition,  (!!), 
+    elemIndex,  elemIndices,  findIndex,  findIndices,  zip,  zip3,  zip4, 
+    zip5,  zip6,  zip7,  zipWith,  zipWith3,  zipWith4,  zipWith5,  zipWith6, 
+    zipWith7,  unzip,  unzip3,  unzip4,  unzip5,  unzip6,  unzip7,  lines, 
+    words,  unlines,  unwords,  nub,  delete,  (\\),  union,  intersect,  sort, 
+    insert,  nubBy,  deleteBy,  deleteFirstsBy,  unionBy,  intersectBy, 
+    groupBy,  sortBy,  insertBy,  maximumBy,  minimumBy,  genericLength, 
+    genericTake,  genericDrop,  genericSplitAt,  genericIndex,  genericReplicate
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{Basic functions
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(++)\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+Append two lists, i.e.,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
+ [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
+\end{verbatim}}
+\end{quote}
+If the first list is not finite, the result is the first list.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+head\ ::\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+Extract the first element of a list, which must be non-empty.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+last\ ::\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+Extract the last element of a list, which must be finite and non-empty.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+tail\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+Extract the elements after the head of a list, which must be non-empty.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+init\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+Return all the elements of a list except the last one.
+ The list must be non-empty.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+null\ ::\ {\char 91}a{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Test whether a list is empty.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+length\ ::\ {\char 91}a{\char 93}\ ->\ Int
+\end{tabular}]\haddockbegindoc
+\emph{O(n)}. \haddockid{length} returns the length of a finite list as an \haddockid{Int}.
+ It is an instance of the more general \haddocktt{Data.List.genericLength},
+ the result type of which may be any kind of number.
+\par
+
+\end{haddockdesc}
+\section{List transformations
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+map\ ::\ (a\ ->\ b)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{map} \haddocktt{f\ xs} is the list obtained by applying \haddocktt{f} to each element
+ of \haddocktt{xs}, i.e.,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
+ map f [x1, x2, ...] == [f x1, f x2, ...]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+reverse\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{reverse} \haddocktt{xs} returns the elements of \haddocktt{xs} in reverse order.
+ \haddocktt{xs} must be finite.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+intersperse\ ::\ a\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{intersperse} function takes an element and a list and
+ `intersperses' that element between the elements of the list.
+ For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ intersperse ',' "abcde" == "a,b,c,d,e"
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+intercalate\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}{\char 91}a{\char 93}{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{intercalate} \haddocktt{xs\ xss} is equivalent to \haddocktt{(concat\ (intersperse\ xs\ xss))}.
+ It inserts the list \haddocktt{xs} in between the lists in \haddocktt{xss} and concatenates the
+ result.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+transpose\ ::\ {\char 91}{\char 91}a{\char 93}{\char 93}\ ->\ {\char 91}{\char 91}a{\char 93}{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{transpose} function transposes the rows and columns of its argument.
+ For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ transpose [[1,2,3],[4,5,6]] == [[1,4],[2,5],[3,6]]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+subsequences\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}{\char 91}a{\char 93}{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{subsequences} function returns the list of all subsequences of the argument.
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ subsequences "abc" == ["","a","b","ab","c","ac","bc","abc"]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+permutations\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}{\char 91}a{\char 93}{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{permutations} function returns the list of all permutations of the argument.
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ permutations "abc" == ["abc","bac","cba","bca","cab","acb"]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\section{Reducing lists (folds)
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+foldl\ ::\ (a\ ->\ b\ ->\ a)\ ->\ a\ ->\ {\char 91}b{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddockid{foldl}, applied to a binary operator, a starting value (typically
+ the left-identity of the operator), and a list, reduces the list
+ using the binary operator, from left to right:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn
+\end{verbatim}}
+\end{quote}
+The list must be finite.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+foldl'\ ::\ (a\ ->\ b\ ->\ a)\ ->\ a\ ->\ {\char 91}b{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+A strict version of \haddockid{foldl}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+foldl1\ ::\ (a\ ->\ a\ ->\ a)\ ->\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddockid{foldl1} is a variant of \haddockid{foldl} that has no starting value argument,
+ and thus must be applied to non-empty lists.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+foldl1'\ ::\ (a\ ->\ a\ ->\ a)\ ->\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+A strict version of \haddockid{foldl1}
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+foldr\ ::\ (a\ ->\ b\ ->\ b)\ ->\ b\ ->\ {\char 91}a{\char 93}\ ->\ b
+\end{tabular}]\haddockbegindoc
+\haddockid{foldr}, applied to a binary operator, a starting value (typically
+ the right-identity of the operator), and a list, reduces the list
+ using the binary operator, from right to left:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+foldr1\ ::\ (a\ ->\ a\ ->\ a)\ ->\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddockid{foldr1} is a variant of \haddockid{foldr} that has no starting value argument,
+ and thus must be applied to non-empty lists.
+\par
+
+\end{haddockdesc}
+\subsection{Special folds
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+concat\ ::\ {\char 91}{\char 91}a{\char 93}{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+Concatenate a list of lists.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+concatMap\ ::\ (a\ ->\ {\char 91}b{\char 93})\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}
+\end{tabular}]\haddockbegindoc
+Map a function over a list and concatenate the results.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+and\ ::\ {\char 91}Bool{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+\haddockid{and} returns the conjunction of a Boolean list.  For the result to be
+ \haddockid{True}, the list must be finite; \haddockid{False}, however, results from a \haddockid{False}
+ value at a finite index of a finite or infinite list.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+or\ ::\ {\char 91}Bool{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+\haddockid{or} returns the disjunction of a Boolean list.  For the result to be
+ \haddockid{False}, the list must be finite; \haddockid{True}, however, results from a \haddockid{True}
+ value at a finite index of a finite or infinite list.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+any\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Applied to a predicate and a list, \haddockid{any} determines if any element
+ of the list satisfies the predicate.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+all\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Applied to a predicate and a list, \haddockid{all} determines if all elements
+ of the list satisfy the predicate.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+sum\ ::\ Num\ a\ =>\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{sum} function computes the sum of a finite list of numbers.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+product\ ::\ Num\ a\ =>\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{product} function computes the product of a finite list of numbers.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+maximum\ ::\ Ord\ a\ =>\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddockid{maximum} returns the maximum value from a list,
+ which must be non-empty, finite, and of an ordered type.
+ It is a special case of \haddockid{maximumBy}, which allows the
+ programmer to supply their own comparison function.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+minimum\ ::\ Ord\ a\ =>\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+\haddockid{minimum} returns the minimum value from a list,
+ which must be non-empty, finite, and of an ordered type.
+ It is a special case of \haddockid{minimumBy}, which allows the
+ programmer to supply their own comparison function.
+\par
+
+\end{haddockdesc}
+\section{Building lists
+}
+\subsection{Scans
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+scanl\ ::\ (a\ ->\ b\ ->\ a)\ ->\ a\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{scanl} is similar to \haddockid{foldl}, but returns a list of successive
+ reduced values from the left:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
+\end{verbatim}}
+\end{quote}
+Note that
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ last (scanl f z xs) == foldl f z xs.
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+scanl1\ ::\ (a\ ->\ a\ ->\ a)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{scanl1} is a variant of \haddockid{scanl} that has no starting value argument:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+scanr\ ::\ (a\ ->\ b\ ->\ b)\ ->\ b\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{scanr} is the right-to-left dual of \haddockid{scanl}.
+ Note that
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ head (scanr f z xs) == foldr f z xs.
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+scanr1\ ::\ (a\ ->\ a\ ->\ a)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{scanr1} is a variant of \haddockid{scanr} that has no starting value argument.
+\par
+
+\end{haddockdesc}
+\subsection{Accumulating maps
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mapAccumL\ ::\ (acc\ ->\ x\ ->\ (acc,\ y))\ ->\ acc\ ->\ {\char 91}x{\char 93}\ ->\ (acc,\ {\char 91}y{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{mapAccumL} function behaves like a combination of \haddockid{map} and
+ \haddockid{foldl}; it applies a function to each element of a list, passing
+ an accumulating parameter from left to right, and returning a final
+ value of this accumulator together with the new list.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mapAccumR\ ::\ (acc\ ->\ x\ ->\ (acc,\ y))\ ->\ acc\ ->\ {\char 91}x{\char 93}\ ->\ (acc,\ {\char 91}y{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{mapAccumR} function behaves like a combination of \haddockid{map} and
+ \haddockid{foldr}; it applies a function to each element of a list, passing
+ an accumulating parameter from right to left, and returning a final
+ value of this accumulator together with the new list.
+\par
+
+\end{haddockdesc}
+\subsection{Infinite lists
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+iterate\ ::\ (a\ ->\ a)\ ->\ a\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{iterate} \haddocktt{f\ x} returns an infinite list of repeated applications
+ of \haddocktt{f} to \haddocktt{x}:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ iterate f x == [x, f x, f (f x), ...]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+repeat\ ::\ a\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{repeat} \haddocktt{x} is an infinite list, with \haddocktt{x} the value of every element.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+replicate\ ::\ Int\ ->\ a\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{replicate} \haddocktt{n\ x} is a list of length \haddocktt{n} with \haddocktt{x} the value of
+ every element.
+ It is an instance of the more general \haddocktt{Data.List.genericReplicate},
+ in which \haddocktt{n} may be of any integral type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+cycle\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{cycle} ties a finite list into a circular one, or equivalently,
+ the infinite repetition of the original list.  It is the identity
+ on infinite lists.
+\par
+
+\end{haddockdesc}
+\subsection{Unfolding
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unfoldr\ ::\ (b\ ->\ Maybe\ (a,\ b))\ ->\ b\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{unfoldr} function is a `dual' to \haddockid{foldr}: while \haddockid{foldr}
+ reduces a list to a summary value, \haddockid{unfoldr} builds a list from
+ a seed value.  The function takes the element and returns \haddockid{Nothing}
+ if it is done producing the list or returns \haddockid{Just} \haddocktt{(a,b)}, in which
+ case, \haddocktt{a} is a prepended to the list and \haddocktt{b} is used as the next
+ element in a recursive call.  For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ iterate f == unfoldr (\x -> Just (x, f x))
+\end{verbatim}}
+\end{quote}
+In some cases, \haddockid{unfoldr} can undo a \haddockid{foldr} operation:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ unfoldr f' (foldr f z xs) == xs
+\end{verbatim}}
+\end{quote}
+if the following holds:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ f' (f x y) = Just (x,y)
+ f' z       = Nothing
+\end{verbatim}}
+\end{quote}
+A simple use of unfoldr:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ unfoldr (\b -> if b == 0 then Nothing else Just (b, b-1)) 10
+  [10,9,8,7,6,5,4,3,2,1]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\section{Sublists
+}
+\subsection{Extracting sublists
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+take\ ::\ Int\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{take} \haddocktt{n}, applied to a list \haddocktt{xs}, returns the prefix of \haddocktt{xs}
+ of length \haddocktt{n}, or \haddocktt{xs} itself if \haddocktt{n\ >\ length\ xs}:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ take 5 "Hello World!" == "Hello"
+ take 3 [1,2,3,4,5] == [1,2,3]
+ take 3 [1,2] == [1,2]
+ take 3 [] == []
+ take (-1) [1,2] == []
+ take 0 [1,2] == []
+\end{verbatim}}
+\end{quote}
+It is an instance of the more general \haddocktt{Data.List.genericTake},
+ in which \haddocktt{n} may be of any integral type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+drop\ ::\ Int\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{drop} \haddocktt{n\ xs} returns the suffix of \haddocktt{xs}
+ after the first \haddocktt{n} elements, or \haddocktt{{\char 91}{\char 93}} if \haddocktt{n\ >\ length\ xs}:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ drop 6 "Hello World!" == "World!"
+ drop 3 [1,2,3,4,5] == [4,5]
+ drop 3 [1,2] == []
+ drop 3 [] == []
+ drop (-1) [1,2] == [1,2]
+ drop 0 [1,2] == [1,2]
+\end{verbatim}}
+\end{quote}
+It is an instance of the more general \haddocktt{Data.List.genericDrop},
+ in which \haddocktt{n} may be of any integral type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+splitAt\ ::\ Int\ ->\ {\char 91}a{\char 93}\ ->\ ({\char 91}a{\char 93},\ {\char 91}a{\char 93})
+\end{tabular}]\haddockbegindoc
+\haddockid{splitAt} \haddocktt{n\ xs} returns a tuple where first element is \haddocktt{xs} prefix of
+ length \haddocktt{n} and second element is the remainder of the list:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ splitAt 6 "Hello World!" == ("Hello ","World!")
+ splitAt 3 [1,2,3,4,5] == ([1,2,3],[4,5])
+ splitAt 1 [1,2,3] == ([1],[2,3])
+ splitAt 3 [1,2,3] == ([1,2,3],[])
+ splitAt 4 [1,2,3] == ([1,2,3],[])
+ splitAt 0 [1,2,3] == ([],[1,2,3])
+ splitAt (-1) [1,2,3] == ([],[1,2,3])
+\end{verbatim}}
+\end{quote}
+It is equivalent to \haddocktt{(take\ n\ xs,\ drop\ n\ xs)}.
+ \haddockid{splitAt} is an instance of the more general \haddocktt{Data.List.genericSplitAt},
+ in which \haddocktt{n} may be of any integral type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+takeWhile\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{takeWhile}, applied to a predicate \haddocktt{p} and a list \haddocktt{xs}, returns the
+ longest prefix (possibly empty) of \haddocktt{xs} of elements that satisfy \haddocktt{p}:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ takeWhile (< 3) [1,2,3,4,1,2,3,4] == [1,2]
+ takeWhile (< 9) [1,2,3] == [1,2,3]
+ takeWhile (< 0) [1,2,3] == []
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+dropWhile\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{dropWhile} \haddocktt{p\ xs} returns the suffix remaining after \haddockid{takeWhile} \haddocktt{p\ xs}:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ dropWhile (< 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
+ dropWhile (< 9) [1,2,3] == []
+ dropWhile (< 0) [1,2,3] == [1,2,3]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+span\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ ({\char 91}a{\char 93},\ {\char 91}a{\char 93})
+\end{tabular}]\haddockbegindoc
+\haddockid{span}, applied to a predicate \haddocktt{p} and a list \haddocktt{xs}, returns a tuple where
+ first element is longest prefix (possibly empty) of \haddocktt{xs} of elements that
+ satisfy \haddocktt{p} and second element is the remainder of the list:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ span (< 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4])
+ span (< 9) [1,2,3] == ([1,2,3],[])
+ span (< 0) [1,2,3] == ([],[1,2,3])
+\end{verbatim}}
+\end{quote}
+\haddockid{span} \haddocktt{p\ xs} is equivalent to \haddocktt{(takeWhile\ p\ xs,\ dropWhile\ p\ xs)}
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+break\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ ({\char 91}a{\char 93},\ {\char 91}a{\char 93})
+\end{tabular}]\haddockbegindoc
+\haddockid{break}, applied to a predicate \haddocktt{p} and a list \haddocktt{xs}, returns a tuple where
+ first element is longest prefix (possibly empty) of \haddocktt{xs} of elements that
+ \emph{do not satisfy} \haddocktt{p} and second element is the remainder of the list:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ break (> 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
+ break (< 9) [1,2,3] == ([],[1,2,3])
+ break (> 9) [1,2,3] == ([1,2,3],[])
+\end{verbatim}}
+\end{quote}
+\haddockid{break} \haddocktt{p} is equivalent to \haddocktt{span\ (not\ .\ p)}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+stripPrefix\ ::\ Eq\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ Maybe\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{stripPrefix} function drops the given prefix from a list.
+ It returns \haddockid{Nothing} if the list did not start with the prefix
+ given, or \haddockid{Just} the list after the prefix, if it does.
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ stripPrefix "foo" "foobar" -> Just "bar"
+ stripPrefix "foo" "foo" -> Just ""
+ stripPrefix "foo" "barfoo" -> Nothing
+ stripPrefix "foo" "barfoobaz" -> Nothing
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+group\ ::\ Eq\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}{\char 91}a{\char 93}{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{group} function takes a list and returns a list of lists such
+ that the concatenation of the result is equal to the argument.  Moreover,
+ each sublist in the result contains only equal elements.  For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
+\end{verbatim}}
+\end{quote}
+It is a special case of \haddockid{groupBy}, which allows the programmer to supply
+ their own equality test.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+inits\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}{\char 91}a{\char 93}{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{inits} function returns all initial segments of the argument,
+ shortest first.  For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ inits "abc" == ["","a","ab","abc"]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+tails\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}{\char 91}a{\char 93}{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{tails} function returns all final segments of the argument,
+ longest first.  For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ tails "abc" == ["abc", "bc", "c",""]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\subsection{Predicates
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isPrefixOf\ ::\ Eq\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+The \haddockid{isPrefixOf} function takes two lists and returns \haddockid{True}
+ iff the first list is a prefix of the second.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isSuffixOf\ ::\ Eq\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+The \haddockid{isSuffixOf} function takes two lists and returns \haddockid{True}
+ iff the first list is a suffix of the second.
+ Both lists must be finite.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isInfixOf\ ::\ Eq\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+The \haddockid{isInfixOf} function takes two lists and returns \haddockid{True}
+ iff the first list is contained, wholly and intact,
+ anywhere within the second.
+\par
+Example:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+isInfixOf "Haskell" "I really like Haskell." -> True
+isInfixOf "Ial" "I really like Haskell." -> False
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\section{Searching lists
+}
+\subsection{Searching by equality
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+elem\ ::\ Eq\ a\ =>\ a\ ->\ {\char 91}a{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+\haddockid{elem} is the list membership predicate, usually written in infix form,
+ e.g., \haddocktt{x\ `elem`\ xs}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+notElem\ ::\ Eq\ a\ =>\ a\ ->\ {\char 91}a{\char 93}\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+\haddockid{notElem} is the negation of \haddockid{elem}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+lookup\ ::\ Eq\ a\ =>\ a\ ->\ {\char 91}(a,\ b){\char 93}\ ->\ Maybe\ b
+\end{tabular}]\haddockbegindoc
+\haddockid{lookup} \haddocktt{key\ assocs} looks up a key in an association list.
+\par
+
+\end{haddockdesc}
+\subsection{Searching with a predicate
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+find\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ Maybe\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{find} function takes a predicate and a list and returns the
+ first element in the list matching the predicate, or \haddockid{Nothing} if
+ there is no such element.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+filter\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{filter}, applied to a predicate and a list, returns the list of
+ those elements that satisfy the predicate; i.e.,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ filter p xs = [ x | x <- xs, p x]
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+partition\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ ({\char 91}a{\char 93},\ {\char 91}a{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{partition} function takes a predicate a list and returns
+ the pair of lists of elements which do and do not satisfy the
+ predicate, respectively; i.e.,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ partition p xs == (filter p xs, filter (not . p) xs)
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\section{Indexing lists
+}
+These functions treat a list \haddocktt{xs} as a indexed collection,
+ with indices ranging from 0 to \haddocktt{length\ xs\ -\ 1}.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+(!!)\ ::\ {\char 91}a{\char 93}\ ->\ Int\ ->\ a
+\end{tabular}]\haddockbegindoc
+List index (subscript) operator, starting from 0.
+ It is an instance of the more general \haddocktt{Data.List.genericIndex},
+ which takes an index of any integral type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+elemIndex\ ::\ Eq\ a\ =>\ a\ ->\ {\char 91}a{\char 93}\ ->\ Maybe\ Int
+\end{tabular}]\haddockbegindoc
+The \haddockid{elemIndex} function returns the index of the first element
+ in the given list which is equal (by \haddockid{==}) to the query element,
+ or \haddockid{Nothing} if there is no such element.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+elemIndices\ ::\ Eq\ a\ =>\ a\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}Int{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{elemIndices} function extends \haddockid{elemIndex}, by returning the
+ indices of all elements equal to the query element, in ascending order.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+findIndex\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ Maybe\ Int
+\end{tabular}]\haddockbegindoc
+The \haddockid{findIndex} function takes a predicate and a list and returns
+ the index of the first element in the list satisfying the predicate,
+ or \haddockid{Nothing} if there is no such element.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+findIndices\ ::\ (a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}Int{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{findIndices} function extends \haddockid{findIndex}, by returning the
+ indices of all elements satisfying the predicate, in ascending order.
+\par
+
+\end{haddockdesc}
+\section{Zipping and unzipping lists
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zip\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}(a,\ b){\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{zip} takes two lists and returns a list of corresponding pairs.
+ If one input list is short, excess elements of the longer list are
+ discarded.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zip3\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}(a,\ b,\ c){\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{zip3} takes three lists and returns a list of triples, analogous to
+ \haddockid{zip}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zip4\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}d{\char 93}\ ->\ {\char 91}(a,\ b,\ c,\ d){\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zip4} function takes four lists and returns a list of
+ quadruples, analogous to \haddockid{zip}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zip5\ ::\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}d{\char 93}\ ->\ {\char 91}e{\char 93}\ ->\ {\char 91}(a,\ b,\ c,\ d,\ e){\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zip5} function takes five lists and returns a list of
+ five-tuples, analogous to \haddockid{zip}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zip6\ ::\ {\char 91}a{\char 93}\\\ \ \ \ \ \ \ \ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}d{\char 93}\ ->\ {\char 91}e{\char 93}\ ->\ {\char 91}f{\char 93}\ ->\ {\char 91}(a,\ b,\ c,\ d,\ e,\ f){\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zip6} function takes six lists and returns a list of six-tuples,
+ analogous to \haddockid{zip}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zip7\ ::\ {\char 91}a{\char 93}\\\ \ \ \ \ \ \ \ ->\ {\char 91}b{\char 93}\\\ \ \ \ \ \ \ \ \ \ \ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}d{\char 93}\ ->\ {\char 91}e{\char 93}\ ->\ {\char 91}f{\char 93}\ ->\ {\char 91}g{\char 93}\ ->\ {\char 91}(a,\ b,\ c,\ d,\ e,\ f,\ g){\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zip7} function takes seven lists and returns a list of
+ seven-tuples, analogous to \haddockid{zip}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zipWith\ ::\ (a\ ->\ b\ ->\ c)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{zipWith} generalises \haddockid{zip} by zipping with the function given
+ as the first argument, instead of a tupling function.
+ For example, \haddocktt{zipWith\ (+)} is applied to two lists to produce the
+ list of corresponding sums.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zipWith3\ ::\ (a\ ->\ b\ ->\ c\ ->\ d)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}d{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zipWith3} function takes a function which combines three
+ elements, as well as three lists and returns a list of their point-wise
+ combination, analogous to \haddockid{zipWith}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zipWith4\ ::\ (a\ ->\ b\ ->\ c\ ->\ d\ ->\ e)\\\ \ \ \ \ \ \ \ \ \ \ \ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}d{\char 93}\ ->\ {\char 91}e{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zipWith4} function takes a function which combines four
+ elements, as well as four lists and returns a list of their point-wise
+ combination, analogous to \haddockid{zipWith}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zipWith5\ ::\ (a\ ->\ b\ ->\ c\ ->\ d\ ->\ e\ ->\ f)\\\ \ \ \ \ \ \ \ \ \ \ \ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}d{\char 93}\ ->\ {\char 91}e{\char 93}\ ->\ {\char 91}f{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zipWith5} function takes a function which combines five
+ elements, as well as five lists and returns a list of their point-wise
+ combination, analogous to \haddockid{zipWith}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zipWith6\ ::\ (a\ ->\ b\ ->\ c\ ->\ d\ ->\ e\ ->\ f\ ->\ g)\\\ \ \ \ \ \ \ \ \ \ \ \ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}d{\char 93}\ ->\ {\char 91}e{\char 93}\ ->\ {\char 91}f{\char 93}\ ->\ {\char 91}g{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zipWith6} function takes a function which combines six
+ elements, as well as six lists and returns a list of their point-wise
+ combination, analogous to \haddockid{zipWith}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+zipWith7\ ::\ (a\ ->\ b\ ->\ c\ ->\ d\ ->\ e\ ->\ f\ ->\ g\ ->\ h)\\\ \ \ \ \ \ \ \ \ \ \ \ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ {\char 91}c{\char 93}\ ->\ {\char 91}d{\char 93}\ ->\ {\char 91}e{\char 93}\ ->\ {\char 91}f{\char 93}\ ->\ {\char 91}g{\char 93}\ ->\ {\char 91}h{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{zipWith7} function takes a function which combines seven
+ elements, as well as seven lists and returns a list of their point-wise
+ combination, analogous to \haddockid{zipWith}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unzip\ ::\ {\char 91}(a,\ b){\char 93}\ ->\ ({\char 91}a{\char 93},\ {\char 91}b{\char 93})
+\end{tabular}]\haddockbegindoc
+\haddockid{unzip} transforms a list of pairs into a list of first components
+ and a list of second components.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unzip3\ ::\ {\char 91}(a,\ b,\ c){\char 93}\ ->\ ({\char 91}a{\char 93},\ {\char 91}b{\char 93},\ {\char 91}c{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{unzip3} function takes a list of triples and returns three
+ lists, analogous to \haddockid{unzip}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unzip4\ ::\ {\char 91}(a,\ b,\ c,\ d){\char 93}\ ->\ ({\char 91}a{\char 93},\ {\char 91}b{\char 93},\ {\char 91}c{\char 93},\ {\char 91}d{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{unzip4} function takes a list of quadruples and returns four
+ lists, analogous to \haddockid{unzip}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unzip5\ ::\ {\char 91}(a,\ b,\ c,\ d,\ e){\char 93}\ ->\ ({\char 91}a{\char 93},\ {\char 91}b{\char 93},\ {\char 91}c{\char 93},\ {\char 91}d{\char 93},\ {\char 91}e{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{unzip5} function takes a list of five-tuples and returns five
+ lists, analogous to \haddockid{unzip}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unzip6\ ::\ {\char 91}(a,\ b,\ c,\ d,\ e,\ f){\char 93}\ ->\ ({\char 91}a{\char 93},\ {\char 91}b{\char 93},\ {\char 91}c{\char 93},\ {\char 91}d{\char 93},\ {\char 91}e{\char 93},\ {\char 91}f{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{unzip6} function takes a list of six-tuples and returns six
+ lists, analogous to \haddockid{unzip}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unzip7\ ::\ {\char 91}(a,\ b,\ c,\ d,\ e,\ f,\ g){\char 93}\\\ \ \ \ \ \ \ \ \ \ ->\ ({\char 91}a{\char 93},\ {\char 91}b{\char 93},\ {\char 91}c{\char 93},\ {\char 91}d{\char 93},\ {\char 91}e{\char 93},\ {\char 91}f{\char 93},\ {\char 91}g{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{unzip7} function takes a list of seven-tuples and returns
+ seven lists, analogous to \haddockid{unzip}.
+\par
+
+\end{haddockdesc}
+\section{Special lists
+}
+\subsection{Functions on strings
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+lines\ ::\ String\ ->\ {\char 91}String{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{lines} breaks a string up into a list of strings at newline
+ characters.  The resulting strings do not contain newlines.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+words\ ::\ String\ ->\ {\char 91}String{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{words} breaks a string up into a list of words, which were delimited
+ by white space.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unlines\ ::\ {\char 91}String{\char 93}\ ->\ String
+\end{tabular}]\haddockbegindoc
+\haddockid{unlines} is an inverse operation to \haddockid{lines}.
+ It joins lines, after appending a terminating newline to each.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unwords\ ::\ {\char 91}String{\char 93}\ ->\ String
+\end{tabular}]\haddockbegindoc
+\haddockid{unwords} is an inverse operation to \haddockid{words}.
+ It joins words with separating spaces.
+\par
+
+\end{haddockdesc}
+\subsection{"Set" operations
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+nub\ ::\ Eq\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{nub} function removes duplicate elements from a list.
+ In particular, it keeps only the first occurrence of each element.
+ (The name \haddockid{nub} means `essence'.)
+ It is a special case of \haddockid{nubBy}, which allows the programmer to supply
+ their own equality test.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+delete\ ::\ Eq\ a\ =>\ a\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+\haddockid{delete} \haddocktt{x} removes the first occurrence of \haddocktt{x} from its list argument.
+ For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ delete 'a' "banana" == "bnana"
+\end{verbatim}}
+\end{quote}
+It is a special case of \haddockid{deleteBy}, which allows the programmer to
+ supply their own equality test.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+({\char '134}{\char '134})\ ::\ Eq\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{{\char '134}{\char '134}} function is list difference ((non-associative).
+ In the result of \haddocktt{xs} \haddockid{{\char '134}{\char '134}} \haddocktt{ys}, the first occurrence of each element of
+ \haddocktt{ys} in turn (if any) has been removed from \haddocktt{xs}.  Thus
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ (xs ++ ys) \\ xs == ys.
+\end{verbatim}}
+\end{quote}
+It is a special case of \haddockid{deleteFirstsBy}, which allows the programmer
+ to supply their own equality test.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+union\ ::\ Eq\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{union} function returns the list union of the two lists.
+ For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ "dog" `union` "cow" == "dogcw"
+\end{verbatim}}
+\end{quote}
+Duplicates, and elements of the first list, are removed from the
+ the second list, but if the first list contains duplicates, so will
+ the result.
+ It is a special case of \haddockid{unionBy}, which allows the programmer to supply
+ their own equality test.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+intersect\ ::\ Eq\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{intersect} function takes the list intersection of two lists.
+ For example,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ [1,2,3,4] `intersect` [2,4,6,8] == [2,4]
+\end{verbatim}}
+\end{quote}
+If the first list contains duplicates, so will the result.
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ [1,2,2,3,4] `intersect` [6,4,4,2] == [2,2,4]
+\end{verbatim}}
+\end{quote}
+It is a special case of \haddockid{intersectBy}, which allows the programmer to
+ supply their own equality test.
+\par
+
+\end{haddockdesc}
+\subsection{Ordered lists
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+sort\ ::\ Ord\ a\ =>\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{sort} function implements a stable sorting algorithm.
+ It is a special case of \haddockid{sortBy}, which allows the programmer to supply
+ their own comparison function.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+insert\ ::\ Ord\ a\ =>\ a\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{insert} function takes an element and a list and inserts the
+ element into the list at the last position where it is still less
+ than or equal to the next element.  In particular, if the list
+ is sorted before the call, the result will also be sorted.
+ It is a special case of \haddockid{insertBy}, which allows the programmer to
+ supply their own comparison function.
+\par
+
+\end{haddockdesc}
+\section{Generalized functions
+}
+\subsection{The "\haddocktt{By}" operations
+}
+By convention, overloaded functions have a non-overloaded
+ counterpart whose name is suffixed with `\haddocktt{By}'.
+\par
+It is often convenient to use these functions together with
+ \haddocktt{Data.Function.on}, for instance \haddocktt{sortBy\ (compare\\\ `on`\ fst)}.
+\par
+
+\subsubsection{User-supplied equality (replacing an \haddocktt{Eq} context)
+}
+The predicate is assumed to define an equivalence.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+nubBy\ ::\ (a\ ->\ a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{nubBy} function behaves just like \haddockid{nub}, except it uses a
+ user-supplied equality predicate instead of the overloaded \haddockid{==}
+ function.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+deleteBy\ ::\ (a\ ->\ a\ ->\ Bool)\ ->\ a\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{deleteBy} function behaves like \haddockid{delete}, but takes a
+ user-supplied equality predicate.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+deleteFirstsBy\ ::\ (a\ ->\ a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{deleteFirstsBy} function takes a predicate and two lists and
+ returns the first list with the first occurrence of each element of
+ the second list removed.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unionBy\ ::\ (a\ ->\ a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{unionBy} function is the non-overloaded version of \haddockid{union}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+intersectBy\ ::\ (a\ ->\ a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{intersectBy} function is the non-overloaded version of \haddockid{intersect}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+groupBy\ ::\ (a\ ->\ a\ ->\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}{\char 91}a{\char 93}{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{groupBy} function is the non-overloaded version of \haddockid{group}.
+\par
+
+\end{haddockdesc}
+\subsubsection{User-supplied comparison (replacing an \haddocktt{Ord} context)
+}
+The function is assumed to define a total ordering.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+sortBy\ ::\ (a\ ->\ a\ ->\ Ordering)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{sortBy} function is the non-overloaded version of \haddockid{sort}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+insertBy\ ::\ (a\ ->\ a\ ->\ Ordering)\ ->\ a\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The non-overloaded version of \haddockid{insert}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+maximumBy\ ::\ (a\ ->\ a\ ->\ Ordering)\ ->\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{maximumBy} function takes a comparison function and a list
+ and returns the greatest element of the list by the comparison function.
+ The list must be finite and non-empty.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+minimumBy\ ::\ (a\ ->\ a\ ->\ Ordering)\ ->\ {\char 91}a{\char 93}\ ->\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{minimumBy} function takes a comparison function and a list
+ and returns the least element of the list by the comparison function.
+ The list must be finite and non-empty.
+\par
+
+\end{haddockdesc}
+\subsection{The "\haddocktt{generic}" operations
+}
+The prefix `\haddocktt{generic}' indicates an overloaded function that
+ is a generalized version of a \haddocktt{Prelude} function.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+genericLength\ ::\ Num\ i\ =>\ {\char 91}b{\char 93}\ ->\ i
+\end{tabular}]\haddockbegindoc
+The \haddockid{genericLength} function is an overloaded version of \haddockid{length}.  In
+ particular, instead of returning an \haddockid{Int}, it returns any type which is
+ an instance of \haddockid{Num}.  It is, however, less efficient than \haddockid{length}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+genericTake\ ::\ Integral\ i\ =>\ i\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{genericTake} function is an overloaded version of \haddockid{take}, which
+ accepts any \haddockid{Integral} value as the number of elements to take.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+genericDrop\ ::\ Integral\ i\ =>\ i\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{genericDrop} function is an overloaded version of \haddockid{drop}, which
+ accepts any \haddockid{Integral} value as the number of elements to drop.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+genericSplitAt\ ::\ Integral\ i\ =>\ i\ ->\ {\char 91}b{\char 93}\ ->\ ({\char 91}b{\char 93},\ {\char 91}b{\char 93})
+\end{tabular}]\haddockbegindoc
+The \haddockid{genericSplitAt} function is an overloaded version of \haddockid{splitAt}, which
+ accepts any \haddockid{Integral} value as the position at which to split.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+genericIndex\ ::\ Integral\ a\ =>\ {\char 91}b{\char 93}\ ->\ a\ ->\ b
+\end{tabular}]\haddockbegindoc
+The \haddockid{genericIndex} function is an overloaded version of \haddockid{!!}, which
+ accepts any \haddockid{Integral} value as the index.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+genericReplicate\ ::\ Integral\ i\ =>\ i\ ->\ a\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{genericReplicate} function is an overloaded version of \haddockid{replicate},
+ which accepts any \haddockid{Integral} value as the number of repetitions to make.
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Data-Maybe.tex b/report/libs/Data-Maybe.tex
new file mode 100644 (file)
index 0000000..029dcd9
--- /dev/null
@@ -0,0 +1,169 @@
+\chapter{\texttt{Data.Maybe}}
+\label{module:Data.Maybe}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.Maybe (
+    Maybe(Nothing, Just),  maybe,  isJust,  isNothing,  fromJust,  fromMaybe, 
+    listToMaybe,  maybeToList,  catMaybes,  mapMaybe
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{The \haddocktt{Maybe} type and operations
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Maybe\ a
+\end{tabular}]\haddockbegindoc
+\haddockbeginconstrs
+\haddockdecltt{=} & \haddockdecltt{Nothing} & \\
+\haddockdecltt{|} & \haddockdecltt{Just a} & \\
+\haddockendconstrs\par
+The \haddockid{Maybe} type encapsulates an optional value.  A value of type
+ \haddocktt{Maybe\ a} either contains a value of type \haddocktt{a} (represented as \haddocktt{Just\ a}), 
+ or it is empty (represented as \haddockid{Nothing}).  Using \haddockid{Maybe} is a good way to 
+ deal with errors or exceptional cases without resorting to drastic
+ measures such as \haddockid{error}.
+\par
+The \haddockid{Maybe} type is also a monad.  It is a simple kind of error
+ monad, where all errors are represented by \haddockid{Nothing}.  A richer
+ error monad can be built using the \haddocktt{Data.Either.Either} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Monad\ Maybe\\instance\ Functor\ Maybe\\instance\ MonadPlus\ Maybe\\instance\ Eq\ a\ =>\ Eq\ (Maybe\ a)\\instance\ Ord\ a\ =>\ Ord\ (Maybe\ a)\\instance\ Read\ a\ =>\ Read\ (Maybe\ a)\\instance\ Show\ a\ =>\ Show\ (Maybe\ a)
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+maybe\ ::\ b\ ->\ (a\ ->\ b)\ ->\ Maybe\ a\ ->\ b
+\end{tabular}]\haddockbegindoc
+The \haddockid{maybe} function takes a default value, a function, and a \haddockid{Maybe}
+ value.  If the \haddockid{Maybe} value is \haddockid{Nothing}, the function returns the
+ default value.  Otherwise, it applies the function to the value inside
+ the \haddockid{Just} and returns the result.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isJust\ ::\ Maybe\ a\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+The \haddockid{isJust} function returns \haddockid{True} iff its argument is of the
+ form \haddocktt{Just\ {\char '137}}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isNothing\ ::\ Maybe\ a\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+The \haddockid{isNothing} function returns \haddockid{True} iff its argument is \haddockid{Nothing}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+fromJust\ ::\ Maybe\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{fromJust} function extracts the element out of a \haddockid{Just} and
+ throws an error if its argument is \haddockid{Nothing}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+fromMaybe\ ::\ a\ ->\ Maybe\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{fromMaybe} function takes a default value and and \haddockid{Maybe}
+ value.  If the \haddockid{Maybe} is \haddockid{Nothing}, it returns the default values;
+ otherwise, it returns the value contained in the \haddockid{Maybe}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+listToMaybe\ ::\ {\char 91}a{\char 93}\ ->\ Maybe\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{listToMaybe} function returns \haddockid{Nothing} on an empty list
+ or \haddocktt{Just\ a} where \haddocktt{a} is the first element of the list.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+maybeToList\ ::\ Maybe\ a\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{maybeToList} function returns an empty list when given
+ \haddockid{Nothing} or a singleton list when not given \haddockid{Nothing}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+catMaybes\ ::\ {\char 91}Maybe\ a{\char 93}\ ->\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{catMaybes} function takes a list of \haddockid{Maybe}s and returns
+ a list of all the \haddockid{Just} values. 
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mapMaybe\ ::\ (a\ ->\ Maybe\ b)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}
+\end{tabular}]\haddockbegindoc
+The \haddockid{mapMaybe} function is a version of \haddockid{map} which can throw
+ out elements.  In particular, the functional argument returns
+ something of type \haddocktt{Maybe\ b}.  If this is \haddockid{Nothing}, no element
+ is added on to the result list.  If it just \haddocktt{Just\ b}, then \haddocktt{b} is
+ included in the result list.
+\par
+
+\end{haddockdesc}
+\section{Specification
+}
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ module Maybe(
+     Maybe(Nothing, Just),
+     isJust, isNothing,
+     fromJust, fromMaybe, listToMaybe, maybeToList,
+     catMaybes, mapMaybe,
+     maybe
+   ) where
+ maybe                  :: b -> (a -> b) -> Maybe a -> b
+ maybe n _ Nothing      =  n
+ maybe _ f (Just x)     =  f x
+ isJust                 :: Maybe a -> Bool
+ isJust (Just a)        =  True
+ isJust Nothing         =  False
+ isNothing              :: Maybe a -> Bool
+ isNothing              =  not . isJust
+ fromJust               :: Maybe a -> a
+ fromJust (Just a)      =  a
+ fromJust Nothing       =  error "Maybe.fromJust: Nothing"
+ fromMaybe              :: a -> Maybe a -> a
+ fromMaybe d Nothing    =  d
+ fromMaybe d (Just a)   =  a
+ maybeToList            :: Maybe a -> [a]
+ maybeToList Nothing    =  []
+ maybeToList (Just a)   =  [a]
+ listToMaybe            :: [a] -> Maybe a
+ listToMaybe []         =  Nothing
+ listToMaybe (a:_)      =  Just a
+  
+ catMaybes              :: [Maybe a] -> [a]
+ catMaybes ms           =  [ m | Just m <- ms ]
+ mapMaybe               :: (a -> Maybe b) -> [a] -> [b]
+ mapMaybe f             =  catMaybes . map f
+\end{verbatim}}
+\end{quote}
diff --git a/report/libs/Data-Ratio.tex b/report/libs/Data-Ratio.tex
new file mode 100644 (file)
index 0000000..3d1b35d
--- /dev/null
@@ -0,0 +1,186 @@
+\chapter{\texttt{Data.Ratio}}
+\label{module:Data.Ratio}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.Ratio (
+    Ratio,  Rational,  (%),  numerator,  denominator,  approxRational
+  ) where\end{verbatim}}
+\haddockendheader
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Integral\ a\ =>\ Ratio\ a
+\end{tabular}]\haddockbegindoc
+Rational numbers, with numerator and denominator of some \haddockid{Integral} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Integral\ a\ =>\ Enum\ (Ratio\ a)\\instance\ Integral\ a\ =>\ Eq\ (Ratio\ a)\\instance\ Integral\ a\ =>\ Fractional\ (Ratio\ a)\\instance\ Integral\ a\ =>\ Num\ (Ratio\ a)\\instance\ Integral\ a\ =>\ Ord\ (Ratio\ a)\\instance\ (Integral\ a,\ Read\ a)\ =>\ Read\ (Ratio\ a)\\instance\ Integral\ a\ =>\ Real\ (Ratio\ a)\\instance\ Integral\ a\ =>\ RealFrac\ (Ratio\ a)\\instance\ Integral\ a\ =>\ Show\ (Ratio\ a)
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ Rational\ =\ Ratio\ Integer
+\end{tabular}]\haddockbegindoc
+Arbitrary-precision rational numbers, represented as a ratio of
+ two \haddockid{Integer} values.  A rational number may be constructed using
+ the \haddockid{{\char '45}} operator.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+({\char '45})\ ::\ Integral\ a\ =>\ a\ ->\ a\ ->\ Ratio\ a
+\end{tabular}]\haddockbegindoc
+Forms the ratio of two integral numbers.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+numerator\ ::\ Integral\ a\ =>\ Ratio\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+Extract the numerator of the ratio in reduced form:
+ the numerator and denominator have no common factor and the denominator
+ is positive.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+denominator\ ::\ Integral\ a\ =>\ Ratio\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+Extract the denominator of the ratio in reduced form:
+ the numerator and denominator have no common factor and the denominator
+ is positive.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+approxRational\ ::\ RealFrac\ a\ =>\ a\ ->\ a\ ->\ Rational
+\end{tabular}]\haddockbegindoc
+\haddockid{approxRational}, applied to two real fractional numbers \haddocktt{x} and \haddocktt{epsilon},
+ returns the simplest rational number within \haddocktt{epsilon} of \haddocktt{x}.
+ A rational number \haddocktt{y} is said to be \emph{simpler} than another \haddocktt{y'} if
+\par
+\begin{itemize}
+\item
+ \haddocktt{abs\ (numerator\ y)\ <=\ abs\ (numerator\ y')}, and
+\par
+
+\item
+ \haddocktt{denominator\ y\ <=\ denominator\ y'}.
+\par
+
+\end{itemize}
+Any real interval contains a unique simplest rational;
+ in particular, note that \haddocktt{0/1} is the simplest rational of all.
+\par
+
+\end{haddockdesc}
+\section{Specification
+}
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ module  Ratio (
+     Ratio, Rational, (%), numerator, denominator, approxRational ) where
+ infixl 7  %
+ ratPrec = 7 :: Int
+ data  (Integral a)      => Ratio a = !a :% !a  deriving (Eq)
+ type  Rational          =  Ratio Integer
+ (%)                     :: (Integral a) => a -> a -> Ratio a
+ numerator, denominator  :: (Integral a) => Ratio a -> a
+ approxRational          :: (RealFrac a) => a -> a -> Rational
+ -- "reduce" is a subsidiary function used only in this module.
+ -- It normalises a ratio by dividing both numerator
+ -- and denominator by their greatest common divisor.
+ --
+ -- E.g., 12 `reduce` 8    ==  3 :%   2
+ --       12 `reduce` (-8) ==  3 :% (-2)
+ reduce _ 0              =  error "Ratio.% : zero denominator"
+ reduce x y              =  (x `quot` d) :% (y `quot` d)
+                            where d = gcd x y
+ x % y                   =  reduce (x * signum y) (abs y)
+ numerator (x :% _)      =  x
+ denominator (_ :% y)    =  y
+ instance  (Integral a)  => Ord (Ratio a)  where
+     (x:%y) <= (x':%y')  =  x * y' <= x' * y
+     (x:%y) <  (x':%y')  =  x * y' <  x' * y
+ instance  (Integral a)  => Num (Ratio a)  where
+     (x:%y) + (x':%y')   =  reduce (x*y' + x'*y) (y*y')
+     (x:%y) * (x':%y')   =  reduce (x * x') (y * y')
+     negate (x:%y)       =  (-x) :% y
+     abs (x:%y)          =  abs x :% y
+     signum (x:%y)       =  signum x :% 1
+     fromInteger x       =  fromInteger x :% 1
+ instance  (Integral a)  => Real (Ratio a)  where
+     toRational (x:%y)   =  toInteger x :% toInteger y
+ instance  (Integral a)  => Fractional (Ratio a)  where
+     (x:%y) / (x':%y')   =  (x*y') % (y*x')
+     recip (x:%y)        =  y % x
+     fromRational (x:%y) =  fromInteger x :% fromInteger y
+ instance  (Integral a)  => RealFrac (Ratio a)  where
+     properFraction (x:%y) = (fromIntegral q, r:%y)
+                             where (q,r) = quotRem x y
+ instance  (Integral a)  => Enum (Ratio a)  where
+     succ x           =  x+1
+     pred x           =  x-1
+     toEnum           =  fromIntegral
+     fromEnum         =  fromInteger . truncate        -- May overflow
+     enumFrom         =  numericEnumFrom               -- These numericEnumXXX functions
+     enumFromThen     =  numericEnumFromThen   -- are as defined in Prelude.hs
+     enumFromTo       =  numericEnumFromTo     -- but not exported from it!
+     enumFromThenTo   =  numericEnumFromThenTo
+ instance  (Read a, Integral a)  => Read (Ratio a)  where
+     readsPrec p  =  readParen (p > ratPrec)
+                               (\r -> [(x%y,u) | (x,s)   <- readsPrec (ratPrec+1) r,
+                                                 ("%",t) <- lex s,
+                                                 (y,u)   <- readsPrec (ratPrec+1) t ])
+ instance  (Integral a)  => Show (Ratio a)  where
+     showsPrec p (x:%y)  =  showParen (p > ratPrec)
+                                (showsPrec (ratPrec+1) x . 
+                               showString " % " . 
+                               showsPrec (ratPrec+1) y)
+ approxRational x eps    =  simplest (x-eps) (x+eps)
+         where simplest x y | y < x      =  simplest y x
+                            | x == y     =  xr
+                            | x > 0      =  simplest' n d n' d'
+                            | y < 0      =  - simplest' (-n') d' (-n) d
+                            | otherwise  =  0 :% 1
+                                         where xr@(n:%d) = toRational x
+                                               (n':%d')  = toRational y
+               simplest' n d n' d'       -- assumes 0 < n%d < n'%d'
+                         | r == 0     =  q :% 1
+                         | q /= q'    =  (q+1) :% 1
+                         | otherwise  =  (q*n''+d'') :% n''
+                                      where (q,r)      =  quotRem n d
+                                            (q',r')    =  quotRem n' d'
+                                            (n'':%d'') =  simplest' d' r' d r
+\end{verbatim}}
+\end{quote}
diff --git a/report/libs/Data-Word.tex b/report/libs/Data-Word.tex
new file mode 100644 (file)
index 0000000..7e3631e
--- /dev/null
@@ -0,0 +1,98 @@
+\chapter{\texttt{Data.Word}}
+\label{module:Data.Word}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Data.Word (
+    Word,  Word8,  Word16,  Word32,  Word64
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{Unsigned integral types
+}
+This module provides unsigned integer types of unspecified width (\haddockid{Word})
+and fixed widths (\haddockid{Word8}, \haddockid{Word16}, \haddockid{Word32} and \haddockid{Word64}).  All
+arithmetic is performed modulo 2{\char '136}n, where \haddocktt{n} is the number of bits in
+the type.  One non-obvious consequence of this is that \haddockid{negate}
+  should \emph{not} raise an error on negative arguments.
+\par
+For coercing between any two integer types, use
+\haddockid{fromIntegral}.  Coercing word types to and from integer
+types preserves representation, not sign.
+\par
+The rules that hold for \haddockid{Enum} instances over a bounded type
+such as \haddockid{Int} (see the section of the Haskell report dealing
+with arithmetic sequences) also hold for the \haddockid{Enum} instances
+over the various \haddockid{Word} types defined here.
+\par
+Right and left shifts by amounts greater than or equal to the width of
+the type result in a zero result.  This is contrary to the behaviour
+in C, which is undefined; a common interpretation is to truncate the
+shift count to the width of the type, for example \haddocktt{1\ <<\ 32\ ==\ 1} in
+some C implementations.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Word
+\end{tabular}]\haddockbegindoc
+A \haddockid{Word} is an unsigned integral type, with the same size as \haddockid{Int}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ Word\\instance\ Enum\ Word\\instance\ Eq\ Word\\instance\ Integral\ Word\\instance\ Num\ Word\\instance\ Ord\ Word\\instance\ Read\ Word\\instance\ Real\ Word\\instance\ Show\ Word\\instance\ Ix\ Word\\instance\ Storable\ Word\\instance\ Bits\ Word
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Word8
+\end{tabular}]\haddockbegindoc
+8-bit unsigned integer type
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ Word8\\instance\ Enum\ Word8\\instance\ Eq\ Word8\\instance\ Integral\ Word8\\instance\ Num\ Word8\\instance\ Ord\ Word8\\instance\ Read\ Word8\\instance\ Real\ Word8\\instance\ Show\ Word8\\instance\ Ix\ Word8\\instance\ Storable\ Word8\\instance\ Bits\ Word8
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Word16
+\end{tabular}]\haddockbegindoc
+16-bit unsigned integer type
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ Word16\\instance\ Enum\ Word16\\instance\ Eq\ Word16\\instance\ Integral\ Word16\\instance\ Num\ Word16\\instance\ Ord\ Word16\\instance\ Read\ Word16\\instance\ Real\ Word16\\instance\ Show\ Word16\\instance\ Ix\ Word16\\instance\ Storable\ Word16\\instance\ Bits\ Word16
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Word32
+\end{tabular}]\haddockbegindoc
+32-bit unsigned integer type
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ Word32\\instance\ Enum\ Word32\\instance\ Eq\ Word32\\instance\ Integral\ Word32\\instance\ Num\ Word32\\instance\ Ord\ Word32\\instance\ Read\ Word32\\instance\ Real\ Word32\\instance\ Show\ Word32\\instance\ Ix\ Word32\\instance\ Storable\ Word32\\instance\ Bits\ Word32
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Word64
+\end{tabular}]\haddockbegindoc
+64-bit unsigned integer type
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ Word64\\instance\ Enum\ Word64\\instance\ Eq\ Word64\\instance\ Integral\ Word64\\instance\ Num\ Word64\\instance\ Ord\ Word64\\instance\ Read\ Word64\\instance\ Real\ Word64\\instance\ Show\ Word64\\instance\ Ix\ Word64\\instance\ Storable\ Word64\\instance\ Bits\ Word64
+\end{tabular}]
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-C-Error.tex b/report/libs/Foreign-C-Error.tex
new file mode 100644 (file)
index 0000000..3fd3414
--- /dev/null
@@ -0,0 +1,342 @@
+\chapter{\texttt{Foreign.C.Error}}
+\label{module:Foreign.C.Error}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.C.Error (
+    Errno(Errno),  eOK,  e2BIG,  eACCES,  eADDRINUSE,  eADDRNOTAVAIL,  eADV, 
+    eAFNOSUPPORT,  eAGAIN,  eALREADY,  eBADF,  eBADMSG,  eBADRPC,  eBUSY, 
+    eCHILD,  eCOMM,  eCONNABORTED,  eCONNREFUSED,  eCONNRESET,  eDEADLK, 
+    eDESTADDRREQ,  eDIRTY,  eDOM,  eDQUOT,  eEXIST,  eFAULT,  eFBIG,  eFTYPE, 
+    eHOSTDOWN,  eHOSTUNREACH,  eIDRM,  eILSEQ,  eINPROGRESS,  eINTR,  eINVAL, 
+    eIO,  eISCONN,  eISDIR,  eLOOP,  eMFILE,  eMLINK,  eMSGSIZE,  eMULTIHOP, 
+    eNAMETOOLONG,  eNETDOWN,  eNETRESET,  eNETUNREACH,  eNFILE,  eNOBUFS, 
+    eNODATA,  eNODEV,  eNOENT,  eNOEXEC,  eNOLCK,  eNOLINK,  eNOMEM,  eNOMSG, 
+    eNONET,  eNOPROTOOPT,  eNOSPC,  eNOSR,  eNOSTR,  eNOSYS,  eNOTBLK, 
+    eNOTCONN,  eNOTDIR,  eNOTEMPTY,  eNOTSOCK,  eNOTTY,  eNXIO,  eOPNOTSUPP, 
+    ePERM,  ePFNOSUPPORT,  ePIPE,  ePROCLIM,  ePROCUNAVAIL,  ePROGMISMATCH, 
+    ePROGUNAVAIL,  ePROTO,  ePROTONOSUPPORT,  ePROTOTYPE,  eRANGE,  eREMCHG, 
+    eREMOTE,  eROFS,  eRPCMISMATCH,  eRREMOTE,  eSHUTDOWN,  eSOCKTNOSUPPORT, 
+    eSPIPE,  eSRCH,  eSRMNT,  eSTALE,  eTIME,  eTIMEDOUT,  eTOOMANYREFS, 
+    eTXTBSY,  eUSERS,  eWOULDBLOCK,  eXDEV,  isValidErrno,  getErrno, 
+    resetErrno,  errnoToIOError,  throwErrno,  throwErrnoIf,  throwErrnoIf_, 
+    throwErrnoIfRetry,  throwErrnoIfRetry_,  throwErrnoIfMinus1, 
+    throwErrnoIfMinus1_,  throwErrnoIfMinus1Retry,  throwErrnoIfMinus1Retry_, 
+    throwErrnoIfNull,  throwErrnoIfNullRetry,  throwErrnoIfRetryMayBlock, 
+    throwErrnoIfRetryMayBlock_,  throwErrnoIfMinus1RetryMayBlock, 
+    throwErrnoIfMinus1RetryMayBlock_,  throwErrnoIfNullRetryMayBlock, 
+    throwErrnoPath,  throwErrnoPathIf,  throwErrnoPathIf_, 
+    throwErrnoPathIfNull,  throwErrnoPathIfMinus1,  throwErrnoPathIfMinus1_
+  ) where\end{verbatim}}
+\haddockendheader
+
+The module \haddocktt{Foreign.C.Error} facilitates C-specific error
+ handling of \haddocktt{errno}.
+\par
+
+\section{Haskell representations of \haddocktt{errno} values
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newtype\ Errno
+\end{tabular}]\haddockbegindoc
+\haddockbeginconstrs
+\haddockdecltt{=} & \haddockdecltt{Errno CInt} & \\
+\haddockendconstrs\par
+Haskell representation for \haddocktt{errno} values.
+ The implementation is deliberately exposed, to allow users to add
+ their own definitions of \haddockid{Errno} values.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ Errno
+\end{tabular}]
+\end{haddockdesc}
+\subsection{Common \haddocktt{errno} symbols
+}
+Different operating systems and/or C libraries often support
+ different values of \haddocktt{errno}.  This module defines the common values,
+ but due to the open definition of \haddockid{Errno} users may add definitions
+ which are not predefined.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+eOK\ ::\ Errno\\e2BIG\ ::\ Errno\\eACCES\ ::\ Errno\\eADDRINUSE\ ::\ Errno\\eADDRNOTAVAIL\ ::\ Errno\\eADV\ ::\ Errno\\eAFNOSUPPORT\ ::\ Errno\\eAGAIN\ ::\ Errno\\eALREADY\ ::\ Errno\\eBADF\ ::\ Errno\\eBADMSG\ ::\ Errno\\eBADRPC\ ::\ Errno\\eBUSY\ ::\ Errno\\eCHILD\ ::\ Errno\\eCOMM\ ::\ Errno\\eCONNABORTED\ ::\ Errno\\eCONNREFUSED\ ::\ Errno\\eCONNRESET\ ::\ Errno\\eDEADLK\ ::\ Errno\\eDESTADDRREQ\ ::\ Errno\\eDIRTY\ ::\ Errno\\eDOM\ ::\ Errno\\eDQUOT\ ::\ Errno\\eEXIST\ ::\ Errno\\eFAULT\ ::\ Errno\\eFBIG\ ::\ Errno\\eFTYPE\ ::\ Errno\\eHOSTDOWN\ ::\ Errno\\eHOSTUNREACH\ ::\ Errno\\eIDRM\ ::\ Errno\\eILSEQ\ ::\ Errno\\eINPROGRESS\ ::\ Errno\\eINTR\ ::\ Errno\\eINVAL\ ::\ Errno\\eIO\ ::\ Errno\\eISCONN\ ::\ Errno\\eISDIR\ ::\ Errno\\eLOOP\ ::\ Errno\\eMFILE\ ::\ Errno\\eMLINK\ ::\ Errno\\eMSGSIZE\ ::\ Errno\\eMULTIHOP\ ::\ Errno\\eNAMETOOLONG\ ::\ Errno\\eNETDOWN\ ::\ Errno\\eNETRESET\ ::\ Errno\\eNETUNREACH\ ::\ Errno\\eNFILE\ ::\ Errno\\eNOBUFS\ ::\ Errno\\eNODATA\ ::\ Errno\\eNODEV\ ::\ Errno\\eNOENT\ ::\ Errno\\eNOEXEC\ ::\ Errno\\eNOLCK\ ::\ Errno\\eNOLINK\ ::\ Errno\\eNOMEM\ ::\ Errno\\eNOMSG\ ::\ Errno\\eNONET\ ::\ Errno\\eNOPROTOOPT\ ::\ Errno\\eNOSPC\ ::\ Errno\\eNOSR\ ::\ Errno\\eNOSTR\ ::\ Errno\\eNOSYS\ ::\ Errno\\eNOTBLK\ ::\ Errno\\eNOTCONN\ ::\ Errno\\eNOTDIR\ ::\ Errno\\eNOTEMPTY\ ::\ Errno\\eNOTSOCK\ ::\ Errno\\eNOTTY\ ::\ Errno\\eNXIO\ ::\ Errno\\eOPNOTSUPP\ ::\ Errno\\ePERM\ ::\ Errno\\ePFNOSUPPORT\ ::\ Errno\\ePIPE\ ::\ Errno\\ePROCLIM\ ::\ Errno\\ePROCUNAVAIL\ ::\ Errno\\ePROGMISMATCH\ ::\ Errno\\ePROGUNAVAIL\ ::\ Errno\\ePROTO\ ::\ Errno\\ePROTONOSUPPORT\ ::\ Errno\\ePROTOTYPE\ ::\ Errno\\eRANGE\ ::\ Errno\\eREMCHG\ ::\ Errno\\eREMOTE\ ::\ Errno\\eROFS\ ::\ Errno\\eRPCMISMATCH\ ::\ Errno\\eRREMOTE\ ::\ Errno\\eSHUTDOWN\ ::\ Errno\\eSOCKTNOSUPPORT\ ::\ Errno\\eSPIPE\ ::\ Errno\\eSRCH\ ::\ Errno\\eSRMNT\ ::\ Errno\\eSTALE\ ::\ Errno\\eTIME\ ::\ Errno\\eTIMEDOUT\ ::\ Errno\\eTOOMANYREFS\ ::\ Errno\\eTXTBSY\ ::\ Errno\\eUSERS\ ::\ Errno\\eWOULDBLOCK\ ::\ Errno\\eXDEV\ ::\ Errno
+\end{tabular}]
+\end{haddockdesc}
+\subsection{\haddockid{Errno} functions
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isValidErrno\ ::\ Errno\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Yield \haddockid{True} if the given \haddockid{Errno} value is valid on the system.
+ This implies that the \haddockid{Eq} instance of \haddockid{Errno} is also system dependent
+ as it is only defined for valid values of \haddockid{Errno}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+getErrno\ ::\ IO\ Errno
+\end{tabular}]\haddockbegindoc
+Get the current value of \haddocktt{errno} in the current thread.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+resetErrno\ ::\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Reset the current thread's \haddocktt{errno} value to \haddockid{eOK}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+errnoToIOError
+\end{tabular}]\haddockbegindoc
+\haddockbeginargs
+\haddockdecltt{::} & \haddockdecltt{String} & the location where the error occurred
+ \\
+                                              \haddockdecltt{->} & \haddockdecltt{Errno} & the error number
+ \\
+                                                                                           \haddockdecltt{->} & \haddockdecltt{Maybe Handle} & optional handle associated with the error
+ \\
+                                                                                                                                               \haddockdecltt{->} & \haddockdecltt{Maybe String} & optional filename associated with the error
+ \\
+                                                                                                                                                                                                   \haddockdecltt{->} & \haddockdecltt{IOError} & \\
+\haddockendargs\par
+Construct a Haskell 98 I/O error based on the given \haddockid{Errno} value.
+ The optional information can be used to improve the accuracy of
+ error messages.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrno
+\end{tabular}]\haddockbegindoc
+\haddockbeginargs
+\haddockdecltt{::} & \haddockdecltt{String} & textual description of the error location
+ \\
+                                              \haddockdecltt{->} & \haddockdecltt{IO a} & \\
+\haddockendargs\par
+Throw an \haddockid{IOError} corresponding to the current value of \haddockid{getErrno}.
+\par
+
+\end{haddockdesc}
+\subsection{Guards for IO operations that may fail
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIf
+\end{tabular}]\haddockbegindoc
+\haddockbeginargs
+\haddockdecltt{::} & \haddockdecltt{(a
+                                     -> Bool)} & predicate to apply to the result value
+ of the \haddockid{IO} operation
+ \\
+                                                 \haddockdecltt{->} & \haddockdecltt{String} & textual description of the location
+ \\
+                                                                                               \haddockdecltt{->} & \haddockdecltt{IO a} & the \haddockid{IO} operation to be executed
+ \\
+                                                                                                                                           \haddockdecltt{->} & \haddockdecltt{IO a} & \\
+\haddockendargs\par
+Throw an \haddockid{IOError} corresponding to the current value of \haddockid{getErrno}
+ if the result value of the \haddockid{IO} action meets the given predicate.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIf{\char '137}\ ::\ (a\ ->\ Bool)\ ->\ String\ ->\ IO\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIf}, but discards the result of the \haddockid{IO} action after
+ error handling.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfRetry\ ::\ (a\ ->\ Bool)\ ->\ String\ ->\ IO\ a\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIf}, but retry the \haddockid{IO} action when it yields the
+ error code \haddockid{eINTR} - this amounts to the standard retry loop for
+ interrupted POSIX system calls.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfRetry{\char '137}\ ::\ (a\ ->\ Bool)\ ->\ String\ ->\ IO\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfRetry}, but discards the result.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfMinus1\ ::\ Num\ a\ =>\ String\ ->\ IO\ a\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Throw an \haddockid{IOError} corresponding to the current value of \haddockid{getErrno}
+ if the \haddockid{IO} action returns a result of \haddocktt{-1}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfMinus1{\char '137}\ ::\ Num\ a\ =>\ String\ ->\ IO\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfMinus1}, but discards the result.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfMinus1Retry\ ::\ Num\ a\ =>\ String\ ->\ IO\ a\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Throw an \haddockid{IOError} corresponding to the current value of \haddockid{getErrno}
+ if the \haddockid{IO} action returns a result of \haddocktt{-1}, but retries in case of
+ an interrupted operation.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfMinus1Retry{\char '137}\ ::\ Num\ a\ =>\ String\ ->\ IO\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfMinus1}, but discards the result.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfNull\ ::\ String\ ->\ IO\ (Ptr\ a)\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Throw an \haddockid{IOError} corresponding to the current value of \haddockid{getErrno}
+ if the \haddockid{IO} action returns \haddockid{nullPtr}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfNullRetry\ ::\ String\ ->\ IO\ (Ptr\ a)\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Throw an \haddockid{IOError} corresponding to the current value of \haddockid{getErrno}
+ if the \haddockid{IO} action returns \haddockid{nullPtr},
+ but retry in case of an interrupted operation.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfRetryMayBlock
+\end{tabular}]\haddockbegindoc
+\haddockbeginargs
+\haddockdecltt{::} & \haddockdecltt{(a
+                                     -> Bool)} & predicate to apply to the result value
+ of the \haddockid{IO} operation
+ \\
+                                                 \haddockdecltt{->} & \haddockdecltt{String} & textual description of the location
+ \\
+                                                                                               \haddockdecltt{->} & \haddockdecltt{IO a} & the \haddockid{IO} operation to be executed
+ \\
+                                                                                                                                           \haddockdecltt{->} & \haddockdecltt{IO b} & action to execute before retrying if
+ an immediate retry would block
+ \\
+                                                                                                                                                                                       \haddockdecltt{->} & \haddockdecltt{IO a} & \\
+\haddockendargs\par
+as \haddockid{throwErrnoIfRetry}, but additionlly if the operation 
+ yields the error code \haddockid{eAGAIN} or \haddockid{eWOULDBLOCK}, an alternative
+ action is executed before retrying.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfRetryMayBlock{\char '137}\ ::\ (a\ ->\ Bool)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ String\ ->\ IO\ a\ ->\ IO\ b\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfRetryMayBlock}, but discards the result.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfMinus1RetryMayBlock\ ::\ Num\ a\ =>\ String\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ IO\ a\ ->\ IO\ b\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfMinus1Retry}, but checks for operations that would block.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfMinus1RetryMayBlock{\char '137}\ ::\ Num\ a\ =>\ String\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ IO\ a\ ->\ IO\ b\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfMinus1RetryMayBlock}, but discards the result.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoIfNullRetryMayBlock\ ::\ String\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ IO\ (Ptr\ a)\ ->\ IO\ b\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfNullRetry}, but checks for operations that would block.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoPath\ ::\ String\ ->\ FilePath\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrno}, but exceptions include the given path when appropriate.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoPathIf\ ::\ (a\ ->\ Bool)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ String\ ->\ FilePath\ ->\ IO\ a\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIf}, but exceptions include the given path when
+   appropriate.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoPathIf{\char '137}\ ::\ (a\ ->\ Bool)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ String\ ->\ FilePath\ ->\ IO\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIf{\char '137}}, but exceptions include the given path when
+   appropriate.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoPathIfNull\ ::\ String\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ FilePath\ ->\ IO\ (Ptr\ a)\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfNull}, but exceptions include the given path when
+   appropriate.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoPathIfMinus1\ ::\ Num\ a\ =>\ String\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ FilePath\ ->\ IO\ a\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfMinus1}, but exceptions include the given path when
+   appropriate.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwErrnoPathIfMinus1{\char '137}\ ::\ Num\ a\ =>\ String\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ FilePath\ ->\ IO\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+as \haddockid{throwErrnoIfMinus1{\char '137}}, but exceptions include the given path when
+   appropriate.
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-C-String.tex b/report/libs/Foreign-C-String.tex
new file mode 100644 (file)
index 0000000..d8fb08e
--- /dev/null
@@ -0,0 +1,399 @@
+\chapter{\texttt{Foreign.C.String}}
+\label{module:Foreign.C.String}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.C.String (
+    CString,  CStringLen,  peekCString,  peekCStringLen,  newCString, 
+    newCStringLen,  withCString,  withCStringLen,  charIsRepresentable, 
+    castCharToCChar,  castCCharToChar,  peekCAString,  peekCAStringLen, 
+    newCAString,  newCAStringLen,  withCAString,  withCAStringLen,  CWString, 
+    CWStringLen,  peekCWString,  peekCWStringLen,  newCWString, 
+    newCWStringLen,  withCWString,  withCWStringLen
+  ) where\end{verbatim}}
+\haddockendheader
+
+Utilities for primitive marshalling of C strings.
+\par
+The marshalling converts each Haskell character, representing a Unicode
+ code point, to one or more bytes in a manner that, by default, is
+ determined by the current locale.  As a consequence, no guarantees
+ can be made about the relative length of a Haskell string and its
+ corresponding C string, and therefore all the marshalling routines
+ include memory allocation.  The translation between Unicode and the
+ encoding of the current locale may be lossy.
+\par
+
+\section{C strings
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ CString\ =\ Ptr\ CChar
+\end{tabular}]\haddockbegindoc
+A C string is a reference to an array of C characters terminated by NUL.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ CStringLen\ =\ (Ptr\ CChar,\ Int)
+\end{tabular}]\haddockbegindoc
+A string with explicit length information in bytes instead of a
+ terminating NUL (allowing NUL characters in the middle of the string).
+\par
+
+\end{haddockdesc}
+\subsection{Using a locale-dependent encoding
+}
+Currently these functions are identical to their \haddocktt{CAString} counterparts;
+ eventually they will use an encoding determined by the current locale.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekCString\ ::\ CString\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+Marshal a NUL terminated C string into a Haskell string.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekCStringLen\ ::\ CStringLen\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+Marshal a C string with explicit length into a Haskell string.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newCString\ ::\ String\ ->\ IO\ CString
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a NUL terminated C string.
+\par
+\begin{itemize}
+\item
+ the Haskell string may \emph{not} contain any NUL characters
+\par
+
+\item
+ new storage is allocated for the C string and must be
+   explicitly freed using \haddocktt{Foreign.Marshal.Alloc.free} or
+   \haddocktt{Foreign.Marshal.Alloc.finalizerFree}.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newCStringLen\ ::\ String\ ->\ IO\ CStringLen
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a C string (ie, character array) with
+ explicit length information.
+\par
+\begin{itemize}
+\item
+ new storage is allocated for the C string and must be
+   explicitly freed using \haddocktt{Foreign.Marshal.Alloc.free} or
+   \haddocktt{Foreign.Marshal.Alloc.finalizerFree}.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withCString\ ::\ String\ ->\ (CString\ ->\ IO\ a)\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a NUL terminated C string using temporary
+ storage.
+\par
+\begin{itemize}
+\item
+ the Haskell string may \emph{not} contain any NUL characters
+\par
+
+\item
+ the memory is freed when the subcomputation terminates (either
+   normally or via an exception), so the pointer to the temporary
+   storage must \emph{not} be used after this.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withCStringLen\ ::\ String\ ->\ (CStringLen\ ->\ IO\ a)\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a C string (ie, character array)
+ in temporary storage, with explicit length information.
+\par
+\begin{itemize}
+\item
+ the memory is freed when the subcomputation terminates (either
+   normally or via an exception), so the pointer to the temporary
+   storage must \emph{not} be used after this.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+charIsRepresentable\ ::\ Char\ ->\ IO\ Bool
+\end{tabular}]\haddockbegindoc
+Determines whether a character can be accurately encoded in a \haddockid{CString}.
+ Unrepresentable characters are converted to \haddocktt{'?'}.
+\par
+Currently only Latin-1 characters are representable.
+\par
+
+\end{haddockdesc}
+\subsection{Using 8-bit characters
+}
+These variants of the above functions are for use with C libraries
+ that are ignorant of Unicode.  These functions should be used with
+ care, as a loss of information can occur.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+castCharToCChar\ ::\ Char\ ->\ CChar
+\end{tabular}]\haddockbegindoc
+Convert a Haskell character to a C character.
+ This function is only safe on the first 256 characters.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+castCCharToChar\ ::\ CChar\ ->\ Char
+\end{tabular}]\haddockbegindoc
+Convert a C byte, representing a Latin-1 character, to the corresponding
+ Haskell character.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekCAString\ ::\ CString\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+Marshal a NUL terminated C string into a Haskell string.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekCAStringLen\ ::\ CStringLen\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+Marshal a C string with explicit length into a Haskell string.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newCAString\ ::\ String\ ->\ IO\ CString
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a NUL terminated C string.
+\par
+\begin{itemize}
+\item
+ the Haskell string may \emph{not} contain any NUL characters
+\par
+
+\item
+ new storage is allocated for the C string and must be
+   explicitly freed using \haddocktt{Foreign.Marshal.Alloc.free} or
+   \haddocktt{Foreign.Marshal.Alloc.finalizerFree}.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newCAStringLen\ ::\ String\ ->\ IO\ CStringLen
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a C string (ie, character array) with
+ explicit length information.
+\par
+\begin{itemize}
+\item
+ new storage is allocated for the C string and must be
+   explicitly freed using \haddocktt{Foreign.Marshal.Alloc.free} or
+   \haddocktt{Foreign.Marshal.Alloc.finalizerFree}.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withCAString\ ::\ String\ ->\ (CString\ ->\ IO\ a)\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a NUL terminated C string using temporary
+ storage.
+\par
+\begin{itemize}
+\item
+ the Haskell string may \emph{not} contain any NUL characters
+\par
+
+\item
+ the memory is freed when the subcomputation terminates (either
+   normally or via an exception), so the pointer to the temporary
+   storage must \emph{not} be used after this.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withCAStringLen\ ::\ String\ ->\ (CStringLen\ ->\ IO\ a)\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a C string (ie, character array)
+ in temporary storage, with explicit length information.
+\par
+\begin{itemize}
+\item
+ the memory is freed when the subcomputation terminates (either
+   normally or via an exception), so the pointer to the temporary
+   storage must \emph{not} be used after this.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\section{C wide strings
+}
+These variants of the above functions are for use with C libraries
+ that encode Unicode using the C \haddocktt{wchar{\char '137}t} type in a system-dependent
+ way.  The only encodings supported are
+\par
+\begin{itemize}
+\item
+ UTF-32 (the C compiler defines \haddocktt{{\char '137}{\char '137}STDC{\char '137}ISO{\char '137}10646{\char '137}{\char '137}}), or
+\par
+
+\item
+ UTF-16 (as used on Windows systems).
+\par
+
+\end{itemize}
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ CWString\ =\ Ptr\ CWchar
+\end{tabular}]\haddockbegindoc
+A C wide string is a reference to an array of C wide characters
+ terminated by NUL.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ CWStringLen\ =\ (Ptr\ CWchar,\ Int)
+\end{tabular}]\haddockbegindoc
+A wide character string with explicit length information in \haddockid{CWchar}s
+ instead of a terminating NUL (allowing NUL characters in the middle
+ of the string).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekCWString\ ::\ CWString\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+Marshal a NUL terminated C wide string into a Haskell string.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekCWStringLen\ ::\ CWStringLen\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+Marshal a C wide string with explicit length into a Haskell string.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newCWString\ ::\ String\ ->\ IO\ CWString
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a NUL terminated C wide string.
+\par
+\begin{itemize}
+\item
+ the Haskell string may \emph{not} contain any NUL characters
+\par
+
+\item
+ new storage is allocated for the C wide string and must
+   be explicitly freed using \haddocktt{Foreign.Marshal.Alloc.free} or
+   \haddocktt{Foreign.Marshal.Alloc.finalizerFree}.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newCWStringLen\ ::\ String\ ->\ IO\ CWStringLen
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a C wide string (ie, wide character array)
+ with explicit length information.
+\par
+\begin{itemize}
+\item
+ new storage is allocated for the C wide string and must
+   be explicitly freed using \haddocktt{Foreign.Marshal.Alloc.free} or
+   \haddocktt{Foreign.Marshal.Alloc.finalizerFree}.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withCWString\ ::\ String\ ->\ (CWString\ ->\ IO\ a)\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a NUL terminated C wide string using
+ temporary storage.
+\par
+\begin{itemize}
+\item
+ the Haskell string may \emph{not} contain any NUL characters
+\par
+
+\item
+ the memory is freed when the subcomputation terminates (either
+   normally or via an exception), so the pointer to the temporary
+   storage must \emph{not} be used after this.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withCWStringLen\ ::\ String\ ->\ (CWStringLen\ ->\ IO\ a)\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Marshal a Haskell string into a NUL terminated C wide string using
+ temporary storage.
+\par
+\begin{itemize}
+\item
+ the Haskell string may \emph{not} contain any NUL characters
+\par
+
+\item
+ the memory is freed when the subcomputation terminates (either
+   normally or via an exception), so the pointer to the temporary
+   storage must \emph{not} be used after this.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-C-Types.tex b/report/libs/Foreign-C-Types.tex
new file mode 100644 (file)
index 0000000..67979bb
--- /dev/null
@@ -0,0 +1,420 @@
+\chapter{\texttt{Foreign.C.Types}}
+\label{module:Foreign.C.Types}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.C.Types (
+    CChar,  CSChar,  CUChar,  CShort,  CUShort,  CInt,  CUInt,  CLong,  CULong, 
+    CPtrdiff,  CSize,  CWchar,  CSigAtomic,  CLLong,  CULLong,  CIntPtr, 
+    CUIntPtr,  CIntMax,  CUIntMax,  CClock,  CTime,  CFloat,  CDouble,  CFile, 
+    CFpos,  CJmpBuf
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{Representations of C types
+}
+These types are needed to accurately represent C function prototypes,
+in order to access C library interfaces in Haskell.  The Haskell system
+is not required to represent those types exactly as C does, but the
+following guarantees are provided concerning a Haskell type \haddocktt{CT}
+representing a C type \haddocktt{t}:
+\par
+\begin{itemize}
+\item
+ If a C function prototype has \haddocktt{t} as an argument or result type, the
+  use of \haddocktt{CT} in the corresponding position in a foreign declaration
+  permits the Haskell program to access the full range of values encoded
+  by the C type; and conversely, any Haskell value for \haddocktt{CT} has a valid
+  representation in C.
+\par
+
+\item
+ \haddocktt{\haddocktt{sizeOf}\ (undefined\ ::\ CT)} will yield the same value as
+  \haddocktt{sizeof\ (t)} in C.
+\par
+
+\item
+ \haddocktt{\haddocktt{alignment}\ (undefined\ ::\ CT)} matches the alignment
+  constraint enforced by the C implementation for \haddocktt{t}.
+\par
+
+\item
+ The members \haddocktt{peek} and \haddocktt{poke} of the \haddocktt{Storable} class map all values
+  of \haddocktt{CT} to the corresponding value of \haddocktt{t} and vice versa.
+\par
+
+\item
+ When an instance of \haddockid{Bounded} is defined for \haddocktt{CT}, the values
+  of \haddockid{minBound} and \haddockid{maxBound} coincide with \haddocktt{t{\char '137}MIN}
+  and \haddocktt{t{\char '137}MAX} in C.
+\par
+
+\item
+ When an instance of \haddockid{Eq} or \haddockid{Ord} is defined for \haddocktt{CT},
+  the predicates defined by the type class implement the same relation
+  as the corresponding predicate in C on \haddocktt{t}.
+\par
+
+\item
+ When an instance of \haddockid{Num}, \haddockid{Read}, \haddockid{Integral},
+  \haddockid{Fractional}, \haddockid{Floating}, \haddockid{RealFrac}, or
+  \haddockid{RealFloat} is defined for \haddocktt{CT}, the arithmetic operations
+  defined by the type class implement the same function as the
+  corresponding arithmetic operations (if available) in C on \haddocktt{t}.
+\par
+
+\item
+ When an instance of \haddocktt{Bits} is defined for \haddocktt{CT}, the bitwise operation
+  defined by the type class implement the same function as the
+  corresponding bitwise operation in C on \haddocktt{t}.
+\par
+
+\end{itemize}
+
+\subsection{Integral types
+}
+These types are are represented as \haddocktt{newtype}s of
+ types in \haddocktt{Data.Int} and \haddocktt{Data.Word}, and are instances of
+ \haddockid{Eq}, \haddockid{Ord}, \haddockid{Num}, \haddockid{Read},
+ \haddockid{Show}, \haddockid{Enum}, \haddocktt{Typeable}, \haddocktt{Storable},
+ \haddockid{Bounded}, \haddockid{Real}, \haddockid{Integral} and
+ \haddocktt{Bits}.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CChar
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{char} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CChar\\instance\ Enum\ CChar\\instance\ Eq\ CChar\\instance\ Integral\ CChar\\instance\ Num\ CChar\\instance\ Ord\ CChar\\instance\ Read\ CChar\\instance\ Real\ CChar\\instance\ Show\ CChar\\instance\ Typeable\ CChar\\instance\ Storable\ CChar\\instance\ Bits\ CChar
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CSChar
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{signed\ char} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CSChar\\instance\ Enum\ CSChar\\instance\ Eq\ CSChar\\instance\ Integral\ CSChar\\instance\ Num\ CSChar\\instance\ Ord\ CSChar\\instance\ Read\ CSChar\\instance\ Real\ CSChar\\instance\ Show\ CSChar\\instance\ Typeable\ CSChar\\instance\ Storable\ CSChar\\instance\ Bits\ CSChar
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CUChar
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{unsigned\ char} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CUChar\\instance\ Enum\ CUChar\\instance\ Eq\ CUChar\\instance\ Integral\ CUChar\\instance\ Num\ CUChar\\instance\ Ord\ CUChar\\instance\ Read\ CUChar\\instance\ Real\ CUChar\\instance\ Show\ CUChar\\instance\ Typeable\ CUChar\\instance\ Storable\ CUChar\\instance\ Bits\ CUChar
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CShort
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{short} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CShort\\instance\ Enum\ CShort\\instance\ Eq\ CShort\\instance\ Integral\ CShort\\instance\ Num\ CShort\\instance\ Ord\ CShort\\instance\ Read\ CShort\\instance\ Real\ CShort\\instance\ Show\ CShort\\instance\ Typeable\ CShort\\instance\ Storable\ CShort\\instance\ Bits\ CShort
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CUShort
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{unsigned\ short} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CUShort\\instance\ Enum\ CUShort\\instance\ Eq\ CUShort\\instance\ Integral\ CUShort\\instance\ Num\ CUShort\\instance\ Ord\ CUShort\\instance\ Read\ CUShort\\instance\ Real\ CUShort\\instance\ Show\ CUShort\\instance\ Typeable\ CUShort\\instance\ Storable\ CUShort\\instance\ Bits\ CUShort
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CInt
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{int} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CInt\\instance\ Enum\ CInt\\instance\ Eq\ CInt\\instance\ Integral\ CInt\\instance\ Num\ CInt\\instance\ Ord\ CInt\\instance\ Read\ CInt\\instance\ Real\ CInt\\instance\ Show\ CInt\\instance\ Typeable\ CInt\\instance\ Storable\ CInt\\instance\ Bits\ CInt
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CUInt
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{unsigned\ int} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CUInt\\instance\ Enum\ CUInt\\instance\ Eq\ CUInt\\instance\ Integral\ CUInt\\instance\ Num\ CUInt\\instance\ Ord\ CUInt\\instance\ Read\ CUInt\\instance\ Real\ CUInt\\instance\ Show\ CUInt\\instance\ Typeable\ CUInt\\instance\ Storable\ CUInt\\instance\ Bits\ CUInt
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CLong
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{long} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CLong\\instance\ Enum\ CLong\\instance\ Eq\ CLong\\instance\ Integral\ CLong\\instance\ Num\ CLong\\instance\ Ord\ CLong\\instance\ Read\ CLong\\instance\ Real\ CLong\\instance\ Show\ CLong\\instance\ Typeable\ CLong\\instance\ Storable\ CLong\\instance\ Bits\ CLong
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CULong
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{unsigned\ long} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CULong\\instance\ Enum\ CULong\\instance\ Eq\ CULong\\instance\ Integral\ CULong\\instance\ Num\ CULong\\instance\ Ord\ CULong\\instance\ Read\ CULong\\instance\ Real\ CULong\\instance\ Show\ CULong\\instance\ Typeable\ CULong\\instance\ Storable\ CULong\\instance\ Bits\ CULong
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CPtrdiff
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{ptrdiff{\char '137}t} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CPtrdiff\\instance\ Enum\ CPtrdiff\\instance\ Eq\ CPtrdiff\\instance\ Integral\ CPtrdiff\\instance\ Num\ CPtrdiff\\instance\ Ord\ CPtrdiff\\instance\ Read\ CPtrdiff\\instance\ Real\ CPtrdiff\\instance\ Show\ CPtrdiff\\instance\ Typeable\ CPtrdiff\\instance\ Storable\ CPtrdiff\\instance\ Bits\ CPtrdiff
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CSize
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{size{\char '137}t} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CSize\\instance\ Enum\ CSize\\instance\ Eq\ CSize\\instance\ Integral\ CSize\\instance\ Num\ CSize\\instance\ Ord\ CSize\\instance\ Read\ CSize\\instance\ Real\ CSize\\instance\ Show\ CSize\\instance\ Typeable\ CSize\\instance\ Storable\ CSize\\instance\ Bits\ CSize
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CWchar
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{wchar{\char '137}t} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CWchar\\instance\ Enum\ CWchar\\instance\ Eq\ CWchar\\instance\ Integral\ CWchar\\instance\ Num\ CWchar\\instance\ Ord\ CWchar\\instance\ Read\ CWchar\\instance\ Real\ CWchar\\instance\ Show\ CWchar\\instance\ Typeable\ CWchar\\instance\ Storable\ CWchar\\instance\ Bits\ CWchar
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CSigAtomic
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{sig{\char '137}atomic{\char '137}t} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CSigAtomic\\instance\ Enum\ CSigAtomic\\instance\ Eq\ CSigAtomic\\instance\ Integral\ CSigAtomic\\instance\ Num\ CSigAtomic\\instance\ Ord\ CSigAtomic\\instance\ Read\ CSigAtomic\\instance\ Real\ CSigAtomic\\instance\ Show\ CSigAtomic\\instance\ Typeable\ CSigAtomic\\instance\ Storable\ CSigAtomic\\instance\ Bits\ CSigAtomic
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CLLong
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{long\ long} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CLLong\\instance\ Enum\ CLLong\\instance\ Eq\ CLLong\\instance\ Integral\ CLLong\\instance\ Num\ CLLong\\instance\ Ord\ CLLong\\instance\ Read\ CLLong\\instance\ Real\ CLLong\\instance\ Show\ CLLong\\instance\ Typeable\ CLLong\\instance\ Storable\ CLLong\\instance\ Bits\ CLLong
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CULLong
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{unsigned\ long\ long} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CULLong\\instance\ Enum\ CULLong\\instance\ Eq\ CULLong\\instance\ Integral\ CULLong\\instance\ Num\ CULLong\\instance\ Ord\ CULLong\\instance\ Read\ CULLong\\instance\ Real\ CULLong\\instance\ Show\ CULLong\\instance\ Typeable\ CULLong\\instance\ Storable\ CULLong\\instance\ Bits\ CULLong
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CIntPtr
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CIntPtr\\instance\ Enum\ CIntPtr\\instance\ Eq\ CIntPtr\\instance\ Integral\ CIntPtr\\instance\ Num\ CIntPtr\\instance\ Ord\ CIntPtr\\instance\ Read\ CIntPtr\\instance\ Real\ CIntPtr\\instance\ Show\ CIntPtr\\instance\ Typeable\ CIntPtr\\instance\ Storable\ CIntPtr\\instance\ Bits\ CIntPtr
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CUIntPtr
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CUIntPtr\\instance\ Enum\ CUIntPtr\\instance\ Eq\ CUIntPtr\\instance\ Integral\ CUIntPtr\\instance\ Num\ CUIntPtr\\instance\ Ord\ CUIntPtr\\instance\ Read\ CUIntPtr\\instance\ Real\ CUIntPtr\\instance\ Show\ CUIntPtr\\instance\ Typeable\ CUIntPtr\\instance\ Storable\ CUIntPtr\\instance\ Bits\ CUIntPtr
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CIntMax
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CIntMax\\instance\ Enum\ CIntMax\\instance\ Eq\ CIntMax\\instance\ Integral\ CIntMax\\instance\ Num\ CIntMax\\instance\ Ord\ CIntMax\\instance\ Read\ CIntMax\\instance\ Real\ CIntMax\\instance\ Show\ CIntMax\\instance\ Typeable\ CIntMax\\instance\ Storable\ CIntMax\\instance\ Bits\ CIntMax
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CUIntMax
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Bounded\ CUIntMax\\instance\ Enum\ CUIntMax\\instance\ Eq\ CUIntMax\\instance\ Integral\ CUIntMax\\instance\ Num\ CUIntMax\\instance\ Ord\ CUIntMax\\instance\ Read\ CUIntMax\\instance\ Real\ CUIntMax\\instance\ Show\ CUIntMax\\instance\ Typeable\ CUIntMax\\instance\ Storable\ CUIntMax\\instance\ Bits\ CUIntMax
+\end{tabular}]
+\end{haddockdesc}
+\subsection{Numeric types
+}
+These types are are represented as \haddocktt{newtype}s of basic
+ foreign types, and are instances of
+ \haddockid{Eq}, \haddockid{Ord}, \haddockid{Num}, \haddockid{Read},
+ \haddockid{Show}, \haddockid{Enum}, \haddocktt{Typeable} and \haddocktt{Storable}.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CClock
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{clock{\char '137}t} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Enum\ CClock\\instance\ Eq\ CClock\\instance\ Num\ CClock\\instance\ Ord\ CClock\\instance\ Read\ CClock\\instance\ Real\ CClock\\instance\ Show\ CClock\\instance\ Typeable\ CClock\\instance\ Storable\ CClock
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CTime
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{time{\char '137}t} type.
+\par
+To convert to a \haddocktt{Data.Time.UTCTime}, use the following formula:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+  posixSecondsToUTCTime (realToFrac :: POSIXTime)
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Enum\ CTime\\instance\ Eq\ CTime\\instance\ Num\ CTime\\instance\ Ord\ CTime\\instance\ Read\ CTime\\instance\ Real\ CTime\\instance\ Show\ CTime\\instance\ Typeable\ CTime\\instance\ Storable\ CTime
+\end{tabular}]
+\end{haddockdesc}
+\subsection{Floating types
+}
+These types are are represented as \haddocktt{newtype}s of
+ \haddockid{Float} and \haddockid{Double}, and are instances of
+ \haddockid{Eq}, \haddockid{Ord}, \haddockid{Num}, \haddockid{Read},
+ \haddockid{Show}, \haddockid{Enum}, \haddocktt{Typeable}, \haddocktt{Storable},
+ \haddockid{Real}, \haddockid{Fractional}, \haddockid{Floating},
+ \haddockid{RealFrac} and \haddockid{RealFloat}.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CFloat
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{float} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Enum\ CFloat\\instance\ Eq\ CFloat\\instance\ Floating\ CFloat\\instance\ Fractional\ CFloat\\instance\ Num\ CFloat\\instance\ Ord\ CFloat\\instance\ Read\ CFloat\\instance\ Real\ CFloat\\instance\ RealFloat\ CFloat\\instance\ RealFrac\ CFloat\\instance\ Show\ CFloat\\instance\ Typeable\ CFloat\\instance\ Storable\ CFloat
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CDouble
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{double} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Enum\ CDouble\\instance\ Eq\ CDouble\\instance\ Floating\ CDouble\\instance\ Fractional\ CDouble\\instance\ Num\ CDouble\\instance\ Ord\ CDouble\\instance\ Read\ CDouble\\instance\ Real\ CDouble\\instance\ RealFloat\ CDouble\\instance\ RealFrac\ CDouble\\instance\ Show\ CDouble\\instance\ Typeable\ CDouble\\instance\ Storable\ CDouble
+\end{tabular}]
+\end{haddockdesc}
+\subsection{Other types
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CFile
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{FILE} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CFpos
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{fpos{\char '137}t} type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ CJmpBuf
+\end{tabular}]\haddockbegindoc
+Haskell type representing the C \haddocktt{jmp{\char '137}buf} type.
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-C.tex b/report/libs/Foreign-C.tex
new file mode 100644 (file)
index 0000000..6e63c9a
--- /dev/null
@@ -0,0 +1,18 @@
+\chapter{\texttt{Foreign.C}}
+\label{module:Foreign.C}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.C (
+    module Foreign.C.Types,  module Foreign.C.String,  module Foreign.C.Error
+  ) where\end{verbatim}}
+\haddockendheader
+
+The module \haddocktt{Foreign.C} combines the interfaces of all
+ modules providing C-specific marshalling support, namely
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+module\ Foreign.C.Types\\module\ Foreign.C.String\\module\ Foreign.C.Error
+\end{tabular}]
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-ForeignPtr.tex b/report/libs/Foreign-ForeignPtr.tex
new file mode 100644 (file)
index 0000000..35ab3fd
--- /dev/null
@@ -0,0 +1,260 @@
+\chapter{\texttt{Foreign.ForeignPtr}}
+\label{module:Foreign.ForeignPtr}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.ForeignPtr (
+    ForeignPtr,  FinalizerPtr,  FinalizerEnvPtr,  newForeignPtr, 
+    newForeignPtr_,  addForeignPtrFinalizer,  newForeignPtrEnv, 
+    addForeignPtrFinalizerEnv,  withForeignPtr,  unsafeForeignPtrToPtr, 
+    touchForeignPtr,  castForeignPtr,  mallocForeignPtr, 
+    mallocForeignPtrBytes,  mallocForeignPtrArray,  mallocForeignPtrArray0
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{Finalised data pointers
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ ForeignPtr\ a
+\end{tabular}]\haddockbegindoc
+The type \haddockid{ForeignPtr} represents references to objects that are
+ maintained in a foreign language, i.e., that are not part of the
+ data structures usually managed by the Haskell storage manager.
+ The essential difference between \haddockid{ForeignPtr}s and vanilla memory
+ references of type \haddocktt{Ptr\ a} is that the former may be associated
+ with \emph{finalizers}. A finalizer is a routine that is invoked when
+ the Haskell storage manager detects that - within the Haskell heap
+ and stack - there are no more references left that are pointing to
+ the \haddockid{ForeignPtr}.  Typically, the finalizer will, then, invoke
+ routines in the foreign language that free the resources bound by
+ the foreign object.
+\par
+The \haddockid{ForeignPtr} is parameterised in the same way as \haddockid{Ptr}.  The
+ type argument of \haddockid{ForeignPtr} should normally be an instance of
+ class \haddockid{Storable}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Typeable1\ ForeignPtr\\instance\ Eq\ (ForeignPtr\ a)\\instance\ Ord\ (ForeignPtr\ a)\\instance\ Show\ (ForeignPtr\ a)
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ FinalizerPtr\ a\ =\ FunPtr\ (Ptr\ a\ ->\ IO\ ())
+\end{tabular}]\haddockbegindoc
+A Finalizer is represented as a pointer to a foreign function that, at
+ finalisation time, gets as an argument a plain pointer variant of the
+ foreign pointer that the finalizer is associated with.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ FinalizerEnvPtr\ env\ a\ =\ FunPtr\ (Ptr\ env\ ->\ Ptr\ a\ ->\ IO\ ())
+\end{tabular}]
+\end{haddockdesc}
+\subsection{Basic operations
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newForeignPtr\ ::\ FinalizerPtr\ a\ ->\ Ptr\ a\ ->\ IO\ (ForeignPtr\ a)
+\end{tabular}]\haddockbegindoc
+Turns a plain memory reference into a foreign pointer, and
+ associates a finaliser with the reference.  The finaliser will be
+ executed after the last reference to the foreign object is dropped.
+ There is no guarantee of promptness, however the finalizer will be
+ executed before the program exits.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newForeignPtr{\char '137}\ ::\ Ptr\ a\ ->\ IO\ (ForeignPtr\ a)
+\end{tabular}]\haddockbegindoc
+Turns a plain memory reference into a foreign pointer that may be
+ associated with finalizers by using \haddockid{addForeignPtrFinalizer}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+addForeignPtrFinalizer\ ::\ FinalizerPtr\ a\ ->\ ForeignPtr\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+This function adds a finalizer to the given foreign object.  The
+ finalizer will run \emph{before} all other finalizers for the same
+ object which have already been registered.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newForeignPtrEnv\ ::\ FinalizerEnvPtr\ env\ a\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ Ptr\ env\ ->\ Ptr\ a\ ->\ IO\ (ForeignPtr\ a)
+\end{tabular}]\haddockbegindoc
+This variant of \haddockid{newForeignPtr} adds a finalizer that expects an
+ environment in addition to the finalized pointer.  The environment
+ that will be passed to the finalizer is fixed by the second argument to
+ \haddockid{newForeignPtrEnv}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+addForeignPtrFinalizerEnv\ ::\ FinalizerEnvPtr\ env\ a\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ Ptr\ env\ ->\ ForeignPtr\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+like \haddockid{addForeignPtrFinalizerEnv} but allows the finalizer to be
+ passed an additional environment parameter to be passed to the
+ finalizer.  The environment passed to the finalizer is fixed by the
+ second argument to \haddockid{addForeignPtrFinalizerEnv}
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withForeignPtr\ ::\ ForeignPtr\ a\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+This is a way to look at the pointer living inside a
+ foreign object.  This function takes a function which is
+ applied to that pointer. The resulting \haddockid{IO} action is then
+ executed. The foreign object is kept alive at least during
+ the whole action, even if it is not used directly
+ inside. Note that it is not safe to return the pointer from
+ the action and use it after the action completes. All uses
+ of the pointer should be inside the
+ \haddockid{withForeignPtr} bracket.  The reason for
+ this unsafeness is the same as for
+ \haddockid{unsafeForeignPtrToPtr} below: the finalizer
+ may run earlier than expected, because the compiler can only
+ track usage of the \haddockid{ForeignPtr} object, not
+ a \haddockid{Ptr} object made from it.
+\par
+This function is normally used for marshalling data to
+ or from the object pointed to by the
+ \haddockid{ForeignPtr}, using the operations from the
+ \haddockid{Storable} class.
+\par
+
+\end{haddockdesc}
+\subsection{Low-level operations
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unsafeForeignPtrToPtr\ ::\ ForeignPtr\ a\ ->\ Ptr\ a
+\end{tabular}]\haddockbegindoc
+This function extracts the pointer component of a foreign
+ pointer.  This is a potentially dangerous operations, as if the
+ argument to \haddockid{unsafeForeignPtrToPtr} is the last usage
+ occurrence of the given foreign pointer, then its finalizer(s) will
+ be run, which potentially invalidates the plain pointer just
+ obtained.  Hence, \haddockid{touchForeignPtr} must be used
+ wherever it has to be guaranteed that the pointer lives on - i.e.,
+ has another usage occurrence.
+\par
+To avoid subtle coding errors, hand written marshalling code
+ should preferably use \haddocktt{Foreign.ForeignPtr.withForeignPtr} rather
+ than combinations of \haddockid{unsafeForeignPtrToPtr} and
+ \haddockid{touchForeignPtr}.  However, the latter routines
+ are occasionally preferred in tool generated marshalling code.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+touchForeignPtr\ ::\ ForeignPtr\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+This function ensures that the foreign object in
+ question is alive at the given place in the sequence of IO
+ actions. In particular \haddocktt{Foreign.ForeignPtr.withForeignPtr}
+ does a \haddockid{touchForeignPtr} after it
+ executes the user action.
+\par
+Note that this function should not be used to express dependencies
+ between finalizers on \haddockid{ForeignPtr}s.  For example, if the finalizer
+ for a \haddockid{ForeignPtr} \haddocktt{F1} calls \haddockid{touchForeignPtr} on a second
+ \haddockid{ForeignPtr} \haddocktt{F2}, then the only guarantee is that the finalizer
+ for \haddocktt{F2} is never started before the finalizer for \haddocktt{F1}.  They
+ might be started together if for example both \haddocktt{F1} and \haddocktt{F2} are
+ otherwise unreachable, and in that case the scheduler might end up
+ running the finalizer for \haddocktt{F2} first.
+\par
+In general, it is not recommended to use finalizers on separate
+ objects with ordering constraints between them.  To express the
+ ordering robustly requires explicit synchronisation using \haddocktt{MVar}s
+ between the finalizers, but even then the runtime sometimes runs
+ multiple finalizers sequentially in a single thread (for
+ performance reasons), so synchronisation between finalizers could
+ result in artificial deadlock.  Another alternative is to use
+ explicit reference counting.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+castForeignPtr\ ::\ ForeignPtr\ a\ ->\ ForeignPtr\ b
+\end{tabular}]\haddockbegindoc
+This function casts a \haddockid{ForeignPtr}
+ parameterised by one type into another type.
+\par
+
+\end{haddockdesc}
+\subsection{Allocating managed memory
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mallocForeignPtr\ ::\ Storable\ a\ =>\ IO\ (ForeignPtr\ a)
+\end{tabular}]\haddockbegindoc
+Allocate some memory and return a \haddockid{ForeignPtr} to it.  The memory
+ will be released automatically when the \haddockid{ForeignPtr} is discarded.
+\par
+\haddockid{mallocForeignPtr} is equivalent to
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+    do { p <- malloc; newForeignPtr finalizerFree p }
+\end{verbatim}}
+\end{quote}
+although it may be implemented differently internally: you may not
+ assume that the memory returned by \haddockid{mallocForeignPtr} has been
+ allocated with \haddocktt{Foreign.Marshal.Alloc.malloc}.
+\par
+GHC notes: \haddockid{mallocForeignPtr} has a heavily optimised
+ implementation in GHC.  It uses pinned memory in the garbage
+ collected heap, so the \haddockid{ForeignPtr} does not require a finalizer to
+ free the memory.  Use of \haddockid{mallocForeignPtr} and associated
+ functions is strongly recommended in preference to \haddocktt{newForeignPtr}
+ with a finalizer.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mallocForeignPtrBytes\ ::\ Int\ ->\ IO\ (ForeignPtr\ a)
+\end{tabular}]\haddockbegindoc
+This function is similar to \haddockid{mallocForeignPtr}, except that the
+ size of the memory required is given explicitly as a number of bytes.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mallocForeignPtrArray\ ::\ Storable\ a\ =>\ Int\ ->\ IO\ (ForeignPtr\ a)
+\end{tabular}]\haddockbegindoc
+This function is similar to \haddocktt{Foreign.Marshal.Array.mallocArray},
+ but yields a memory area that has a finalizer attached that releases
+ the memory area.  As with \haddockid{mallocForeignPtr}, it is not guaranteed that
+ the block of memory was allocated by \haddocktt{Foreign.Marshal.Alloc.malloc}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mallocForeignPtrArray0\ ::\ Storable\ a\ =>\ Int\ ->\ IO\ (ForeignPtr\ a)
+\end{tabular}]\haddockbegindoc
+This function is similar to \haddocktt{Foreign.Marshal.Array.mallocArray0},
+ but yields a memory area that has a finalizer attached that releases
+ the memory area.  As with \haddockid{mallocForeignPtr}, it is not guaranteed that
+ the block of memory was allocated by \haddocktt{Foreign.Marshal.Alloc.malloc}.
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-Marshal-Alloc.tex b/report/libs/Foreign-Marshal-Alloc.tex
new file mode 100644 (file)
index 0000000..44746c4
--- /dev/null
@@ -0,0 +1,142 @@
+\chapter{\texttt{Foreign.Marshal.Alloc}}
+\label{module:Foreign.Marshal.Alloc}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.Marshal.Alloc (
+    alloca,  allocaBytes,  malloc,  mallocBytes,  realloc,  reallocBytes, 
+    free,  finalizerFree
+  ) where\end{verbatim}}
+\haddockendheader
+
+The module \haddocktt{Foreign.Marshal.Alloc} provides operations to allocate and
+deallocate blocks of raw memory (i.e., unstructured chunks of memory
+outside of the area maintained by the Haskell storage manager).  These
+memory blocks are commonly used to pass compound data structures to
+foreign functions or to provide space in which compound result values
+are obtained from foreign functions.
+\par
+If any of the allocation functions fails, a value of \haddocktt{nullPtr} is
+produced.  If \haddockid{free} or \haddockid{reallocBytes} is applied to a memory area
+that has been allocated with \haddockid{alloca} or \haddockid{allocaBytes}, the
+behaviour is undefined.  Any further access to memory areas allocated with
+\haddockid{alloca} or \haddockid{allocaBytes}, after the computation that was passed to
+the allocation function has terminated, leads to undefined behaviour.  Any
+further access to the memory area referenced by a pointer passed to
+\haddockid{realloc}, \haddockid{reallocBytes}, or \haddockid{free} entails undefined
+behaviour.
+\par
+
+\section{Memory allocation
+}
+\subsection{Local allocation
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+alloca\ ::\ Storable\ a\ =>\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+\haddocktt{alloca\ f} executes the computation \haddocktt{f}, passing as argument
+ a pointer to a temporarily allocated block of memory sufficient to
+ hold values of type \haddocktt{a}.
+\par
+The memory is freed when \haddocktt{f} terminates (either normally or via an
+ exception), so the pointer passed to \haddocktt{f} must \emph{not} be used after this.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+allocaBytes\ ::\ Int\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+\haddocktt{allocaBytes\ n\ f} executes the computation \haddocktt{f}, passing as argument
+ a pointer to a temporarily allocated block of memory of \haddocktt{n} bytes.
+ The block of memory is sufficiently aligned for any of the basic
+ foreign types that fits into a memory block of the allocated size.
+\par
+The memory is freed when \haddocktt{f} terminates (either normally or via an
+ exception), so the pointer passed to \haddocktt{f} must \emph{not} be used after this.
+\par
+
+\end{haddockdesc}
+\subsection{Dynamic allocation
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+malloc\ ::\ Storable\ a\ =>\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Allocate a block of memory that is sufficient to hold values of type
+ \haddocktt{a}.  The size of the area allocated is determined by the \haddockid{sizeOf}
+ method from the instance of \haddockid{Storable} for the appropriate type.
+\par
+The memory may be deallocated using \haddockid{free} or \haddockid{finalizerFree} when
+ no longer required.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mallocBytes\ ::\ Int\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Allocate a block of memory of the given number of bytes.
+ The block of memory is sufficiently aligned for any of the basic
+ foreign types that fits into a memory block of the allocated size.
+\par
+The memory may be deallocated using \haddockid{free} or \haddockid{finalizerFree} when
+ no longer required.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+realloc\ ::\ Storable\ b\ =>\ Ptr\ a\ ->\ IO\ (Ptr\ b)
+\end{tabular}]\haddockbegindoc
+Resize a memory area that was allocated with \haddockid{malloc} or \haddockid{mallocBytes}
+ to the size needed to store values of type \haddocktt{b}.  The returned pointer
+ may refer to an entirely different memory area, but will be suitably
+ aligned to hold values of type \haddocktt{b}.  The contents of the referenced
+ memory area will be the same as of the original pointer up to the
+ minimum of the original size and the size of values of type \haddocktt{b}.
+\par
+If the argument to \haddockid{realloc} is \haddockid{nullPtr}, \haddockid{realloc} behaves like
+ \haddockid{malloc}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+reallocBytes\ ::\ Ptr\ a\ ->\ Int\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Resize a memory area that was allocated with \haddockid{malloc} or \haddockid{mallocBytes}
+ to the given size.  The returned pointer may refer to an entirely
+ different memory area, but will be sufficiently aligned for any of the
+ basic foreign types that fits into a memory block of the given size.
+ The contents of the referenced memory area will be the same as of
+ the original pointer up to the minimum of the original size and the
+ given size.
+\par
+If the pointer argument to \haddockid{reallocBytes} is \haddockid{nullPtr}, \haddockid{reallocBytes}
+ behaves like \haddockid{malloc}.  If the requested size is 0, \haddockid{reallocBytes}
+ behaves like \haddockid{free}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+free\ ::\ Ptr\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Free a block of memory that was allocated with \haddockid{malloc},
+ \haddockid{mallocBytes}, \haddockid{realloc}, \haddockid{reallocBytes}, \haddocktt{Foreign.Marshal.Utils.new}
+ or any of the \haddocktt{new}\emph{X} functions in \haddocktt{Foreign.Marshal.Array} or
+ \haddocktt{Foreign.C.String}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+finalizerFree\ ::\ FinalizerPtr\ a
+\end{tabular}]\haddockbegindoc
+A pointer to a foreign function equivalent to \haddockid{free}, which may be
+ used as a finalizer (cf \haddocktt{Foreign.ForeignPtr.ForeignPtr}) for storage
+ allocated with \haddockid{malloc}, \haddockid{mallocBytes}, \haddockid{realloc} or \haddockid{reallocBytes}.
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-Marshal-Array.tex b/report/libs/Foreign-Marshal-Array.tex
new file mode 100644 (file)
index 0000000..ee39452
--- /dev/null
@@ -0,0 +1,218 @@
+\chapter{\texttt{Foreign.Marshal.Array}}
+\label{module:Foreign.Marshal.Array}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.Marshal.Array (
+    mallocArray,  mallocArray0,  allocaArray,  allocaArray0,  reallocArray, 
+    reallocArray0,  peekArray,  peekArray0,  pokeArray,  pokeArray0,  newArray, 
+    newArray0,  withArray,  withArray0,  withArrayLen,  withArrayLen0, 
+    copyArray,  moveArray,  lengthArray0,  advancePtr
+  ) where\end{verbatim}}
+\haddockendheader
+
+The module \haddocktt{Foreign.Marshal.Array} provides operations for marshalling Haskell
+lists into monolithic arrays and vice versa.  Most functions come in two
+flavours: one for arrays terminated by a special termination element and one
+where an explicit length parameter is used to determine the extent of an
+array.  The typical example for the former case are C's NUL terminated
+strings.  However, please note that C strings should usually be marshalled
+using the functions provided by \haddocktt{Foreign.C.String} as
+the Unicode encoding has to be taken into account.  All functions specifically
+operating on arrays that are terminated by a special termination element have
+a name ending on \haddocktt{0}---e.g., \haddockid{mallocArray} allocates space for an
+array of the given size, whereas \haddockid{mallocArray0} allocates space for one
+more element to ensure that there is room for the terminator.
+\par
+
+\section{Marshalling arrays
+}
+\subsection{Allocation
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mallocArray\ ::\ Storable\ a\ =>\ Int\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Allocate storage for the given number of elements of a storable type
+ (like \haddocktt{Foreign.Marshal.Alloc.malloc}, but for multiple elements).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mallocArray0\ ::\ Storable\ a\ =>\ Int\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Like \haddockid{mallocArray}, but add an extra position to hold a special
+ termination element.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+allocaArray\ ::\ Storable\ a\ =>\ Int\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+Temporarily allocate space for the given number of elements
+ (like \haddocktt{Foreign.Marshal.Alloc.alloca}, but for multiple elements).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+allocaArray0\ ::\ Storable\ a\ =>\ Int\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+Like \haddockid{allocaArray}, but add an extra position to hold a special
+ termination element.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+reallocArray\ ::\ Storable\ a\ =>\ Ptr\ a\ ->\ Int\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Adjust the size of an array
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+reallocArray0\ ::\ Storable\ a\ =>\ Ptr\ a\ ->\ Int\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Adjust the size of an array including an extra position for the end marker.
+\par
+
+\end{haddockdesc}
+\subsection{Marshalling
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekArray\ ::\ Storable\ a\ =>\ Int\ ->\ Ptr\ a\ ->\ IO\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+Convert an array of given length into a Haskell list.  This version
+ traverses the array backwards using an accumulating parameter,
+ which uses constant stack space.  The previous version using mapM
+ needed linear stack space.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekArray0\ ::\ (Storable\ a,\ Eq\ a)\ =>\ a\ ->\ Ptr\ a\ ->\ IO\ {\char 91}a{\char 93}
+\end{tabular}]\haddockbegindoc
+Convert an array terminated by the given end marker into a Haskell list
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+pokeArray\ ::\ Storable\ a\ =>\ Ptr\ a\ ->\ {\char 91}a{\char 93}\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Write the list elements consecutive into memory
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+pokeArray0\ ::\ Storable\ a\ =>\ a\ ->\ Ptr\ a\ ->\ {\char 91}a{\char 93}\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Write the list elements consecutive into memory and terminate them with the
+ given marker element
+\par
+
+\end{haddockdesc}
+\subsection{Combined allocation and marshalling
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newArray\ ::\ Storable\ a\ =>\ {\char 91}a{\char 93}\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Write a list of storable elements into a newly allocated, consecutive
+ sequence of storable values
+ (like \haddocktt{Foreign.Marshal.Utils.new}, but for multiple elements).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newArray0\ ::\ Storable\ a\ =>\ a\ ->\ {\char 91}a{\char 93}\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Write a list of storable elements into a newly allocated, consecutive
+ sequence of storable values, where the end is fixed by the given end marker
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withArray\ ::\ Storable\ a\ =>\ {\char 91}a{\char 93}\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+Temporarily store a list of storable values in memory
+ (like \haddocktt{Foreign.Marshal.Utils.with}, but for multiple elements).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withArray0\ ::\ Storable\ a\ =>\ a\ ->\ {\char 91}a{\char 93}\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+Like \haddockid{withArray}, but a terminator indicates where the array ends
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withArrayLen\ ::\ Storable\ a\ =>\ {\char 91}a{\char 93}\ ->\ (Int\ ->\ Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+Like \haddockid{withArray}, but the action gets the number of values
+ as an additional parameter
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withArrayLen0\ ::\ Storable\ a\ =>\ a\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ {\char 91}a{\char 93}\ ->\ (Int\ ->\ Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+Like \haddockid{withArrayLen}, but a terminator indicates where the array ends
+\par
+
+\end{haddockdesc}
+\subsection{Copying
+}
+(argument order: destination, source)
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+copyArray\ ::\ Storable\ a\ =>\ Ptr\ a\ ->\ Ptr\ a\ ->\ Int\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Copy the given number of elements from the second array (source) into the
+ first array (destination); the copied areas may \emph{not} overlap
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+moveArray\ ::\ Storable\ a\ =>\ Ptr\ a\ ->\ Ptr\ a\ ->\ Int\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Copy the given number of elements from the second array (source) into the
+ first array (destination); the copied areas \emph{may} overlap
+\par
+
+\end{haddockdesc}
+\subsection{Finding the length
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+lengthArray0\ ::\ (Storable\ a,\ Eq\ a)\ =>\ a\ ->\ Ptr\ a\ ->\ IO\ Int
+\end{tabular}]\haddockbegindoc
+Return the number of elements in an array, excluding the terminator
+\par
+
+\end{haddockdesc}
+\subsection{Indexing
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+advancePtr\ ::\ Storable\ a\ =>\ Ptr\ a\ ->\ Int\ ->\ Ptr\ a
+\end{tabular}]\haddockbegindoc
+Advance a pointer into an array by the given number of elements
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-Marshal-Error.tex b/report/libs/Foreign-Marshal-Error.tex
new file mode 100644 (file)
index 0000000..559274b
--- /dev/null
@@ -0,0 +1,71 @@
+\chapter{\texttt{Foreign.Marshal.Error}}
+\label{module:Foreign.Marshal.Error}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.Marshal.Error (
+    throwIf,  throwIf_,  throwIfNeg,  throwIfNeg_,  throwIfNull,  void
+  ) where\end{verbatim}}
+\haddockendheader
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwIf
+\end{tabular}]\haddockbegindoc
+\haddockbeginargs
+\haddockdecltt{::} & \haddockdecltt{(a
+                                     -> Bool)} & error condition on the result of the \haddockid{IO} action
+ \\
+                                                 \haddockdecltt{->} & \haddockdecltt{(a
+                                                                                      -> String)} & computes an error message from erroneous results
+ of the \haddockid{IO} action
+ \\
+                                                                                                    \haddockdecltt{->} & \haddockdecltt{IO a} & the \haddockid{IO} action to be executed
+ \\
+                                                                                                                                                \haddockdecltt{->} & \haddockdecltt{IO a} & \\
+\haddockendargs\par
+Execute an \haddockid{IO} action, throwing a \haddockid{userError} if the predicate yields
+ \haddockid{True} when applied to the result returned by the \haddockid{IO} action.
+ If no exception is raised, return the result of the computation.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwIf{\char '137}\ ::\ (a\ ->\ Bool)\ ->\ (a\ ->\ String)\ ->\ IO\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Like \haddockid{throwIf}, but discarding the result
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwIfNeg\ ::\ (Ord\ a,\ Num\ a)\ =>\ (a\ ->\ String)\ ->\ IO\ a\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Guards against negative result values
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwIfNeg{\char '137}\ ::\ (Ord\ a,\ Num\ a)\ =>\ (a\ ->\ String)\ ->\ IO\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Like \haddockid{throwIfNeg}, but discarding the result
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+throwIfNull\ ::\ String\ ->\ IO\ (Ptr\ a)\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Guards against null pointers
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+void\ ::\ IO\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Discard the return value of an \haddockid{IO} action
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-Marshal-Utils.tex b/report/libs/Foreign-Marshal-Utils.tex
new file mode 100644 (file)
index 0000000..e220905
--- /dev/null
@@ -0,0 +1,127 @@
+\chapter{\texttt{Foreign.Marshal.Utils}}
+\label{module:Foreign.Marshal.Utils}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.Marshal.Utils (
+    with,  new,  fromBool,  toBool,  maybeNew,  maybeWith,  maybePeek, 
+    withMany,  copyBytes,  moveBytes
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{General marshalling utilities
+}
+\subsection{Combined allocation and marshalling
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+with\ ::\ Storable\ a\ =>\ a\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
+\end{tabular}]\haddockbegindoc
+\haddocktt{with\ val\ f} executes the computation \haddocktt{f}, passing as argument
+ a pointer to a temporarily allocated block of memory into which
+ \haddocktt{val} has been marshalled (the combination of \haddockid{alloca} and \haddockid{poke}).
+\par
+The memory is freed when \haddocktt{f} terminates (either normally or via an
+ exception), so the pointer passed to \haddocktt{f} must \emph{not} be used after this.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+new\ ::\ Storable\ a\ =>\ a\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Allocate a block of memory and marshal a value into it
+ (the combination of \haddockid{malloc} and \haddockid{poke}).
+ The size of the area allocated is determined by the \haddocktt{Foreign.Storable.sizeOf}
+ method from the instance of \haddockid{Storable} for the appropriate type.
+\par
+The memory may be deallocated using \haddocktt{Foreign.Marshal.Alloc.free} or
+ \haddocktt{Foreign.Marshal.Alloc.finalizerFree} when no longer required.
+\par
+
+\end{haddockdesc}
+\subsection{Marshalling of Boolean values (non-zero corresponds to \haddockid{True})
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+fromBool\ ::\ Num\ a\ =>\ Bool\ ->\ a
+\end{tabular}]\haddockbegindoc
+Convert a Haskell \haddockid{Bool} to its numeric representation
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+toBool\ ::\ Num\ a\ =>\ a\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+Convert a Boolean in numeric representation to a Haskell value
+\par
+
+\end{haddockdesc}
+\subsection{Marshalling of Maybe values
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+maybeNew\ ::\ (a\ ->\ IO\ (Ptr\ a))\ ->\ Maybe\ a\ ->\ IO\ (Ptr\ a)
+\end{tabular}]\haddockbegindoc
+Allocate storage and marshall a storable value wrapped into a \haddockid{Maybe}
+\par
+\begin{itemize}
+\item
+ the \haddockid{nullPtr} is used to represent \haddockid{Nothing}
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+maybeWith\ ::\ (a\ ->\ (Ptr\ b\ ->\ IO\ c)\ ->\ IO\ c)\\\ \ \ \ \ \ \ \ \ \ \ \ \ ->\ Maybe\ a\ ->\ (Ptr\ b\ ->\ IO\ c)\ ->\ IO\ c
+\end{tabular}]\haddockbegindoc
+Converts a \haddocktt{withXXX} combinator into one marshalling a value wrapped
+ into a \haddockid{Maybe}, using \haddockid{nullPtr} to represent \haddockid{Nothing}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+maybePeek\ ::\ (Ptr\ a\ ->\ IO\ b)\ ->\ Ptr\ a\ ->\ IO\ (Maybe\ b)
+\end{tabular}]\haddockbegindoc
+Convert a peek combinator into a one returning \haddockid{Nothing} if applied to a
+ \haddockid{nullPtr} 
+\par
+
+\end{haddockdesc}
+\subsection{Marshalling lists of storable objects
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withMany\ ::\ (a\ ->\ (b\ ->\ res)\ ->\ res)\ ->\ {\char 91}a{\char 93}\ ->\ ({\char 91}b{\char 93}\ ->\ res)\ ->\ res
+\end{tabular}]\haddockbegindoc
+Replicates a \haddocktt{withXXX} combinator over a list of objects, yielding a list of
+ marshalled objects
+\par
+
+\end{haddockdesc}
+\subsection{Haskellish interface to memcpy and memmove
+}
+(argument order: destination, source)
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+copyBytes\ ::\ Ptr\ a\ ->\ Ptr\ a\ ->\ Int\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Copies the given number of bytes from the second area (source) into the
+ first (destination); the copied areas may \emph{not} overlap
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+moveBytes\ ::\ Ptr\ a\ ->\ Ptr\ a\ ->\ Int\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Copies the given number of bytes from the second area (source) into the
+ first (destination); the copied areas \emph{may} overlap
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-Marshal.tex b/report/libs/Foreign-Marshal.tex
new file mode 100644 (file)
index 0000000..e2e046d
--- /dev/null
@@ -0,0 +1,46 @@
+\chapter{\texttt{Foreign.Marshal}}
+\label{module:Foreign.Marshal}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.Marshal (
+    module Foreign.Marshal.Alloc,  module Foreign.Marshal.Array, 
+    module Foreign.Marshal.Error,  module Foreign.Marshal.Utils, 
+    unsafeLocalState
+  ) where\end{verbatim}}
+\haddockendheader
+
+The module \haddocktt{Foreign.Marshal} re-exports the other modules in the
+ \haddocktt{Foreign.Marshal} hierarchy:
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+module\ Foreign.Marshal.Alloc\\module\ Foreign.Marshal.Array\\module\ Foreign.Marshal.Error\\module\ Foreign.Marshal.Utils
+\end{tabular}]
+\end{haddockdesc}
+and provides one function:
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+unsafeLocalState\ ::\ IO\ a\ ->\ a
+\end{tabular}]\haddockbegindoc
+Sometimes an external entity is a pure function, except that it passes
+arguments and/or results via pointers.  The function
+\haddocktt{unsafeLocalState} permits the packaging of such entities as pure
+functions.  
+\par
+The only IO operations allowed in the IO action passed to
+\haddocktt{unsafeLocalState} are (a) local allocation (\haddocktt{alloca}, \haddocktt{allocaBytes}
+and derived operations such as \haddocktt{withArray} and \haddocktt{withCString}), and (b)
+pointer operations (\haddocktt{Foreign.Storable} and \haddocktt{Foreign.Ptr}) on the
+pointers to local storage, and (c) foreign functions whose only
+observable effect is to read and/or write the locally allocated
+memory.  Passing an IO operation that does not obey these rules
+results in undefined behaviour.
+\par
+It is expected that this operation will be
+replaced in a future revision of Haskell.
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-Ptr.tex b/report/libs/Foreign-Ptr.tex
new file mode 100644 (file)
index 0000000..85bb928
--- /dev/null
@@ -0,0 +1,214 @@
+\chapter{\texttt{Foreign.Ptr}}
+\label{module:Foreign.Ptr}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.Ptr (
+    Ptr,  nullPtr,  castPtr,  plusPtr,  alignPtr,  minusPtr,  FunPtr, 
+    nullFunPtr,  castFunPtr,  castFunPtrToPtr,  castPtrToFunPtr, 
+    freeHaskellFunPtr
+  ) where\end{verbatim}}
+\haddockendheader
+
+The module \haddocktt{Foreign.Ptr} provides typed pointers to foreign
+ entities.  We distinguish two kinds of pointers: pointers to data
+ and pointers to functions.  It is understood that these two kinds
+ of pointers may be represented differently as they may be
+ references to data and text segments, respectively.
+\par
+
+\section{Data pointers
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Ptr\ a
+\end{tabular}]\haddockbegindoc
+A value of type \haddocktt{Ptr\ a} represents a pointer to an object, or an
+ array of objects, which may be marshalled to or from Haskell values
+ of type \haddocktt{a}.
+\par
+The type \haddocktt{a} will often be an instance of class
+ \haddocktt{Foreign.Storable.Storable} which provides the marshalling operations.
+ However this is not essential, and you can provide your own operations
+ to access the pointer.  For example you might write small foreign
+ functions to get or set the fields of a C \haddocktt{struct}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ (Ptr\ a)\\instance\ Ord\ (Ptr\ a)\\instance\ Show\ (Ptr\ a)\\instance\ Storable\ (Ptr\ a)
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+nullPtr\ ::\ Ptr\ a
+\end{tabular}]\haddockbegindoc
+The constant \haddockid{nullPtr} contains a distinguished value of \haddockid{Ptr}
+ that is not associated with a valid memory location.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+castPtr\ ::\ Ptr\ a\ ->\ Ptr\ b
+\end{tabular}]\haddockbegindoc
+The \haddockid{castPtr} function casts a pointer from one type to another.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+plusPtr\ ::\ Ptr\ a\ ->\ Int\ ->\ Ptr\ b
+\end{tabular}]\haddockbegindoc
+Advances the given address by the given offset in bytes.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+alignPtr\ ::\ Ptr\ a\ ->\ Int\ ->\ Ptr\ a
+\end{tabular}]\haddockbegindoc
+Given an arbitrary address and an alignment constraint,
+ \haddockid{alignPtr} yields the next higher address that fulfills the
+ alignment constraint.  An alignment constraint \haddocktt{x} is fulfilled by
+ any address divisible by \haddocktt{x}.  This operation is idempotent.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+minusPtr\ ::\ Ptr\ a\ ->\ Ptr\ b\ ->\ Int
+\end{tabular}]\haddockbegindoc
+Computes the offset required to get from the second to the first
+ argument.  We have 
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ p2 == p1 `plusPtr` (p2 `minusPtr` p1)
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\section{Function pointers
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ FunPtr\ a
+\end{tabular}]\haddockbegindoc
+A value of type \haddocktt{FunPtr\ a} is a pointer to a function callable
+ from foreign code.  The type \haddocktt{a} will normally be a \emph{foreign type},
+ a function type with zero or more arguments where
+\par
+\begin{itemize}
+\item
+ the argument types are \emph{marshallable foreign types},
+   i.e. \haddockid{Char}, \haddockid{Int}, \haddocktt{Prelude.Double}, \haddocktt{Prelude.Float},
+   \haddockid{Bool}, \haddocktt{Data.Int.Int8}, \haddocktt{Data.Int.Int16}, \haddocktt{Data.Int.Int32},
+   \haddocktt{Data.Int.Int64}, \haddocktt{Data.Word.Word8}, \haddocktt{Data.Word.Word16},
+   \haddocktt{Data.Word.Word32}, \haddocktt{Data.Word.Word64}, \haddocktt{Ptr\ a}, \haddocktt{FunPtr\ a},
+   \haddocktt{\haddocktt{Foreign.StablePtr.StablePtr}\ a} or a renaming of any of these
+   using \haddocktt{newtype}.
+\par
+
+\item
+ the return type is either a marshallable foreign type or has the form
+   \haddocktt{\haddocktt{Prelude.IO}\ t} where \haddocktt{t} is a marshallable foreign type or \haddocktt{()}.
+\par
+
+\end{itemize}
+A value of type \haddocktt{FunPtr\ a} may be a pointer to a foreign function,
+ either returned by another foreign function or imported with a
+ a static address import like
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ foreign import ccall "stdlib.h &free"
+   p_free :: FunPtr (Ptr a -> IO ())
+\end{verbatim}}
+\end{quote}
+or a pointer to a Haskell function created using a \emph{wrapper} stub
+ declared to produce a \haddockid{FunPtr} of the correct type.  For example:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ type Compare = Int -> Int -> Bool
+ foreign import ccall "wrapper"
+   mkCompare :: Compare -> IO (FunPtr Compare)
+\end{verbatim}}
+\end{quote}
+Calls to wrapper stubs like \haddocktt{mkCompare} allocate storage, which
+ should be released with \haddocktt{Foreign.Ptr.freeHaskellFunPtr} when no
+ longer required.
+\par
+To convert \haddockid{FunPtr} values to corresponding Haskell functions, one
+ can define a \emph{dynamic} stub for the specific foreign type, e.g.
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ type IntFunction = CInt -> IO ()
+ foreign import ccall "dynamic" 
+   mkFun :: FunPtr IntFunction -> IntFunction
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ (FunPtr\ a)\\instance\ Ord\ (FunPtr\ a)\\instance\ Show\ (FunPtr\ a)\\instance\ Storable\ (FunPtr\ a)
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+nullFunPtr\ ::\ FunPtr\ a
+\end{tabular}]\haddockbegindoc
+The constant \haddockid{nullFunPtr} contains a
+ distinguished value of \haddockid{FunPtr} that is not
+ associated with a valid memory location.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+castFunPtr\ ::\ FunPtr\ a\ ->\ FunPtr\ b
+\end{tabular}]\haddockbegindoc
+Casts a \haddockid{FunPtr} to a \haddockid{FunPtr} of a different type.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+castFunPtrToPtr\ ::\ FunPtr\ a\ ->\ Ptr\ b
+\end{tabular}]\haddockbegindoc
+Casts a \haddockid{FunPtr} to a \haddockid{Ptr}.
+\par
+\emph{Note:} this is valid only on architectures where data and function
+ pointers range over the same set of addresses, and should only be used
+ for bindings to external libraries whose interface already relies on
+ this assumption.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+castPtrToFunPtr\ ::\ Ptr\ a\ ->\ FunPtr\ b
+\end{tabular}]\haddockbegindoc
+Casts a \haddockid{Ptr} to a \haddockid{FunPtr}.
+\par
+\emph{Note:} this is valid only on architectures where data and function
+ pointers range over the same set of addresses, and should only be used
+ for bindings to external libraries whose interface already relies on
+ this assumption.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+freeHaskellFunPtr\ ::\ FunPtr\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Release the storage associated with the given \haddockid{FunPtr}, which
+ must have been obtained from a wrapper stub.  This should be called
+ whenever the return value from a foreign import wrapper function is
+ no longer required; otherwise, the storage it uses will leak.
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign-StablePtr.tex b/report/libs/Foreign-StablePtr.tex
new file mode 100644 (file)
index 0000000..33cccac
--- /dev/null
@@ -0,0 +1,115 @@
+\chapter{\texttt{Foreign.StablePtr}}
+\label{module:Foreign.StablePtr}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.StablePtr (
+    StablePtr,  newStablePtr,  deRefStablePtr,  freeStablePtr, 
+    castStablePtrToPtr,  castPtrToStablePtr
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{Stable references to Haskell values
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ StablePtr\ a
+\end{tabular}]\haddockbegindoc
+A \emph{stable pointer} is a reference to a Haskell expression that is
+guaranteed not to be affected by garbage collection, i.e., it will neither be
+deallocated nor will the value of the stable pointer itself change during
+garbage collection (ordinary references may be relocated during garbage
+collection).  Consequently, stable pointers can be passed to foreign code,
+which can treat it as an opaque reference to a Haskell value.
+\par
+A value of type \haddocktt{StablePtr\ a} is a stable pointer to a Haskell
+expression of type \haddocktt{a}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ (StablePtr\ a)\\instance\ Storable\ (StablePtr\ a)
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+newStablePtr\ ::\ a\ ->\ IO\ (StablePtr\ a)
+\end{tabular}]\haddockbegindoc
+Create a stable pointer referring to the given Haskell value.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+deRefStablePtr\ ::\ StablePtr\ a\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Obtain the Haskell value referenced by a stable pointer, i.e., the
+ same value that was passed to the corresponding call to
+ \haddocktt{makeStablePtr}.  If the argument to \haddockid{deRefStablePtr} has
+ already been freed using \haddockid{freeStablePtr}, the behaviour of
+ \haddockid{deRefStablePtr} is undefined.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+freeStablePtr\ ::\ StablePtr\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Dissolve the association between the stable pointer and the Haskell
+ value. Afterwards, if the stable pointer is passed to
+ \haddockid{deRefStablePtr} or \haddockid{freeStablePtr}, the behaviour is
+ undefined.  However, the stable pointer may still be passed to
+ \haddockid{castStablePtrToPtr}, but the \haddocktt{\haddocktt{Foreign.Ptr.Ptr}\ ()} value returned
+ by \haddockid{castStablePtrToPtr}, in this case, is undefined (in particular,
+ it may be \haddocktt{Foreign.Ptr.nullPtr}).  Nevertheless, the call
+ to \haddockid{castStablePtrToPtr} is guaranteed not to diverge.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+castStablePtrToPtr\ ::\ StablePtr\ a\ ->\ Ptr\ ()
+\end{tabular}]\haddockbegindoc
+Coerce a stable pointer to an address. No guarantees are made about
+ the resulting value, except that the original stable pointer can be
+ recovered by \haddockid{castPtrToStablePtr}.  In particular, the address may not
+ refer to an accessible memory location and any attempt to pass it to
+ the member functions of the class \haddocktt{Foreign.Storable.Storable} leads to
+ undefined behaviour.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+castPtrToStablePtr\ ::\ Ptr\ ()\ ->\ StablePtr\ a
+\end{tabular}]\haddockbegindoc
+The inverse of \haddockid{castStablePtrToPtr}, i.e., we have the identity
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ sp == castPtrToStablePtr (castStablePtrToPtr sp)
+\end{verbatim}}
+\end{quote}
+for any stable pointer \haddocktt{sp} on which \haddockid{freeStablePtr} has
+ not been executed yet.  Moreover, \haddockid{castPtrToStablePtr} may
+ only be applied to pointers that have been produced by
+ \haddockid{castStablePtrToPtr}.
+\par
+
+\end{haddockdesc}
+\subsection{The C-side interface
+}
+The following definition is available to C programs inter-operating with
+ Haskell code when including the header \haddocktt{HsFFI.h}.
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ typedef void *HsStablePtr;  
+\end{verbatim}}
+\end{quote}
+Note that no assumptions may be made about the values representing stable
+ pointers.  In fact, they need not even be valid memory addresses.  The only
+ guarantee provided is that if they are passed back to Haskell land, the
+ function \haddockid{deRefStablePtr} will be able to reconstruct the
+ Haskell value referred to by the stable pointer.
+\par
diff --git a/report/libs/Foreign-Storable.tex b/report/libs/Foreign-Storable.tex
new file mode 100644 (file)
index 0000000..e4954d7
--- /dev/null
@@ -0,0 +1,165 @@
+\chapter{\texttt{Foreign.Storable}}
+\label{module:Foreign.Storable}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign.Storable (
+    Storable(sizeOf,
+             alignment,
+             peekElemOff,
+             pokeElemOff,
+             peekByteOff,
+             pokeByteOff,
+             peek,
+             poke)
+  ) where\end{verbatim}}
+\haddockendheader
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+class\ Storable\ a\ where
+\end{tabular}]\haddockbegindoc
+The member functions of this class facilitate writing values of
+primitive types to raw memory (which may have been allocated with the
+above mentioned routines) and reading values from blocks of raw
+memory.  The class, furthermore, includes support for computing the
+storage requirements and alignment restrictions of storable types.
+\par
+Memory addresses are represented as values of type \haddocktt{Ptr\ a}, for some
+\haddocktt{a} which is an instance of class \haddockid{Storable}.  The type argument to
+\haddockid{Ptr} helps provide some valuable type safety in FFI code (you can't
+mix pointers of different types without an explicit cast), while
+helping the Haskell type system figure out which marshalling method is
+needed for a given pointer.
+\par
+All marshalling between Haskell and a foreign language ultimately
+boils down to translating Haskell data structures into the binary
+representation of a corresponding data structure of the foreign
+language and vice versa.  To code this marshalling in Haskell, it is
+necessary to manipulate primitive data types stored in unstructured
+memory blocks.  The class \haddockid{Storable} facilitates this manipulation on
+all types for which it is instantiated, which are the standard basic
+types of Haskell, the fixed size \haddocktt{Int} types (\haddockid{Int8}, \haddockid{Int16},
+\haddockid{Int32}, \haddockid{Int64}), the fixed size \haddocktt{Word} types (\haddockid{Word8}, \haddockid{Word16},
+\haddockid{Word32}, \haddockid{Word64}), \haddockid{StablePtr}, all types from \haddocktt{Foreign.C.Types},
+as well as \haddockid{Ptr}.
+\par
+Minimal complete definition: \haddockid{sizeOf}, \haddockid{alignment}, one of \haddockid{peek},
+\haddockid{peekElemOff} and \haddockid{peekByteOff}, and one of \haddockid{poke}, \haddockid{pokeElemOff} and
+\haddockid{pokeByteOff}.
+\par
+
+\haddockpremethods{}\textbf{Methods}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+sizeOf\ ::\ a\ ->\ Int
+\end{tabular}]\haddockbegindoc
+Computes the storage requirements (in bytes) of the argument.
+ The value of the argument is not used.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+alignment\ ::\ a\ ->\ Int
+\end{tabular}]\haddockbegindoc
+Computes the alignment constraint of the argument.  An
+ alignment constraint \haddocktt{x} is fulfilled by any address divisible
+ by \haddocktt{x}.  The value of the argument is not used.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekElemOff\ ::\ Ptr\ a\ ->\ Int\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Read a value from a memory area regarded as an array
+         of values of the same kind.  The first argument specifies
+         the start address of the array and the second the index into
+         the array (the first element of the array has index
+         \haddocktt{0}).  The following equality holds,
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ peekElemOff addr idx = IOExts.fixIO $ \result ->
+   peek (addr `plusPtr` (idx * sizeOf result))
+\end{verbatim}}
+\end{quote}
+Note that this is only a specification, not
+         necessarily the concrete implementation of the
+         function.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+pokeElemOff\ ::\ Ptr\ a\ ->\ Int\ ->\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Write a value to a memory area regarded as an array of
+         values of the same kind.  The following equality holds:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ pokeElemOff addr idx x = 
+   poke (addr `plusPtr` (idx * sizeOf x)) x
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peekByteOff\ ::\ Ptr\ b\ ->\ Int\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Read a value from a memory location given by a base
+         address and offset.  The following equality holds:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ peekByteOff addr off = peek (addr `plusPtr` off)
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+pokeByteOff\ ::\ Ptr\ b\ ->\ Int\ ->\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Write a value to a memory location given by a base
+         address and offset.  The following equality holds:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ pokeByteOff addr off x = poke (addr `plusPtr` off) x
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+peek\ ::\ Ptr\ a\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Read a value from the given memory location.
+\par
+Note that the peek and poke functions might require properly
+  aligned addresses to function correctly.  This is architecture
+  dependent; thus, portable code should ensure that when peeking or
+  poking values of some type \haddocktt{a}, the alignment
+  constraint for \haddocktt{a}, as given by the function
+  \haddockid{alignment} is fulfilled.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+poke\ ::\ Ptr\ a\ ->\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Write the given value to the given memory location.  Alignment
+ restrictions might apply; see \haddockid{peek}.
+\par
+
+\end{haddockdesc}
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Storable\ Bool\\instance\ Storable\ Char\\instance\ Storable\ Double\\instance\ Storable\ Float\\instance\ Storable\ Int\\instance\ Storable\ Int8\\instance\ Storable\ Int16\\instance\ Storable\ Int32\\instance\ Storable\ Int64\\instance\ Storable\ Word\\instance\ Storable\ Word8\\instance\ Storable\ Word16\\instance\ Storable\ Word32\\instance\ Storable\ Word64\\instance\ Storable\ WordPtr\\instance\ Storable\ IntPtr\\instance\ Storable\ CChar\\instance\ Storable\ CSChar\\instance\ Storable\ CUChar\\instance\ Storable\ CShort\\instance\ Storable\ CUShort\\instance\ Storable\ CInt\\instance\ Storable\ CUInt\\instance\ Storable\ CLong\\instance\ Storable\ CULong\\instance\ Storable\ CLLong\\instance\ Storable\ CULLong\\instance\ Storable\ CFloat\\instance\ Storable\ CDouble\\instance\ Storable\ CPtrdiff\\instance\ Storable\ CSize\\instance\ Storable\ CWchar\\instance\ Storable\ CSigAtomic\\instance\ Storable\ CClock\\instance\ Storable\ CTime\\instance\ Storable\ CIntPtr\\instance\ Storable\ CUIntPtr\\instance\ Storable\ CIntMax\\instance\ Storable\ CUIntMax\\instance\ Storable\ (StablePtr\ a)\\instance\ Storable\ (Ptr\ a)\\instance\ Storable\ (FunPtr\ a)
+\end{tabular}]
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/Foreign.tex b/report/libs/Foreign.tex
new file mode 100644 (file)
index 0000000..f0fd037
--- /dev/null
@@ -0,0 +1,21 @@
+\chapter{\texttt{Foreign}}
+\label{module:Foreign}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module Foreign (
+    module Data.Bits,  module Data.Int,  module Data.Word,  module Foreign.Ptr, 
+    module Foreign.ForeignPtr,  module Foreign.StablePtr, 
+    module Foreign.Storable,  module Foreign.Marshal
+  ) where\end{verbatim}}
+\haddockendheader
+
+The module \haddocktt{Foreign} combines the interfaces of all
+ modules providing language-independent marshalling support,
+ namely
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+module\ Data.Bits\\module\ Data.Int\\module\ Data.Word\\module\ Foreign.Ptr\\module\ Foreign.ForeignPtr\\module\ Foreign.StablePtr\\module\ Foreign.Storable\\module\ Foreign.Marshal
+\end{tabular}]
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/System-Environment.tex b/report/libs/System-Environment.tex
new file mode 100644 (file)
index 0000000..859acab
--- /dev/null
@@ -0,0 +1,51 @@
+\chapter{\texttt{System.Environment}}
+\label{module:System.Environment}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module System.Environment (
+    getArgs,  getProgName,  getEnv
+  ) where\end{verbatim}}
+\haddockendheader
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+getArgs\ ::\ IO\ {\char 91}String{\char 93}
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{getArgs} returns a list of the program's command
+ line arguments (not including the program name).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+getProgName\ ::\ IO\ String
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{getProgName} returns the name of the program as it was
+invoked.
+\par
+However, this is hard-to-impossible to implement on some non-Unix
+OSes, so instead, for maximum portability, we just return the leafname
+of the program as invoked. Even then there are some differences
+between platforms: on Windows, for example, a program invoked as foo
+is probably really \haddocktt{FOO.EXE}, and that is what \haddockid{getProgName} will return.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+getEnv\ ::\ String\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{getEnv} \haddocktt{var} returns the value
+ of the environment variable \haddocktt{var}.  
+\par
+This computation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{System.IO.Error.isDoesNotExistError} if the environment variable
+    does not exist.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/System-Exit.tex b/report/libs/System-Exit.tex
new file mode 100644 (file)
index 0000000..0fa9bd5
--- /dev/null
@@ -0,0 +1,67 @@
+\chapter{\texttt{System.Exit}}
+\label{module:System.Exit}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module System.Exit (
+    ExitCode(ExitSuccess, ExitFailure),  exitWith,  exitFailure,  exitSuccess
+  ) where\end{verbatim}}
+\haddockendheader
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ ExitCode
+\end{tabular}]\haddockbegindoc
+\haddockbeginconstrs
+\haddockdecltt{=} & \haddockdecltt{ExitSuccess} & indicates successful termination;
+ \\
+\haddockdecltt{|} & \haddockdecltt{ExitFailure Int} & indicates program failure with an exit code.
+ The exact interpretation of the code is
+ operating-system dependent.  In particular, some values
+ may be prohibited (e.g. 0 on a POSIX-compliant system).
+ \\
+\haddockendconstrs\par
+Defines the exit codes that a program can return.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ ExitCode\\instance\ Ord\ ExitCode\\instance\ Read\ ExitCode\\instance\ Show\ ExitCode\\instance\ Typeable\ ExitCode\\instance\ Exception\ ExitCode
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+exitWith\ ::\ ExitCode\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+Computation \haddocktt{exitWith\ code} terminates the program, returning \haddocktt{code}
+to the program's caller.  
+The caller may interpret the return code as it wishes, but the program
+should return \haddockid{ExitSuccess} to mean normal completion, and
+\haddocktt{ExitFailure\ n} to mean that the program encountered a problem from
+which it could not recover.  The value \haddockid{exitFailure} is equal to
+\haddocktt{exitWith\ (ExitFailure\ exitfail)}, where \haddocktt{exitfail} is
+implementation-dependent.  \haddockid{exitWith} bypasses the error handling in
+the I/O monad and cannot be intercepted by \haddockid{catch} from the \haddocktt{Prelude}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+exitFailure\ ::\ IO\ a
+\end{tabular}]\haddockbegindoc
+The computation \haddockid{exitFailure} is equivalent to
+ \haddockid{exitWith} \haddocktt{(}\haddockid{ExitFailure} \emph{exitfail}\haddocktt{)},
+ where \emph{exitfail} is implementation-dependent.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+exitSuccess\ ::\ IO\ a
+\end{tabular}]\haddockbegindoc
+The computation \haddockid{exitSuccess} is equivalent to
+ \haddockid{exitWith} \haddockid{ExitSuccess}, It terminates the program
+ sucessfully.
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/System-IO-Error.tex b/report/libs/System-IO-Error.tex
new file mode 100644 (file)
index 0000000..4a1332a
--- /dev/null
@@ -0,0 +1,236 @@
+\chapter{\texttt{System.IO.Error}}
+\label{module:System.IO.Error}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module System.IO.Error (
+    IOError,  userError,  mkIOError,  annotateIOError,  isAlreadyExistsError, 
+    isDoesNotExistError,  isAlreadyInUseError,  isFullError,  isEOFError, 
+    isIllegalOperation,  isPermissionError,  isUserError,  ioeGetErrorString, 
+    ioeGetHandle,  ioeGetFileName,  IOErrorType,  alreadyExistsErrorType, 
+    doesNotExistErrorType,  alreadyInUseErrorType,  fullErrorType, 
+    eofErrorType,  illegalOperationErrorType,  permissionErrorType, 
+    userErrorType
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{I/O errors
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ IOError\ =\ IOError
+\end{tabular}]\haddockbegindoc
+Errors of type \haddockid{IOError} are used by the \haddockid{IO} monad.  This is an
+ abstract type; the module \haddocktt{System.IO.Error} provides functions to
+ interrogate and construct values of type \haddockid{IOError}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+userError\ ::\ String\ ->\ IOError
+\end{tabular}]\haddockbegindoc
+Construct an \haddockid{IOError} value with a string describing the error.
+ The \haddockid{fail} method of the \haddockid{IO} instance of the \haddockid{Monad} class raises a
+ \haddockid{userError}, thus:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ instance Monad IO where 
+   ...
+   fail s = ioError (userError s)
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+mkIOError\ ::\ IOErrorType\\\ \ \ \ \ \ \ \ \ \ \ \ \ ->\ String\ ->\ Maybe\ Handle\ ->\ Maybe\ FilePath\ ->\ IOError
+\end{tabular}]\haddockbegindoc
+Construct an \haddockid{IOError} of the given type where the second argument
+ describes the error location and the third and fourth argument
+ contain the file handle and file path of the file involved in the
+ error if applicable.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+annotateIOError\ ::\ IOError\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ String\ ->\ Maybe\ Handle\ ->\ Maybe\ FilePath\ ->\ IOError
+\end{tabular}]\haddockbegindoc
+Adds a location description and maybe a file path and file handle
+ to an \haddockid{IOError}.  If any of the file handle or file path is not given
+ the corresponding value in the \haddockid{IOError} remains unaltered.
+\par
+
+\end{haddockdesc}
+\subsection{Classifying I/O errors
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isAlreadyExistsError\ ::\ IOError\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+An error indicating that an \haddockid{IO} operation failed because
+ one of its arguments already exists.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isDoesNotExistError\ ::\ IOError\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+An error indicating that an \haddockid{IO} operation failed because
+ one of its arguments does not exist.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isAlreadyInUseError\ ::\ IOError\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+An error indicating that an \haddockid{IO} operation failed because
+ one of its arguments is a single-use resource, which is already
+ being used (for example, opening the same file twice for writing
+ might give this error).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isFullError\ ::\ IOError\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+An error indicating that an \haddockid{IO} operation failed because
+ the device is full.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isEOFError\ ::\ IOError\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+An error indicating that an \haddockid{IO} operation failed because
+ the end of file has been reached.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isIllegalOperation\ ::\ IOError\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+An error indicating that an \haddockid{IO} operation failed because
+ the operation was not possible.
+ Any computation which returns an \haddockid{IO} result may fail with
+ \haddockid{isIllegalOperation}.  In some cases, an implementation will not be
+ able to distinguish between the possible error causes.  In this case
+ it should fail with \haddockid{isIllegalOperation}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isPermissionError\ ::\ IOError\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+An error indicating that an \haddockid{IO} operation failed because
+ the user does not have sufficient operating system privilege
+ to perform that operation.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isUserError\ ::\ IOError\ ->\ Bool
+\end{tabular}]\haddockbegindoc
+A programmer-defined error value constructed using \haddockid{userError}.
+\par
+
+\end{haddockdesc}
+\subsection{Attributes of I/O errors
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+ioeGetErrorString\ ::\ IOError\ ->\ String\\ioeGetHandle\ ::\ IOError\ ->\ Maybe\ Handle\\ioeGetFileName\ ::\ IOError\ ->\ Maybe\ FilePath
+\end{tabular}]
+\end{haddockdesc}
+\section{Types of I/O error
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ IOErrorType
+\end{tabular}]\haddockbegindoc
+An abstract type that contains a value for each variant of \haddockid{IOError}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ IOErrorType\\instance\ Show\ IOErrorType
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+alreadyExistsErrorType\ ::\ IOErrorType
+\end{tabular}]\haddockbegindoc
+I/O error where the operation failed because one of its arguments
+ already exists.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+doesNotExistErrorType\ ::\ IOErrorType
+\end{tabular}]\haddockbegindoc
+I/O error where the operation failed because one of its arguments
+ does not exist.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+alreadyInUseErrorType\ ::\ IOErrorType
+\end{tabular}]\haddockbegindoc
+I/O error where the operation failed because one of its arguments
+ is a single-use resource, which is already being used.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+fullErrorType\ ::\ IOErrorType
+\end{tabular}]\haddockbegindoc
+I/O error where the operation failed because the device is full.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+eofErrorType\ ::\ IOErrorType
+\end{tabular}]\haddockbegindoc
+I/O error where the operation failed because the end of file has
+ been reached.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+illegalOperationErrorType\ ::\ IOErrorType
+\end{tabular}]\haddockbegindoc
+I/O error where the operation is not possible.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+permissionErrorType\ ::\ IOErrorType
+\end{tabular}]\haddockbegindoc
+I/O error where the operation failed because the user does not
+ have sufficient operating system privilege to perform that operation.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+userErrorType\ ::\ IOErrorType
+\end{tabular}]\haddockbegindoc
+I/O error that is programmer-defined.
+\par
+
+\end{haddockdesc}
\ No newline at end of file
diff --git a/report/libs/System-IO.tex b/report/libs/System-IO.tex
new file mode 100644 (file)
index 0000000..46a1a79
--- /dev/null
@@ -0,0 +1,977 @@
+\chapter{\texttt{System.IO}}
+\label{module:System.IO}
+\haddockbeginheader
+{\haddockverb\begin{verbatim}
+module System.IO (
+    IO,  fixIO,  FilePath,  Handle,  stdin,  stdout,  stderr,  withFile, 
+    openFile,  IOMode(ReadMode, WriteMode, AppendMode, ReadWriteMode),  hClose, 
+    readFile,  writeFile,  appendFile,  hFileSize,  hSetFileSize,  hIsEOF, 
+    isEOF,  BufferMode(NoBuffering, LineBuffering, BlockBuffering), 
+    hSetBuffering,  hGetBuffering,  hFlush,  hGetPosn,  hSetPosn,  HandlePosn, 
+    hSeek,  SeekMode(AbsoluteSeek, RelativeSeek, SeekFromEnd),  hTell, 
+    hIsOpen,  hIsClosed,  hIsReadable,  hIsWritable,  hIsSeekable, 
+    hIsTerminalDevice,  hSetEcho,  hGetEcho,  hShow,  hWaitForInput,  hReady, 
+    hGetChar,  hGetLine,  hLookAhead,  hGetContents,  hPutChar,  hPutStr, 
+    hPutStrLn,  hPrint,  interact,  putChar,  putStr,  putStrLn,  print, 
+    getChar,  getLine,  getContents,  readIO,  readLn
+  ) where\end{verbatim}}
+\haddockendheader
+
+\section{The IO monad
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ IO\ a
+\end{tabular}]\haddockbegindoc
+A value of type \haddocktt{IO\ a} is a computation which, when performed,
+does some I/O before returning a value of type \haddocktt{a}.
+\par
+There is really only one way to "perform" an I/O action: bind it to
+\haddocktt{Main.main} in your program.  When your program is run, the I/O will
+be performed.  It isn't possible to perform I/O from an arbitrary
+function, unless that function is itself in the \haddockid{IO} monad and called
+at some point, directly or indirectly, from \haddocktt{Main.main}.
+\par
+\haddockid{IO} is a monad, so \haddockid{IO} actions can be combined using either the do-notation
+or the \haddocktt{>>} and \haddocktt{>>=} operations from the \haddocktt{Monad} class.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Monad\ IO\\instance\ Functor\ IO
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+fixIO\ ::\ (a\ ->\ IO\ a)\ ->\ IO\ a
+\end{tabular}]
+\end{haddockdesc}
+\section{Files and handles
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+type\ FilePath\ =\ String
+\end{tabular}]\haddockbegindoc
+File and directory names are values of type \haddockid{String}, whose precise
+ meaning is operating system dependent. Files can be opened, yielding a
+ handle which can then be used to operate on the contents of that file.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ Handle
+\end{tabular}]\haddockbegindoc
+Haskell defines operations to read and write characters from and to files,
+ represented by values of type \haddocktt{Handle}.  Each value of this type is a
+ \emph{handle}: a record used by the Haskell run-time system to \emph{manage} I/O
+ with file system objects.  A handle has at least the following properties:
+\par
+\begin{itemize}
+\item
+ whether it manages input or output or both;
+\par
+
+\item
+ whether it is \emph{open}, \emph{closed} or \emph{semi-closed};
+\par
+
+\item
+ whether the object is seekable;
+\par
+
+\item
+ whether buffering is disabled, or enabled on a line or block basis;
+\par
+
+\item
+ a buffer (whose length may be zero).
+\par
+
+\end{itemize}
+Most handles will also have a current I/O position indicating where the next
+ input or output operation will occur.  A handle is \emph{readable} if it
+ manages only input or both input and output; likewise, it is \emph{writable} if
+ it manages only output or both input and output.  A handle is \emph{open} when
+ first allocated.
+ Once it is closed it can no longer be used for either input or output,
+ though an implementation cannot re-use its storage while references
+ remain to it.  Handles are in the \haddockid{Show} and \haddockid{Eq} classes.  The string
+ produced by showing a handle is system dependent; it should include
+ enough information to identify the handle for debugging.  A handle is
+ equal according to \haddockid{==} only to itself; no attempt
+ is made to compare the internal state of different handles for equality.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ Handle\\instance\ Show\ Handle\\instance\ Typeable\ Handle
+\end{tabular}]
+\end{haddockdesc}
+\subsection{Standard handles
+}
+Three handles are allocated during program initialisation,
+ and are initially open.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+stdin\ ::\ Handle
+\end{tabular}]\haddockbegindoc
+A handle managing input from the Haskell program's standard input channel.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+stdout\ ::\ Handle
+\end{tabular}]\haddockbegindoc
+A handle managing output to the Haskell program's standard output channel.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+stderr\ ::\ Handle
+\end{tabular}]\haddockbegindoc
+A handle managing output to the Haskell program's standard error channel.
+\par
+
+\end{haddockdesc}
+\section{Opening and closing files
+}
+\subsection{Opening files
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+withFile\ ::\ FilePath\ ->\ IOMode\ ->\ (Handle\ ->\ IO\ r)\ ->\ IO\ r
+\end{tabular}]\haddockbegindoc
+\haddocktt{withFile\ name\ mode\ act} opens a file using \haddockid{openFile} and passes
+ the resulting handle to the computation \haddocktt{act}.  The handle will be
+ closed on exit from \haddockid{withFile}, whether by normal termination or by
+ raising an exception.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+openFile\ ::\ FilePath\ ->\ IOMode\ ->\ IO\ Handle
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{openFile} \haddocktt{file\ mode} allocates and returns a new, open
+ handle to manage the file \haddocktt{file}.  It manages input if \haddocktt{mode}
+ is \haddockid{ReadMode}, output if \haddocktt{mode} is \haddockid{WriteMode} or \haddockid{AppendMode},
+ and both input and output if mode is \haddockid{ReadWriteMode}.
+\par
+If the file does not exist and it is opened for output, it should be
+ created as a new file.  If \haddocktt{mode} is \haddockid{WriteMode} and the file
+ already exists, then it should be truncated to zero length.
+ Some operating systems delete empty files, so there is no guarantee
+ that the file will exist following an \haddockid{openFile} with \haddocktt{mode}
+ \haddockid{WriteMode} unless it is subsequently written to successfully.
+ The handle is positioned at the end of the file if \haddocktt{mode} is
+ \haddockid{AppendMode}, and otherwise at the beginning (in which case its
+ internal position is 0).
+ The initial buffer mode is implementation-dependent.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{isAlreadyInUseError} if the file is already open and cannot be reopened;
+\par
+
+\item
+ \haddocktt{isDoesNotExistError} if the file does not exist; or
+\par
+
+\item
+ \haddocktt{isPermissionError} if the user does not have permission to open the file.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ IOMode
+\end{tabular}]\haddockbegindoc
+\haddockbeginconstrs
+\haddockdecltt{=} & \haddockdecltt{ReadMode} & \\
+\haddockdecltt{|} & \haddockdecltt{WriteMode} & \\
+\haddockdecltt{|} & \haddockdecltt{AppendMode} & \\
+\haddockdecltt{|} & \haddockdecltt{ReadWriteMode} & \\
+\haddockendconstrs\par
+See \haddocktt{System.IO.openFile}
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Enum\ IOMode\\instance\ Eq\ IOMode\\instance\ Ord\ IOMode\\instance\ Read\ IOMode\\instance\ Show\ IOMode\\instance\ Ix\ IOMode
+\end{tabular}]
+\end{haddockdesc}
+\subsection{Closing files
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hClose\ ::\ Handle\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hClose} \haddocktt{hdl} makes handle \haddocktt{hdl} closed.  Before the
+ computation finishes, if \haddocktt{hdl} is writable its buffer is flushed as
+ for \haddockid{hFlush}.
+ Performing \haddockid{hClose} on a handle that has already been closed has no effect; 
+ doing so is not an error.  All other operations on a closed handle will fail.
+ If \haddockid{hClose} fails for any reason, any further operations (apart from
+ \haddockid{hClose}) on the handle will still fail as if \haddocktt{hdl} had been successfully
+ closed.
+\par
+
+\end{haddockdesc}
+\subsection{Special cases
+}
+These functions are also exported by the \haddocktt{Prelude}.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+readFile\ ::\ FilePath\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+The \haddockid{readFile} function reads a file and
+ returns the contents of the file as a string.
+ The file is read lazily, on demand, as with \haddockid{getContents}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+writeFile\ ::\ FilePath\ ->\ String\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+The computation \haddockid{writeFile} \haddocktt{file\ str} function writes the string \haddocktt{str},
+ to the file \haddocktt{file}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+appendFile\ ::\ FilePath\ ->\ String\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+The computation \haddockid{appendFile} \haddocktt{file\ str} function appends the string \haddocktt{str},
+ to the file \haddocktt{file}.
+\par
+Note that \haddockid{writeFile} and \haddockid{appendFile} write a literal string
+ to a file.  To write a value of any printable type, as with \haddockid{print},
+ use the \haddockid{show} function to convert the value to a string first.
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\subsection{File locking
+}
+Implementations should enforce as far as possible, at least locally to the
+ Haskell process, multiple-reader single-writer locking on files.
+ That is, \emph{there may either be many handles on the same file which manage input, or just one handle on the file which manages output}.  If any
+ open or semi-closed handle is managing a file for output, no new
+ handle can be allocated for that file.  If any open or semi-closed
+ handle is managing a file for input, new handles can only be allocated
+ if they do not manage output.  Whether two files are the same is
+ implementation-dependent, but they should normally be the same if they
+ have the same absolute path name and neither has been renamed, for
+ example.
+\par
+\emph{Warning}: the \haddockid{readFile} operation holds a semi-closed handle on
+ the file until the entire contents of the file have been consumed.
+ It follows that an attempt to write to a file (using \haddockid{writeFile}, for
+ example) that was earlier opened by \haddockid{readFile} will usually result in
+ failure with \haddocktt{System.IO.Error.isAlreadyInUseError}.
+\par
+
+\section{Operations on handles
+}
+\subsection{Determining and changing the size of a file
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hFileSize\ ::\ Handle\ ->\ IO\ Integer
+\end{tabular}]\haddockbegindoc
+For a handle \haddocktt{hdl} which attached to a physical file,
+ \haddockid{hFileSize} \haddocktt{hdl} returns the size of that file in 8-bit bytes.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hSetFileSize\ ::\ Handle\ ->\ Integer\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+\haddockid{hSetFileSize} \haddocktt{hdl} \haddocktt{size} truncates the physical file with handle \haddocktt{hdl} to \haddocktt{size} bytes.
+\par
+
+\end{haddockdesc}
+\subsection{Detecting the end of input
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hIsEOF\ ::\ Handle\ ->\ IO\ Bool
+\end{tabular}]\haddockbegindoc
+For a readable handle \haddocktt{hdl}, \haddockid{hIsEOF} \haddocktt{hdl} returns
+ \haddockid{True} if no further input can be taken from \haddocktt{hdl} or for a
+ physical file, if the current I/O position is equal to the length of
+ the file.  Otherwise, it returns \haddockid{False}.
+\par
+NOTE: \haddockid{hIsEOF} may block, because it has to attempt to read from
+ the stream to determine whether there is any more data to be read.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+isEOF\ ::\ IO\ Bool
+\end{tabular}]\haddockbegindoc
+The computation \haddockid{isEOF} is identical to \haddockid{hIsEOF},
+ except that it works only on \haddockid{stdin}.
+\par
+
+\end{haddockdesc}
+\subsection{Buffering operations
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ BufferMode
+\end{tabular}]\haddockbegindoc
+\haddockbeginconstrs
+\haddockdecltt{=} & \haddockdecltt{NoBuffering} & buffering is disabled if possible.
+ \\
+\haddockdecltt{|} & \haddockdecltt{LineBuffering} & line-buffering should be enabled if possible.
+ \\
+\haddockdecltt{|} & \haddockdecltt{BlockBuffering (Maybe Int)} & block-buffering should be enabled if possible.
+ The size of the buffer is \haddocktt{n} items if the argument
+ is \haddockid{Just} \haddocktt{n} and is otherwise implementation-dependent.
+ \\
+\haddockendconstrs\par
+Three kinds of buffering are supported: line-buffering, 
+ block-buffering or no-buffering.  These modes have the following
+ effects. For output, items are written out, or \emph{flushed},
+ from the internal buffer according to the buffer mode:
+\par
+\begin{itemize}
+\item
+ \emph{line-buffering}: the entire output buffer is flushed
+    whenever a newline is output, the buffer overflows, 
+    a \haddocktt{System.IO.hFlush} is issued, or the handle is closed.
+\par
+
+\item
+ \emph{block-buffering}: the entire buffer is written out whenever it
+    overflows, a \haddocktt{System.IO.hFlush} is issued, or the handle is closed.
+\par
+
+\item
+ \emph{no-buffering}: output is written immediately, and never stored
+    in the buffer.
+\par
+
+\end{itemize}
+An implementation is free to flush the buffer more frequently,
+ but not less frequently, than specified above.
+ The output buffer is emptied as soon as it has been written out.
+\par
+Similarly, input occurs according to the buffer mode for the handle:
+\par
+\begin{itemize}
+\item
+ \emph{line-buffering}: when the buffer for the handle is not empty,
+    the next item is obtained from the buffer; otherwise, when the
+    buffer is empty, characters up to and including the next newline
+    character are read into the buffer.  No characters are available
+    until the newline character is available or the buffer is full.
+\par
+
+\item
+ \emph{block-buffering}: when the buffer for the handle becomes empty,
+    the next block of data is read into the buffer.
+\par
+
+\item
+ \emph{no-buffering}: the next input item is read and returned.
+    The \haddocktt{System.IO.hLookAhead} operation implies that even a no-buffered
+    handle may require a one-character buffer.
+\par
+
+\end{itemize}
+The default buffering mode when a handle is opened is
+ implementation-dependent and may depend on the file system object
+ which is attached to that handle.
+ For most implementations, physical files will normally be block-buffered 
+ and terminals will normally be line-buffered.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ BufferMode\\instance\ Ord\ BufferMode\\instance\ Read\ BufferMode\\instance\ Show\ BufferMode
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hSetBuffering\ ::\ Handle\ ->\ BufferMode\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hSetBuffering} \haddocktt{hdl\ mode} sets the mode of buffering for
+ handle \haddocktt{hdl} on subsequent reads and writes.
+\par
+If the buffer mode is changed from \haddockid{BlockBuffering} or
+ \haddockid{LineBuffering} to \haddockid{NoBuffering}, then
+\par
+\begin{itemize}
+\item
+ if \haddocktt{hdl} is writable, the buffer is flushed as for \haddockid{hFlush};
+\par
+
+\item
+ if \haddocktt{hdl} is not writable, the contents of the buffer is discarded.
+\par
+
+\end{itemize}
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{isPermissionError} if the handle has already been used for reading
+    or writing and the implementation does not allow the buffering mode
+    to be changed.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hGetBuffering\ ::\ Handle\ ->\ IO\ BufferMode
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hGetBuffering} \haddocktt{hdl} returns the current buffering mode
+ for \haddocktt{hdl}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hFlush\ ::\ Handle\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+The action \haddockid{hFlush} \haddocktt{hdl} causes any items buffered for output
+ in handle \haddocktt{hdl} to be sent immediately to the operating system.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{isFullError} if the device is full;
+\par
+
+\item
+ \haddocktt{isPermissionError} if a system resource limit would be exceeded.
+    It is unspecified whether the characters in the buffer are discarded
+    or retained under these circumstances.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\subsection{Repositioning handles
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hGetPosn\ ::\ Handle\ ->\ IO\ HandlePosn
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hGetPosn} \haddocktt{hdl} returns the current I/O position of
+ \haddocktt{hdl} as a value of the abstract type \haddockid{HandlePosn}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hSetPosn\ ::\ HandlePosn\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+If a call to \haddockid{hGetPosn} \haddocktt{hdl} returns a position \haddocktt{p},
+ then computation \haddockid{hSetPosn} \haddocktt{p} sets the position of \haddocktt{hdl}
+ to the position it held at the time of the call to \haddockid{hGetPosn}.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{isPermissionError} if a system resource limit would be exceeded.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ HandlePosn
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Eq\ HandlePosn\\instance\ Show\ HandlePosn
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hSeek\ ::\ Handle\ ->\ SeekMode\ ->\ Integer\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hSeek} \haddocktt{hdl\ mode\ i} sets the position of handle
+ \haddocktt{hdl} depending on \haddocktt{mode}.
+ The offset \haddocktt{i} is given in terms of 8-bit bytes.
+\par
+If \haddocktt{hdl} is block- or line-buffered, then seeking to a position which is not
+ in the current buffer will first cause any items in the output buffer to be
+ written to the device, and then cause the input buffer to be discarded.
+ Some handles may not be seekable (see \haddockid{hIsSeekable}), or only support a
+ subset of the possible positioning operations (for instance, it may only
+ be possible to seek to the end of a tape, or to a positive offset from
+ the beginning or current position).
+ It is not possible to set a negative I/O position, or for
+ a physical file, an I/O position beyond the current end-of-file.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{isIllegalOperationError} if the Handle is not seekable, or does
+    not support the requested seek mode.
+  * \haddocktt{isPermissionError} if a system resource limit would be exceeded.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+data\ SeekMode
+\end{tabular}]\haddockbegindoc
+\haddockbeginconstrs
+\haddockdecltt{=} & \haddockdecltt{AbsoluteSeek} & the position of \haddocktt{hdl} is set to \haddocktt{i}.
+ \\
+\haddockdecltt{|} & \haddockdecltt{RelativeSeek} & the position of \haddocktt{hdl} is set to offset \haddocktt{i}
+ from the current position.
+ \\
+\haddockdecltt{|} & \haddockdecltt{SeekFromEnd} & the position of \haddocktt{hdl} is set to offset \haddocktt{i}
+ from the end of the file.
+ \\
+\haddockendconstrs\par
+A mode that determines the effect of \haddocktt{hSeek} \haddocktt{hdl\ mode\ i}.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+instance\ Enum\ SeekMode\\instance\ Eq\ SeekMode\\instance\ Ord\ SeekMode\\instance\ Read\ SeekMode\\instance\ Show\ SeekMode\\instance\ Ix\ SeekMode
+\end{tabular}]
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hTell\ ::\ Handle\ ->\ IO\ Integer
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hTell} \haddocktt{hdl} returns the current position of the
+ handle \haddocktt{hdl}, as the number of bytes from the beginning of
+ the file.  The value returned may be subsequently passed to
+ \haddockid{hSeek} to reposition the handle to the current position.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{isIllegalOperationError} if the Handle is not seekable.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\subsection{Handle properties
+}
+Each of these operations returns \haddockid{True} if the handle has the
+ the specified property, or \haddockid{False} otherwise.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hIsOpen\ ::\ Handle\ ->\ IO\ Bool\\hIsClosed\ ::\ Handle\ ->\ IO\ Bool\\hIsReadable\ ::\ Handle\ ->\ IO\ Bool\\hIsWritable\ ::\ Handle\ ->\ IO\ Bool\\hIsSeekable\ ::\ Handle\ ->\ IO\ Bool
+\end{tabular}]
+\end{haddockdesc}
+\subsection{Terminal operations
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hIsTerminalDevice\ ::\ Handle\ ->\ IO\ Bool
+\end{tabular}]\haddockbegindoc
+Is the handle connected to a terminal?
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hSetEcho\ ::\ Handle\ ->\ Bool\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Set the echoing status of a handle connected to a terminal.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hGetEcho\ ::\ Handle\ ->\ IO\ Bool
+\end{tabular}]\haddockbegindoc
+Get the echoing status of a handle connected to a terminal.
+\par
+
+\end{haddockdesc}
+\subsection{Showing handle state
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hShow\ ::\ Handle\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+\haddockid{hShow} is in the \haddockid{IO} monad, and gives more comprehensive output
+ than the (pure) instance of \haddockid{Show} for \haddockid{Handle}.
+\par
+
+\end{haddockdesc}
+\section{Text input and output
+}
+\subsection{Text input
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hWaitForInput\ ::\ Handle\ ->\ Int\ ->\ IO\ Bool
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hWaitForInput} \haddocktt{hdl\ t}
+ waits until input is available on handle \haddocktt{hdl}.
+ It returns \haddockid{True} as soon as input is available on \haddocktt{hdl},
+ or \haddockid{False} if no input is available within \haddocktt{t} milliseconds.  Note that
+ \haddockid{hWaitForInput} waits until one or more full \emph{characters} are available,
+ which means that it needs to do decoding, and hence may fail
+ with a decoding error.
+\par
+If \haddocktt{t} is less than zero, then \haddocktt{hWaitForInput} waits indefinitely.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{isEOFError} if the end of file has been reached.
+\par
+
+\item
+ a decoding error, if the input begins with an invalid byte sequence
+    in this Handle's encoding.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hReady\ ::\ Handle\ ->\ IO\ Bool
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hReady} \haddocktt{hdl} indicates whether at least one item is
+ available for input from handle \haddocktt{hdl}.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{System.IO.Error.isEOFError} if the end of file has been reached.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hGetChar\ ::\ Handle\ ->\ IO\ Char
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hGetChar} \haddocktt{hdl} reads a character from the file or
+ channel managed by \haddocktt{hdl}, blocking until a character is available.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddockid{isEOFError} if the end of file has been reached.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hGetLine\ ::\ Handle\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hGetLine} \haddocktt{hdl} reads a line from the file or
+ channel managed by \haddocktt{hdl}.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddockid{isEOFError} if the end of file is encountered when reading
+    the \emph{first} character of the line.
+\par
+
+\end{itemize}
+If \haddockid{hGetLine} encounters end-of-file at any other point while reading
+ in a line, it is treated as a line terminator and the (partial)
+ line is returned.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hLookAhead\ ::\ Handle\ ->\ IO\ Char
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hLookAhead} returns the next character from the handle
+ without removing it from the input buffer, blocking until a character
+ is available.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{isEOFError} if the end of file has been reached.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hGetContents\ ::\ Handle\ ->\ IO\ String
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hGetContents} \haddocktt{hdl} returns the list of characters
+ corresponding to the unread portion of the channel or file managed
+ by \haddocktt{hdl}, which is put into an intermediate state, \emph{semi-closed}.
+ In this state, \haddocktt{hdl} is effectively closed,
+ but items are read from \haddocktt{hdl} on demand and accumulated in a special
+ list returned by \haddockid{hGetContents} \haddocktt{hdl}.
+\par
+Any operation that fails because a handle is closed,
+ also fails if a handle is semi-closed.  The only exception is \haddocktt{hClose}.
+ A semi-closed handle becomes closed:
+\par
+\begin{itemize}
+\item
+ if \haddocktt{hClose} is applied to it;
+\par
+
+\item
+ if an I/O error occurs when reading an item from the handle;
+\par
+
+\item
+ or once the entire contents of the handle has been read.
+\par
+
+\end{itemize}
+Once a semi-closed handle becomes closed, the contents of the
+ associated list becomes fixed.  The contents of this final list is
+ only partially specified: it will contain at least all the items of
+ the stream that were evaluated prior to the handle becoming closed.
+\par
+Any I/O errors encountered while a handle is semi-closed are simply
+ discarded.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddockid{isEOFError} if the end of file has been reached.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\subsection{Text output
+}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hPutChar\ ::\ Handle\ ->\ Char\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hPutChar} \haddocktt{hdl\ ch} writes the character \haddocktt{ch} to the
+ file or channel managed by \haddocktt{hdl}.  Characters may be buffered if
+ buffering is enabled for \haddocktt{hdl}.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddockid{isFullError} if the device is full; or
+\par
+
+\item
+ \haddockid{isPermissionError} if another system resource limit would be exceeded.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hPutStr\ ::\ Handle\ ->\ String\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hPutStr} \haddocktt{hdl\ s} writes the string
+ \haddocktt{s} to the file or channel managed by \haddocktt{hdl}.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddockid{isFullError} if the device is full; or
+\par
+
+\item
+ \haddockid{isPermissionError} if another system resource limit would be exceeded.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hPutStrLn\ ::\ Handle\ ->\ String\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+The same as \haddockid{hPutStr}, but adds a newline character.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+hPrint\ ::\ Show\ a\ =>\ Handle\ ->\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Computation \haddockid{hPrint} \haddocktt{hdl\ t} writes the string representation of \haddocktt{t}
+ given by the \haddockid{shows} function to the file or channel managed by \haddocktt{hdl}
+ and appends a newline.
+\par
+This operation may fail with:
+\par
+\begin{itemize}
+\item
+ \haddocktt{System.IO.Error.isFullError} if the device is full; or
+\par
+
+\item
+ \haddocktt{System.IO.Error.isPermissionError} if another system resource limit would be exceeded.
+\par
+
+\end{itemize}
+
+\end{haddockdesc}
+\subsection{Special cases for standard input and output
+}
+These functions are also exported by the \haddocktt{Prelude}.
+\par
+
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+interact\ ::\ (String\ ->\ String)\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+The \haddockid{interact} function takes a function of type \haddocktt{String->String}
+ as its argument.  The entire input from the standard input device is
+ passed to this function as its argument, and the resulting string is
+ output on the standard output device.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+putChar\ ::\ Char\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Write a character to the standard output device
+ (same as \haddockid{hPutChar} \haddockid{stdout}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+putStr\ ::\ String\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+Write a string to the standard output device
+ (same as \haddockid{hPutStr} \haddockid{stdout}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+putStrLn\ ::\ String\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+The same as \haddockid{putStr}, but adds a newline character.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+print\ ::\ Show\ a\ =>\ a\ ->\ IO\ ()
+\end{tabular}]\haddockbegindoc
+The \haddockid{print} function outputs a value of any printable type to the
+ standard output device.
+ Printable types are those that are instances of class \haddockid{Show}; \haddockid{print}
+ converts values to strings for output using the \haddockid{show} operation and
+ adds a newline.
+\par
+For example, a program to print the first 20 integers and their
+ powers of 2 could be written as:
+\par
+\begin{quote}
+{\haddockverb\begin{verbatim}
+ main = print ([(n, 2^n) | n <- [0..19]])
+\end{verbatim}}
+\end{quote}
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+getChar\ ::\ IO\ Char
+\end{tabular}]\haddockbegindoc
+Read a character from the standard input device
+ (same as \haddockid{hGetChar} \haddockid{stdin}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+getLine\ ::\ IO\ String
+\end{tabular}]\haddockbegindoc
+Read a line from the standard input device
+ (same as \haddockid{hGetLine} \haddockid{stdin}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+getContents\ ::\ IO\ String
+\end{tabular}]\haddockbegindoc
+The \haddockid{getContents} operation returns all user input as a single string,
+ which is read lazily as it is needed
+ (same as \haddockid{hGetContents} \haddockid{stdin}).
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+readIO\ ::\ Read\ a\ =>\ String\ ->\ IO\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{readIO} function is similar to \haddockid{read} except that it signals
+ parse failure to the \haddockid{IO} monad instead of terminating the program.
+\par
+
+\end{haddockdesc}
+\begin{haddockdesc}
+\item[\begin{tabular}{@{}l}
+readLn\ ::\ Read\ a\ =>\ IO\ a
+\end{tabular}]\haddockbegindoc
+The \haddockid{readLn} function combines \haddockid{getLine} and \haddockid{readIO}.
+\par
+
+\end{haddockdesc}
\ No newline at end of file