-- 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.4


-- | 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. A supply may be
--   turned into two different supplies by using the functions
--   <a>supplyLeft</a> and <a>supplyRight</a>.
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 supply of ints. WARNING: In general, this is not thread safe!
--   It should be OK, as long as the supply is not accessed by different
--   threads. So, if you are in a multi-threaded setting, first split the
--   supply, and give <i>different</i> supply values to the different
--   threads.
unsafeNewIntSupply :: IO (Supply Int)

-- | 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. This supply is different from the one generated
--   with <a>supplyRight</a>.
supplyLeft :: Supply a -> Supply a

-- | Generate a new supply. This supply is different from the one generated
--   with <a>supplyLeft</a>.
supplyRight :: Supply a -> Supply 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 by using <a>supplyLeft</a> and
--   <a>supplyRight</a> repeatedly.
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