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


-- | Abstractions over deferred folds
--   
--   This library is in an experimental state. Users should be prepared for
--   frequent updates.
@package deferred-folds
@version 0.9.18.6

module DeferredFolds.Unfoldl

-- | A projection on data, which only knows how to execute a strict
--   left-fold.
--   
--   It is a monad and a monoid, and is very useful for efficiently
--   aggregating the projections on data intended for left-folding, since
--   its concatenation (<tt>&lt;&gt;</tt>) has complexity of <tt>O(1)</tt>.
--   
--   <ul>
--   <li><i>Intuition</i></li>
--   </ul>
--   
--   The intuition for this abstraction can be derived from lists.
--   
--   Let's consider the <a>foldl'</a> function for lists:
--   
--   <pre>
--   foldl' :: (b -&gt; a -&gt; b) -&gt; b -&gt; [a] -&gt; b
--   </pre>
--   
--   If we rearrange its parameters we get
--   
--   <pre>
--   foldl' :: [a] -&gt; (b -&gt; a -&gt; b) -&gt; b -&gt; b
--   </pre>
--   
--   Which in Haskell is essentially the same as
--   
--   <pre>
--   foldl' :: [a] -&gt; (forall b. (b -&gt; a -&gt; b) -&gt; b -&gt; b)
--   </pre>
--   
--   We can isolate that part into an abstraction:
--   
--   <pre>
--   newtype Unfoldl a = Unfoldl (forall b. (b -&gt; a -&gt; b) -&gt; b -&gt; b)
--   </pre>
--   
--   Then we get to this simple morphism:
--   
--   <pre>
--   list :: [a] -&gt; Unfoldl a
--   list list = Unfoldl (\ step init -&gt; foldl' step init list)
--   </pre>
--   
--   We can do the same with say <a>Data.Text.Text</a>:
--   
--   <pre>
--   text :: Text -&gt; Unfoldl Char
--   text text = Unfoldl (\ step init -&gt; Data.Text.foldl' step init text)
--   </pre>
--   
--   And then we can use those both to concatenate with just an
--   <tt>O(1)</tt> cost:
--   
--   <pre>
--   abcdef :: Unfoldl Char
--   abcdef = list ['a', 'b', 'c'] &lt;&gt; text "def"
--   </pre>
--   
--   Please notice that up until this moment no actual data materialization
--   has happened and hence no traversals have appeared. All that we've
--   done is just composed a function, which only specifies which parts of
--   data structures to traverse to perform a left-fold. Only at the moment
--   where the actual folding will happen will we actually traverse the
--   source data. E.g., using the "fold" function:
--   
--   <pre>
--   abcdefLength :: Int
--   abcdefLength = fold Control.Foldl.length abcdef
--   </pre>
newtype Unfoldl a
Unfoldl :: (forall x. (x -> a -> x) -> x -> x) -> Unfoldl a

-- | Apply a Gonzalez fold
fold :: Fold input output -> Unfoldl input -> output

-- | Filter the values given a predicate
filter :: (a -> Bool) -> Unfoldl a -> Unfoldl a

-- | Construct from any foldable
foldable :: Foldable foldable => foldable a -> Unfoldl a

-- | Ints in the specified inclusive range
intsInRange :: Int -> Int -> Unfoldl Int

-- | Bytes of a bytestring
byteStringBytes :: ByteString -> Unfoldl Word8

-- | Bytes of a short bytestring
shortByteStringBytes :: ShortByteString -> Unfoldl Word8

-- | Elements of a prim array
primArray :: Prim prim => PrimArray prim -> Unfoldl prim

-- | Elements of a prim array coming paired with indices
primArrayWithIndices :: Prim prim => PrimArray prim -> Unfoldl (Int, prim)

-- | Unlift a monadic unfold
unfoldlM :: UnfoldlM Identity input -> Unfoldl input

-- | Lift a fold input mapping function into a mapping of unfolds
mapFoldInput :: (forall x. Fold b x -> Fold a x) -> Unfoldl a -> Unfoldl b

-- | Associations of a map
mapAssocs :: Map key value -> Unfoldl (key, value)

-- | Associations of an intmap
intMapAssocs :: IntMap value -> Unfoldl (Int, value)

module DeferredFolds.UnfoldlM

-- | A monadic variation of <a>DeferredFolds.Unfoldl</a>
newtype UnfoldlM m a
UnfoldlM :: (forall x. (x -> a -> m x) -> x -> m x) -> UnfoldlM m a

-- | Apply a Gonzalez fold
fold :: Fold input output -> UnfoldlM Identity input -> output

-- | Apply a monadic Gonzalez fold
foldM :: Monad m => FoldM m input output -> UnfoldlM m input -> m output

-- | A more efficient implementation of mapM_
mapM_ :: Monad m => (input -> m ()) -> UnfoldlM m input -> m ()
unfoldr :: Monad m => Unfoldr a -> UnfoldlM m a

-- | Same as <a>mapM_</a> with arguments flipped
forM_ :: Monad m => UnfoldlM m input -> (input -> m ()) -> m ()

-- | Check whether it's empty
null :: Monad m => UnfoldlM m input -> m Bool

-- | Filter the values given a predicate
filter :: Monad m => (a -> m Bool) -> UnfoldlM m a -> UnfoldlM m a

-- | Perform a monadic strict left fold
foldlM' :: Monad m => (output -> input -> m output) -> output -> UnfoldlM m input -> m output

-- | Construct from any foldable
foldable :: (Monad m, Foldable foldable) => foldable a -> UnfoldlM m a

-- | Lift a fold input mapping function into a mapping of unfolds
mapFoldMInput :: Monad m => (forall x. FoldM m b x -> FoldM m a x) -> UnfoldlM m a -> UnfoldlM m b

-- | Construct from a specification of how to execute a left-fold
foldlRunner :: Monad m => (forall x. (x -> a -> x) -> x -> x) -> UnfoldlM m a

-- | Construct from a specification of how to execute a right-fold
foldrRunner :: Monad m => (forall x. (a -> x -> x) -> x -> x) -> UnfoldlM m a

-- | Ints in the specified inclusive range
intsInRange :: Monad m => Int -> Int -> UnfoldlM m Int

-- | TVar contents
tVarValue :: TVar a -> UnfoldlM STM a

-- | Change the base monad using invariant natural transformations
hoist :: (forall a. m a -> n a) -> (forall a. n a -> m a) -> UnfoldlM m a -> UnfoldlM n a

-- | Bytes of a bytestring
byteStringBytes :: ByteString -> UnfoldlM IO Word8

-- | Bytes of a short bytestring
shortByteStringBytes :: Monad m => ShortByteString -> UnfoldlM m Word8

-- | Elements of a prim array
primArray :: (Monad m, Prim prim) => PrimArray prim -> UnfoldlM m prim

-- | Elements of a prim array coming paired with indices
primArrayWithIndices :: (Monad m, Prim prim) => PrimArray prim -> UnfoldlM m (Int, prim)

module DeferredFolds.Unfoldr

-- | A projection on data, which only knows how to execute a right-fold.
--   
--   It is a monad and a monoid, and is very useful for efficiently
--   aggregating the projections on data intended for right-folding, since
--   its concatenation (<tt>&lt;&gt;</tt>) has complexity of <tt>O(1)</tt>.
--   
--   <ul>
--   <li><i>Intuition</i></li>
--   </ul>
--   
--   The intuition of what this abstraction is all about can be derived
--   from lists.
--   
--   Let's consider the <a>foldr</a> function for lists:
--   
--   <pre>
--   foldr :: (a -&gt; b -&gt; b) -&gt; b -&gt; [a] -&gt; b
--   </pre>
--   
--   If we rearrange its parameters we get
--   
--   <pre>
--   foldr :: [a] -&gt; (a -&gt; b -&gt; b) -&gt; b -&gt; b
--   </pre>
--   
--   Which in Haskell is essentially the same as
--   
--   <pre>
--   foldr :: [a] -&gt; (forall b. (a -&gt; b -&gt; b) -&gt; b -&gt; b)
--   </pre>
--   
--   We can isolate that part into an abstraction:
--   
--   <pre>
--   newtype Unfoldr a = Unfoldr (forall b. (a -&gt; b -&gt; b) -&gt; b -&gt; b)
--   </pre>
--   
--   Then we get to this simple morphism:
--   
--   <pre>
--   list :: [a] -&gt; Unfoldr a
--   list list = Unfoldr (\ step init -&gt; foldr step init list)
--   </pre>
--   
--   We can do the same with say <a>Data.Text.Text</a>:
--   
--   <pre>
--   text :: Text -&gt; Unfoldr Char
--   text text = Unfoldr (\ step init -&gt; Data.Text.foldr step init text)
--   </pre>
--   
--   And then we can use those both to concatenate with just an
--   <tt>O(1)</tt> cost:
--   
--   <pre>
--   abcdef :: Unfoldr Char
--   abcdef = list ['a', 'b', 'c'] &lt;&gt; text "def"
--   </pre>
--   
--   Please notice that up until this moment no actual data materialization
--   has happened and hence no traversals have appeared. All that we've
--   done is just composed a function, which only specifies which parts of
--   data structures to traverse to perform a right-fold. Only at the
--   moment where the actual folding will happen will we actually traverse
--   the source data. E.g., using the "fold" function:
--   
--   <pre>
--   abcdefLength :: Int
--   abcdefLength = fold Control.Foldl.length abcdef
--   </pre>
newtype Unfoldr a
Unfoldr :: (forall x. (a -> x -> x) -> x -> x) -> Unfoldr a

-- | Elements of a vector
vector :: Vector vector a => vector a -> Unfoldr a

-- | Apply a Gonzalez fold
fold :: Fold input output -> Unfoldr input -> output

-- | Apply a monadic Gonzalez fold
foldM :: Monad m => FoldM m input output -> Unfoldr input -> m output

-- | Reverse the order.
--   
--   Use with care, because it requires to allocate all elements.
reverse :: Unfoldr a -> Unfoldr a
zipWith :: (a -> b -> c) -> Unfoldr a -> Unfoldr b -> Unfoldr c

-- | Filter the values given a predicate
filter :: (a -> Bool) -> Unfoldr a -> Unfoldr a
cons :: a -> Unfoldr a -> Unfoldr a
snoc :: a -> Unfoldr a -> Unfoldr a
takeWhile :: (a -> Bool) -> Unfoldr a -> Unfoldr a

-- | Insert a separator value between each element.
--   
--   Behaves the same way as <a>intersperse</a>.
intersperse :: a -> Unfoldr a -> Unfoldr a
take :: Int -> Unfoldr a -> Unfoldr a

-- | Construct from any foldable
foldable :: Foldable foldable => foldable a -> Unfoldr a

-- | Ints in the specified inclusive range
intsInRange :: Int -> Int -> Unfoldr Int

-- | Bytes of a bytestring
byteStringBytes :: ByteString -> Unfoldr Word8

-- | Bytes of a short bytestring
shortByteStringBytes :: ShortByteString -> Unfoldr Word8

-- | Elements of a prim array
primArray :: Prim prim => PrimArray prim -> Unfoldr prim

-- | Elements of a prim array coming paired with indices
primArrayWithIndices :: Prim prim => PrimArray prim -> Unfoldr (Int, prim)

-- | Associations of a map
mapAssocs :: Map key value -> Unfoldr (key, value)

-- | Associations of an intmap
intMapAssocs :: IntMap value -> Unfoldr (Int, value)

-- | Elements of IntSet.
intSet :: IntSet -> Unfoldr Int

-- | Ascending infinite stream of enums starting from the one specified
enumsFrom :: Enum a => a -> Unfoldr a

-- | Enums in the specified inclusive range
enumsInRange :: (Enum a, Ord a) => a -> a -> Unfoldr a

-- | Ascending infinite stream of ints starting from the one specified
intsFrom :: Int -> Unfoldr Int

-- | Keys of a hash-map
hashMapKeys :: HashMap key value -> Unfoldr key

-- | Associations of a hash-map
hashMapAssocs :: HashMap key value -> Unfoldr (key, value)

-- | Value of a hash-map by key
hashMapAt :: (Hashable key, Eq key) => HashMap key value -> key -> Unfoldr value

-- | Value of a hash-map by key

-- | <i>Deprecated: Use <a>hashMapAt</a> instead</i>
hashMapValue :: (Hashable key, Eq key) => key -> HashMap key value -> Unfoldr value

-- | Values of a hash-map by their keys
hashMapValues :: (Hashable key, Eq key) => HashMap key value -> Unfoldr key -> Unfoldr value

-- | Elements of a vector coming paired with indices
vectorWithIndices :: Vector vector a => vector a -> Unfoldr (Int, a)

-- | Binary digits of a non-negative integral number.
binaryDigits :: Integral a => a -> Unfoldr a

-- | Binary digits of a non-negative integral number in reverse order.
reverseBinaryDigits :: Integral a => a -> Unfoldr a

-- | Digits of a non-negative number in numeral system based on the
--   specified radix. The digits come in reverse order.
--   
--   E.g., here's how an unfold of binary digits in proper order looks:
--   
--   <pre>
--   binaryDigits :: Integral a =&gt; a -&gt; Unfoldr a
--   binaryDigits = <a>reverse</a> . <a>reverseDigits</a> 2
--   </pre>
reverseDigits :: Integral a => a -> a -> Unfoldr a

-- | Octal digits of a non-negative integral number.
octalDigits :: Integral a => a -> Unfoldr a

-- | Octal digits of a non-negative integral number in reverse order.
reverseOctalDigits :: Integral a => a -> Unfoldr a

-- | Decimal digits of a non-negative integral number.
decimalDigits :: Integral a => a -> Unfoldr a

-- | Decimal digits of a non-negative integral number in reverse order.
--   More efficient than <a>decimalDigits</a>.
reverseDecimalDigits :: Integral a => a -> Unfoldr a

-- | Hexadecimal digits of a non-negative number.
hexadecimalDigits :: Integral a => a -> Unfoldr a

-- | Hexadecimal digits of a non-negative number in reverse order.
reverseHexadecimalDigits :: Integral a => a -> Unfoldr a

-- | Lift into an unfold, which produces pairs with index.
zipWithIndex :: Unfoldr a -> Unfoldr (Int, a)

-- | Lift into an unfold, which produces pairs with right-associative
--   index.

-- | <i>Deprecated: This function builds up stack. Use <a>zipWithIndex</a>
--   instead.</i>
zipWithReverseIndex :: Unfoldr a -> Unfoldr (Int, a)

-- | Indices of set bits.
setBitIndices :: FiniteBits a => a -> Unfoldr Int

-- | Indices of unset bits.
unsetBitIndices :: FiniteBits a => a -> Unfoldr Int

-- | Reproduces the behaviour of <a>unpack</a>.
--   
--   Implementation is efficient and avoids allocation of an intermediate
--   list.
textChars :: Text -> Unfoldr Char

-- | Reproduces the behaviour of <a>words</a>.
--   
--   Implementation is efficient and avoids allocation of an intermediate
--   list.
textWords :: Text -> Unfoldr Text

-- | Transformer of chars, replaces all space-like chars with space, all
--   newline-like chars with <tt>\n</tt>, and trims their duplicate
--   sequences to single-char. Oh yeah, it also trims whitespace from
--   beginning and end.
trimWhitespace :: Unfoldr Char -> Unfoldr Char
