-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A library for generating values without having to thread state.
--   
--   This library can be used to generate values (for example, new names)
--   without the need to thread state. This means that functions that need
--   to generate new values only need a supply object as an argument, and
--   they do not need to return a new supply object as a result. This
--   decreases the number of data-dependencies in a program, which makes it
--   easier to exploit parallelism. The technique for generating new values
--   is based on the paper ''On Generating Unique Names'' by Lennart
--   Augustsson, Mikael Rittri, and Dan Synek.
@package value-supply
@version 0.6


-- | The technique for generating new values is based on the paper ''On
--   Generating Unique Names'' by Lennart Augustsson, Mikael Rittri, and
--   Dan Synek.
module Data.Supply

-- | A type that can be used to generate values on demand.
data Supply a

-- | Creates a new supply of values. The arguments specify how to generate
--   values: the first argument is an initial value, the second specifies
--   how to generate a new value from an existing one.
newSupply :: a -> (a -> a) -> IO (Supply a)

-- | A supply of values that are in the <a>Enum</a> class. The initial
--   value is <tt>toEnum 0</tt>, new values are generates with <a>succ</a>.
newEnumSupply :: Enum a => IO (Supply a)

-- | A supply of values that are in the <a>Num</a> class. The initial value
--   is 0, new values are generated by adding 1.
newNumSupply :: Num a => IO (Supply a)

-- | Create a new supply of values. WARNING: This version is faster then
--   <a>newSupply</a> but it is not completely thread safe, so use only if
--   performance is an issue!
--   
--   Rules for using the generated supplies: * Supply splitting should be
--   evaluated in a single thread. For example, use <a>case</a> with
--   <a>split2</a> to force the splitting of a supply. * Different threads
--   should work with different supplies. For example, one could (strictly)
--   split a supply, and then fork new threads with the resulting supplies.
newDupableSupply :: a -> (a -> a) -> IO (Supply a)

-- | A supply of values that are in the <a>Enum</a> class. The initial
--   value is <tt>toEnum 0</tt>, new values are generates with <a>succ</a>.
--   WARNING: See comment on <a>newDupableSupply</a>
newDupableEnumSupply :: Enum a => IO (Supply a)

-- | A supply of values that are in the <a>Num</a> class. The initial value
--   is 0, new values are generated by adding 1. WARNING: See comment on
--   <a>newDupableSupply</a>
newDupableNumSupply :: Num a => IO (Supply a)

-- | Get the value of a supply. This function, together with
--   <a>modifySupply</a> forms a comonad on <a>Supply</a>.
supplyValue :: Supply a -> a

-- | Generate a new supply by systematically applying a function to an
--   existing supply. This function, together with <a>supplyValue</a> form
--   a comonad on <a>Supply</a>.
modifySupply :: Supply a -> (Supply a -> b) -> Supply b

-- | Generate an infinite list of supplies.
split :: Supply a -> [Supply a]

-- | Split a supply into two different supplies. The resulting supplies are
--   different from the input supply.
split2 :: Supply a -> (Supply a, Supply a)

-- | Split a supply into three different supplies.
split3 :: Supply a -> (Supply a, Supply a, Supply a)

-- | Split a supply into four different supplies.
split4 :: Supply a -> (Supply a, Supply a, Supply a, Supply a)
instance Functor Supply