@@ -0,0 +1,73 @@
1+{-# LANGUAGE BangPatterns #-}
2+{-# LANGUAGE CPP #-}
3+{-# LANGUAGE ExistentialQuantification #-}
4+{-# LANGUAGE FlexibleContexts #-}
5+{-# LANGUAGE PatternSynonyms #-}
6+{-# LANGUAGE RankNTypes #-}
7+{-# LANGUAGE RecordWildCards #-}
8+{-# LANGUAGE ScopedTypeVariables #-}
9+{-# LANGUAGE TupleSections #-}
10+
11+#include "inline.hs"
12+
13+-- |
14+-- Module : Streamly.Data.Unfold
15+-- Copyright : (c) 2019 Composewell Technologies
16+-- License : BSD3
17+-- Maintainer : streamly@composewell.com
18+-- Stability : experimental
19+-- Portability : GHC
20+--
21+-- 'Unfold' type represents an effectful action that generates a stream of
22+-- values from a single starting value often called a seed value. It can also
23+-- be called a producer or a source of stream. It is a data representation of
24+-- the standard 'S.unfoldr' function. An 'Unfold' can be converted into a
25+-- stream using 'S.unfold' by supplying the seed.
26+--
27+-- = Performance Notes
28+--
29+-- 'Unfold' type allows multiple unfold actions to be composed into a single
30+-- unfold function in an efficient manner by enabling the compiler to perform
31+-- stream fusion optimization.
32+-- @Unfold m a b@ can be considered roughly equivalent to an action @a -> t m
33+-- b@ (where @t@ is a stream type). Instead of using an 'Unfold' one could just
34+-- use a function of the shape @a -> t m b@. However, working with stream types
35+-- like 'S.SerialT' does not allow the compiler to perform stream fusion
36+-- optimization when merging, appending or concatenating multiple streams.
37+-- Even though stream based combinator have excellent performance, they are
38+-- much less efficient when compared to combinators using 'Unfold'. For
39+-- example, the 'S.concatMap' combinator which uses @a -> t m b@ (where @t@ is
40+-- a stream type) to generate streams is much less efficient compared to
41+-- 'S.concatUnfold'.
42+--
43+-- On the other hand, transformation operations on stream types are as
44+-- efficient as transformations on 'Unfold'.
45+--
46+-- We should note that in some cases working with stream types may be more
47+-- convenient compared to working with the 'Unfold' type. However, if extra
48+-- performance boost is important then 'Unfold' based composition should be
49+-- preferred compared to stream based composition when merging or concatenating
50+-- streams.
51+--
52+-- = Programmer Notes
53+--
54+-- > import qualified Streamly.Data.Unfold as UF
55+--
56+-- More, not yet exposed, unfold combinators can be found in
57+-- "Streamly.Internal.Data.Unfold".
58+
59+-- The stream types (e.g. 'S.SerialT') can be considered as a special case of
60+-- 'Unfold' with no starting seed.
61+--
62+module Streamly.Data.Unfold
63+ (
64+ -- * Unfold Type
65+ Unfold
66+ )
67+where
68+
69+import Prelude hiding (concat, map, takeWhile, take, filter, const)
70+import Streamly.Internal.Data.Unfold
71+
72+-- imported for documentation links
73+import qualified Streamly.Prelude as S