git.iko.soy/streamly
on fa75413 help sign in
streamly/src/Streamly/Data/Unfold.hs
72 lines 2.9 kB history raw
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 #-}
11#include "inline.hs"
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. Values can be
23-- generated and /pulled/ from the 'Unfold' one at a time. It can also be
24-- called a producer or a source of stream. It is a data representation of the
25-- standard 'S.unfoldr' function. An 'Unfold' can be converted into a stream
26-- type using 'S.unfold' by supplying the seed.
27--
28-- = Performance Notes
29--
30-- 'Unfold' representation is more efficient than using streams when combining
31-- streams. 'Unfold' type allows multiple unfold actions to be composed into a
32-- single unfold function in an efficient manner by enabling the compiler to
33-- perform stream fusion optimization.
34-- @Unfold m a b@ can be considered roughly equivalent to an action @a -> t m
35-- b@ (where @t@ is a stream type). Instead of using an 'Unfold' one could just
36-- use a function of the shape @a -> t m b@. However, working with stream types
37-- like 'S.SerialT' does not allow the compiler to perform stream fusion
38-- optimization when merging, appending or concatenating multiple streams.
39-- Even though stream based combinator have excellent performance, they are
40-- much less efficient when compared to combinators using 'Unfold'. For
41-- example, the 'S.concatMap' combinator which uses @a -> t m b@ (where @t@ is
42-- a stream type) to generate streams is much less efficient compared to
43-- 'S.concatUnfold'.
44--
45-- On the other hand, transformation operations on stream types are as
46-- efficient as transformations on 'Unfold'.
47--
48-- We should note that in some cases working with stream types may be more
49-- convenient compared to working with the 'Unfold' type. However, if extra
50-- performance boost is important then 'Unfold' based composition should be
51-- preferred compared to stream based composition when merging or concatenating
52-- streams.
53--
54-- = Programmer Notes
55--
56-- > import qualified Streamly.Data.Unfold as UF
57--
58-- More, not yet exposed, unfold combinators can be found in
59-- "Streamly.Internal.Data.Unfold".
61-- The stream types (e.g. 'S.SerialT') can be considered as a special case of
62-- 'Unfold' with no starting seed.
63--
64module Streamly.Data.Unfold
65 (
66 -- * Unfold Type
67 Unfold
68 )
69where
71import Prelude hiding (concat, map, takeWhile, take, filter, const)
72import Streamly.Internal.Data.Unfold