@@ -82,6 +82,7 @@ module Streamly.Internal.Data.Unfold
8282 , nilM
8383 , consM
8484 , effect
85+ , singletonM
8586 , singleton
8687 , identity
8788 , const
@@ -158,6 +159,10 @@ import qualified Streamly.Internal.Data.Stream.StreamD as D
158159
159160-- | Map a function on the input argument of the 'Unfold'.
160161--
162+-- @
163+-- lmap f = concat (singleton f)
164+-- @
165+--
161166-- /Internal/
162167{-# INLINE_NORMAL lmap #-}
163168lmap :: (a -> c) -> Unfold m c b -> Unfold m a b
@@ -165,11 +170,18 @@ lmap f (Unfold ustep uinject) = Unfold ustep (uinject . f)
165170
166171-- | Map an action on the input argument of the 'Unfold'.
167172--
173+-- @
174+-- lmapM f = concat (singletonM f)
175+-- @
176+--
168177-- /Internal/
169178{-# INLINE_NORMAL lmapM #-}
170179lmapM :: Monad m => (a -> m c) -> Unfold m c b -> Unfold m a b
171180lmapM f (Unfold ustep uinject) = Unfold ustep (\x -> f x >>= uinject)
172181
182+-- XXX change the signature to the following?
183+-- supply :: a -> Unfold m a b -> Unfold m Void b
184+--
173185-- | Supply the seed to an unfold closing the input end of the unfold.
174186--
175187-- /Internal/
@@ -178,6 +190,9 @@ lmapM f (Unfold ustep uinject) = Unfold ustep (\x -> f x >>= uinject)
178190supply :: Unfold m a b -> a -> Unfold m Void b
179191supply unf a = lmap (Prelude.const a) unf
180192
193+-- XXX change the signature to the following?
194+-- supplyFirst :: a -> Unfold m (a, b) c -> Unfold m b c
195+--
181196-- | Supply the first component of the tuple to an unfold that accepts a tuple
182197-- as a seed resulting in a fold that accepts the second component of the tuple
183198-- as a seed.
@@ -188,6 +203,9 @@ supply unf a = lmap (Prelude.const a) unf
188203supplyFirst :: Unfold m (a, b) c -> a -> Unfold m b c
189204supplyFirst unf a = lmap (a, ) unf
190205
206+-- XXX change the signature to the following?
207+-- supplySecond :: b -> Unfold m (a, b) c -> Unfold m a c
208+--
191209-- | Supply the second component of the tuple to an unfold that accepts a tuple
192210-- as a seed resulting in a fold that accepts the first component of the tuple
193211-- as a seed.
@@ -376,25 +394,33 @@ effect eff = Unfold step inject
376394 step True = eff >>= \r -> return $ Yield r False
377395 step False = return Stop
378396
397+-- XXX change it to yieldM or change yieldM in Prelude to singletonM
398+--
379399-- | Lift a monadic function into an unfold generating a singleton stream.
380400--
381−{-# INLINE singleton #-}
382−singleton :: Monad m => (a -> m b) -> Unfold m a b
383−singleton f = Unfold step inject
401+{-# INLINE singletonM #-}
402+singletonM :: Monad m => (a -> m b) -> Unfold m a b
403+singletonM f = Unfold step inject
384404 where
385405 inject x = return $ Just x
386406 {-# INLINE_LATE step #-}
387407 step (Just x) = f x >>= \r -> return $ Yield r Nothing
388408 step Nothing = return Stop
389409
410+-- | Lift a pure function into an unfold generating a singleton stream.
411+--
412+{-# INLINE singleton #-}
413+singleton :: Monad m => (a -> b) -> Unfold m a b
414+singleton f = singletonM $ return . f
415+
390416-- | Identity unfold. Generates a singleton stream with the seed as the only
391417-- element in the stream.
392418--
393−-- > identity = singleton return
419+-- > identity = singletonM return
394420--
395421{-# INLINE identity #-}
396422identity :: Monad m => Unfold m a a
397−identity = singleton return
423+identity = singletonM return
398424
399425const :: Monad m => m b -> Unfold m a b
400426const m = Unfold step inject
@@ -570,6 +596,11 @@ zipWith f = zipWithM (\a b -> return (f a b))
570596
571597data ConcatState s1 s2 = ConcatOuter s1 | ConcatInner s1 s2
572598
599+-- | Apply the second unfold to each output element of the first unfold and
600+-- flatten the output in a single stream.
601+--
602+-- /Internal/
603+--
573604{-# INLINE_NORMAL concat #-}
574605concat :: Monad m => Unfold m a b -> Unfold m b c -> Unfold m a c
575606concat (Unfold step1 inject1) (Unfold step2 inject2) = Unfold step inject
@@ -598,6 +629,9 @@ concat (Unfold step1 inject1) (Unfold step2 inject2) = Unfold step inject
598629data OuterProductState s1 s2 sy x y =
599630 OuterProductOuter s1 y | OuterProductInner s1 sy s2 x
600631
632+-- | Create an outer product (vector product or cartesian product) of the
633+-- output streams of two unfolds.
634+--
601635{-# INLINE_NORMAL outerProduct #-}
602636outerProduct :: Monad m
603637 => Unfold m a b -> Unfold m c d -> Unfold m (a, c) (b, d)
@@ -628,6 +662,9 @@ outerProduct (Unfold step1 inject1) (Unfold step2 inject2) = Unfold step inject
628662
629663data ConcatMapState s1 s2 = ConcatMapOuter s1 | ConcatMapInner s1 s2
630664
665+-- | Map an unfold generating action to each element of an unfold and
666+-- flattern the results into a single stream.
667+--
631668{-# INLINE_NORMAL concatMapM #-}
632669concatMapM :: Monad m
633670 => (b -> m (Unfold m () c)) -> Unfold m a b -> Unfold m a c