@@ -3,18 +3,19 @@ module Lazy.Stream ( head, tail
33 , map, apply, zip, zipWith, scanl
44 , take, drop, splitAt
55 , sampleOn
6+ , filter, takeWhile, dropWhile, splitWith
67 ) where
78
8−{-| Library for Infinite Streams
9+{-| This library is for creating and manipulating infinite streams
910
1011# Create
11−@docs cons, cons', iterate, repeat, cycle
12+@docs cons, cons', repeat, cycle, iterate
1213
13−# Observe
14−@docs head, tail, sampleOn, take, drop, splitAt
14+# Use
15+@docs head, tail, sampleOn, take, takeWhile, drop, dropWhile, splitAt, splitWith
1516
1617# Transform
17−@docs map, apply, zip, zipWith, scanl
18+@docs map, zip, zipWith, scanl, filter, apply
1819
1920-}
2021
@@ -27,88 +28,170 @@ data Stream a = S (Lazy (a, Stream a))
2728unS : Stream a -> (a, Stream a)
2829unS (S t) = force t
2930
30−{-| Compute the first element of a Stream -}
31+{-| Get the first element of a stream, called the `head`.
32+
33+```haskell
34+head ones == 1
35+```
36+-}
3137head : Stream a -> a
3238head = fst . unS
3339
34−{-| Compute the next piece of a Stream -}
40+{-| Drop the `head` of a stream, leaving you with the `tail`.
41+
42+```haskell
43+-- 1, 1, 1, 1, ...
44+stillAllOnes = tail
45+```
46+-}
3547tail : Stream a -> Stream a
3648tail = snd . unS
3749
38−{-| Create a Stream -}
50+{-| Create a stream:
51+
52+```haskell
53+-- 1, 1, 1, 1, ...
54+ones = cons 1 (\() -> ones)
55+```
56+ -}
3957cons : a -> (() -> Stream a) -> Stream a
4058cons x txs = let mtxs = lazy txs in
4159 S . lazy <| \() ->
4260 (x, force mtxs)
4361
44−{-| Lazily create a Stream. -}
62+{-| Create a stream that is slightly more lazy. Notice that the
63+head of the stream is defined within the thunk, so its evaluation
64+is delayed. This is nice when each element of the stream is costly to compute.
65+
66+```haskell
67+-- 1, 1, 1, 1, ...
68+ones = cons' (\_ -> (1,ones))
69+```
70+-}
4571cons' : (() -> (a, Stream a)) -> Stream a
4672cons' = S . lazy
4773
48−{-| Create a stream of repeated applications of f to x:
74+{-| Iteratively apply a function to a value:
75+
76+```haskell
77+-- x, f x, f (f x), f (f (f x)), ...
78+iterate f x
4979
50− iterate f x = S.cons x (S.cons (f x) (S.cons (f (f x)) ...))
80+-- 2, 4, 8, 16, ...
81+powersOf2 = iterate (\n -> n^2) 2
82+```
5183-}
5284iterate : (a -> a) -> a -> Stream a
53−iterate f x = cons' <| \() ->
54− (x, iterate f (f x))
85+iterate f x =
86+ cons' <| \_ -> (x, iterate f (f x))
87+
88+{-| Repeat a value infinitely:
5589
56−{-| Create an infinite Stream of xs. -}
90+```haskell
91+-- 1, 1, 1, 1, ...
92+ones = repeat 1
93+```
94+ -}
5795repeat : a -> Stream a
5896repeat x = let go = cons x <| \() -> go
5997 in go
6098
61−{-| Cycle through the elements of the nonempty list (x :: xs) -}
99+{-| Infinitely cycle through a list, where the head and tail of
100+the list are given separately to ensure that no one tries to cycle
101+on an empty list:
102+
103+```haskell
104+-- "Alice", "Bob", "Alice", "Bob", ...
105+cycle "Alice" ["Bob"]
106+```
107+-}
62108cycle : a -> [a] -> Stream a
63−cycle x xs = let cycle' ys = case ys of
64− [] -> go
65− (y :: ys) -> cons y <| \() ->
66− cycle' ys
67− go = cons' <| \() ->
68− (x, cycle' xs)
69− in go
70−
71−{-| Apply a function to every element of a Stream. -}
109+cycle x xs =
110+ let cycle' ys = case ys of
111+ [] -> go
112+ (y :: ys) -> cons y (\_ -> cycle' ys)
113+ go = cons' <| \_ -> (x, cycle' xs)
114+ in go
115+
116+{-| Apply a function to every element of a Stream.
117+
118+```haskell
119+-- 2, 2, 2, 2, ...
120+twos = map (\n -> n + 1) ones
121+```
122+-}
72123map : (a -> b) -> Stream a -> Stream b
73−map f xs = cons' <| \() ->
74− (f (head xs), map f (tail xs))
124+map f xs =
125+ cons' <| \_ -> (f (head xs), map f (tail xs))
75126
76−{-| Pairwise apply a stream of functions to a stream of inputs.
77− Together with map, generalizes zipWith to n arguments.
127+{-| Pairwise apply a stream of functions to a stream of arguments.
128+When paired with `map`, this can be used to emulate `zipWith` over *n* streams.
78129
79− zipWith2 : (a -> b -> c -> d) -> Stream a -> Stream b -> Stream c -> Stream d
80− zipWith2 f xs ys zs = f `S.map` xs `S.apply` ys `S.apply` zs
130+```haskell
131+zipWith3 : (a -> b -> c -> d) -> Stream a -> Stream b -> Stream c -> Stream d
132+zipWith3 f xs ys zs = f `S.map` xs `S.apply` ys `S.apply` zs
133+```
81134-}
82135apply : Stream (a -> b) -> Stream a -> Stream b
83136apply fs xs = zipWith (<|) fs xs
84137
85−{-| Combine two streams, combining them into tuples pairwise. -}
86−zip : Stream a -> Stream b -> Stream (a, b)
138+{-| Combine two streams, putting them into tuples pairwise:
139+
140+```haskell
141+-- (1,2), (1,4), (1,8), (1,16), ...
142+pairs = zip ones powersOf2
143+```
144+-}
145+zip : Stream a -> Stream b -> Stream (a,b)
87146zip = zipWith (\x y -> (x,y))
88147
89−{-| Combine two streams, combining them with the given function. -}
148+{-| Combine two streams, applying the given function pairwise:
149+
150+```haskell
151+-- 3, 5, 9, 17, ...
152+zipWith (+) ones powersOf2
153+```
154+-}
90155zipWith : (a -> b -> c) -> Stream a -> Stream b -> Stream c
91156zipWith f xs ys = cons' <| \() ->
92157 (f (head xs) (head ys),
93158 zipWith f (tail xs) (tail ys))
94159
95−{-| Reduce a Stream from the left, building an infinite stream of reductions. -}
160+{-| Scan over a stream from the left, building an infinite stream of reductions.
161+
162+```haskell
163+-- 0, 1, 2, 3, ...
164+runningTotal = scanl (+) 0 ones
165+```
166+-}
96167scanl : (a -> b -> b) -> b -> Stream a -> Stream b
97−scanl f init xs = cons' <| \() ->
98− (init,
99− scanl f (f (head xs) init) (tail xs))
168+scanl f init xs =
169+ cons' <| \() -> (init, scanl f (f (head xs) init) (tail xs))
100170
101−{-| Compute the first n elements of a stream into a list. -}
171+{-| Take the first *n* elements of a stream
172+
173+```haskell
174+take 5 powersOf2 == [2,4,8,16,32]
175+```
176+-}
102177take : Int -> Stream a -> [a]
103178take n xs = fst <| splitAt n xs
104179
105−{-| Drop n elements from the front of a stream. -}
180+{-| Drop the first *n* elements of a stream
181+
182+```haskell
183+-- 64, 128, 256, 512, ...
184+drop 5 powersOf2
185+```
186+-}
106187drop : Int -> Stream a -> Stream a
107188drop n xs = snd <| splitAt n xs
108189
109−{-| Combination of take and drop.
190+{-| Combination of `take` and `drop`
110191
111− splitAt n xs == (take n xs, drop n xs)
192+```haskell
193+splitAt n xs == (take n xs, drop n xs)
194+```
112195-}
113196splitAt : Int -> Stream a -> ([a], Stream a)
114197splitAt n xs = case n of
@@ -117,9 +200,76 @@ splitAt n xs = case n of
117200 in (head xs :: heads, end)
118201
119202{-| Turn a stream into a signal of the elements of the stream,
120− advancing through the stream whenever an event in the given signal is
121− fired.
203+advancing through the stream whenever an event in the given signal is
204+fired.
122205-}
123206sampleOn : Signal b -> Stream a -> Signal a
124207sampleOn sig str = let tails = foldp (\_ -> tail) str sig in
125208 head <~ tails
209+
210+{-| Filter the elements of a Stream according to a predicate.
211+
212+```haskell
213+-- 1, 3, 5, 7, ...
214+filter isOdd naturals
215+
216+-- Bad! Infinite loop!
217+filter isOdd twos
218+```
219+
220+This can infinite loop if no more elements in the stream satisfy the predicate!
221+-}
222+filter : (a -> Bool) -> Stream a -> Stream a
223+filter pred xs = cons' <| (\() ->
224+ let (hd, tl) = unS xs in
225+ case pred hd of
226+ True -> (hd, filter pred tl)
227+ False -> unS <| filter pred tl)
228+
229+{-| Take values from the stream for as long as the predicate holds.
230+This can infinite loop if all elements of the stream satisfy the predicate!
231+
232+```haskell
233+takeWhile (\n -> n < 10) powersOf2 == [2,4,8]
234+
235+-- Bad! Infinite loop!
236+takeWhile isEven powersOf2
237+```
238+
239+This can infinite loop if all elements of the stream satisfy the predicate!
240+-}
241+takeWhile : (a -> Bool) -> Stream a -> [a]
242+takeWhile pred xs = fst <| splitWith pred xs
243+
244+{-| Drop values from the stream as long as the predicate holds.
245+
246+```haskell
247+-- 16, 32, 64, 128, ...
248+dropWhile (\n -> n < 10) powersOf2
249+
250+-- Bad! Infinite loop!
251+dropWhile isEven powersOf2
252+```
253+
254+This can infinite loop if all elements of the stream satisfy the predicate!
255+-}
256+dropWhile : (a -> Bool) -> Stream a -> Stream a
257+dropWhile pred xs = snd <| splitWith pred xs
258+
259+{-| Combination of `takeWhile` and `dropWhile`. Split a stream when
260+the predicate no longer holds.
261+
262+```haskell
263+splitWith pred xs == (takeWhile pred xs, dropWhile pred xs)
264+
265+splitWith (\n -> n < 10) powersOf2 == ([2,4,8], ...)
266+```
267+
268+This can infinite loop if all elements satisfy the predicate!
269+-}
270+splitWith : (a -> Bool) -> Stream a -> ([a], Stream a)
271+splitWith pred xs = let (hd, tl) = unS xs in
272+ case pred hd of
273+ True -> let (taken, dropped) = splitWith pred tl
274+ in (hd :: taken, dropped)
275+ False -> ([], xs)