Commit 9d93bcd0 authored by batterseapower's avatar batterseapower
Browse files

Document UniqSupply

parent a80b845e
......@@ -5,21 +5,23 @@
\begin{code}
module UniqSupply (
-- * Main data type
UniqSupply, -- Abstractly
-- ** Operations on supplies
uniqFromSupply, uniqsFromSupply, -- basic ops
mkSplitUniqSupply,
splitUniqSupply, listSplitUniqSupply,
UniqSM, -- type: unique supply monad
-- * Unique supply monad and its abstraction
UniqSM, MonadUnique(..),
-- ** Operations on the monad
initUs, initUs_,
lazyThenUs, lazyMapUs,
mapAndUnzipM,
MonadUnique(..),
mkSplitUniqSupply,
splitUniqSupply, listSplitUniqSupply,
-- Deprecated:
-- ** Deprecated operations on 'UniqSM'
getUniqueUs, getUs, returnUs, thenUs, mapUs
) where
......@@ -39,19 +41,17 @@ unsafeDupableInterleaveIO = unsafeInterleaveIO
\end{code}
%************************************************************************
%* *
\subsection{Splittable Unique supply: @UniqSupply@}
%* *
%************************************************************************
A value of type @UniqSupply@ is unique, and it can
supply {\em one} distinct @Unique@. Also, from the supply, one can
also manufacture an arbitrary number of further @UniqueSupplies@,
which will be distinct from the first and from all others.
\begin{code}
-- | A value of type 'UniqSupply' is unique, and it can
-- supply /one/ distinct 'Unique'. Also, from the supply, one can
-- also manufacture an arbitrary number of further 'UniqueSupply' values,
-- which will be distinct from the first and from all others.
data UniqSupply
= MkSplitUniqSupply FastInt -- make the Unique with this
UniqSupply UniqSupply
......@@ -60,11 +60,19 @@ data UniqSupply
\begin{code}
mkSplitUniqSupply :: Char -> IO UniqSupply
-- ^ Create a unique supply out of thin air. The character given must
-- be distinct from those of all calls to this function in the compiler
-- for the values generated to be truly unique.
splitUniqSupply :: UniqSupply -> (UniqSupply, UniqSupply)
listSplitUniqSupply :: UniqSupply -> [UniqSupply] -- Infinite
-- ^ Build two 'UniqSupply' from a single one, each of which
-- can supply its own 'Unique'.
listSplitUniqSupply :: UniqSupply -> [UniqSupply]
-- ^ Create an infinite list of 'UniqSupply' from a single one
uniqFromSupply :: UniqSupply -> Unique
-- ^ Obtain the 'Unique' from this particular 'UniqSupply'
uniqsFromSupply :: UniqSupply -> [Unique] -- Infinite
-- ^ Obtain an infinite list of 'Unique' that can be generated by constant splitting of the supply
\end{code}
\begin{code}
......@@ -102,6 +110,7 @@ uniqsFromSupply (MkSplitUniqSupply n _ s2) = mkUniqueGrimily (iBox n) : uniqsFro
%************************************************************************
\begin{code}
-- | A monad which just gives the ability to obtain 'Unique's
newtype UniqSM result = USM { unUSM :: UniqSupply -> (result, UniqSupply) }
instance Monad UniqSM where
......@@ -119,10 +128,11 @@ instance Applicative UniqSM where
(ff, us') -> case x us' of
(xx, us'') -> (ff xx, us'')
-- the initUs function also returns the final UniqSupply; initUs_ drops it
initUs :: UniqSupply -> UniqSM a -> (a,UniqSupply)
-- | Run the 'UniqSM' action, returning the final 'UniqSupply'
initUs :: UniqSupply -> UniqSM a -> (a, UniqSupply)
initUs init_us m = case unUSM m init_us of { (r,us) -> (r,us) }
-- | Run the 'UniqSM' action, discarding the final 'UniqSupply'
initUs_ :: UniqSupply -> UniqSM a -> a
initUs_ init_us m = case unUSM m init_us of { (r, _) -> r }
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment