@@ -1,7 +1,7 @@
2-- Module : Streamly.Internal.Data.Unfold.Enumeration
2-- Module : Streamly.Internal.Data.Unfold.Enumeration
3−-- Copyright : (c) 2019 Composewell Technologies
3+-- Copyright : (c) 2019, 2021 Composewell Technologies
4−-- License : BSD3
4+-- License : BSD-3-Clause
5-- Maintainer : streamly@composewell.com
5-- Maintainer : streamly@composewell.com
6-- Stability : experimental
6-- Stability : experimental
7-- Portability : GHC
7-- Portability : GHC
@@ -61,8 +61,8 @@ import Data.Ratio
61import Data.Word
61import Data.Word
62import Numeric.Natural
62import Numeric.Natural
63import Data.Functor.Identity (Identity(..))
63import Data.Functor.Identity (Identity(..))
64−import Streamly.Internal.Data.Unfold.Type
65import Streamly.Internal.Data.Stream.StreamD.Step (Step(..))
64import Streamly.Internal.Data.Stream.StreamD.Step (Step(..))
65+import Streamly.Internal.Data.Unfold.Type
66import Prelude
66import Prelude
67 hiding (map, mapM, takeWhile, take, filter, const, zipWith
67 hiding (map, mapM, takeWhile, take, filter, const, zipWith
68 , drop, dropWhile)
68 , drop, dropWhile)
@@ -71,34 +71,18 @@ import Prelude
71-- Enumeration of Num
71-- Enumeration of Num
72------------------------------------------------------------------------------
72------------------------------------------------------------------------------
74−-- | Generate an infinite stream starting from a starting value with default
74+-- | Unfolds @(from, next)@ generating an infinite stream starting from @from@
75−-- stride of value 1. The implementation is numerically stable for floating
75+-- and @next@ values with a stride of @(next - from)@. After the value
76−-- point values.
76+-- overflows it keeps enumerating in a cycle:
78−-- Note 'enumerateFromStepIntegral' is faster for integrals.
78+-- >>> Stream.toList $ Stream.take 10 $ Stream.unfold Unfold.enumerateFromThenNum (255::Word8,0)
79+-- [255,0,1,2,3,4,5,6,7,8]
82−{-# INLINE enumerateFromNum #-}
83−enumerateFromNum :: (Monad m, Num a) => Unfold m a a
84−enumerateFromNum = Unfold step inject
88− inject !from = return (from, 1, 0)
90− {-# INLINE_LATE step #-}
91− step (from, stride, i) =
93− (Yield $! (from + i * stride)) $! (from, stride, i + 1)
95−-- | Generate an infinite stream starting from a from and next values with
96−-- stride of (next-from). The implementation is numerically stable for
81+-- The implementation is numerically stable for floating point values.
97−-- floating point values.
99-- Note 'enumerateFromStepIntegral' is faster for integrals.
83-- Note 'enumerateFromStepIntegral' is faster for integrals.
101−-- /Pre-release/
85+-- /Internal/
103{-# INLINE enumerateFromThenNum #-}
87{-# INLINE enumerateFromThenNum #-}
104enumerateFromThenNum :: (Monad m, Num a) => Unfold m (a, a) a
88enumerateFromThenNum :: (Monad m, Num a) => Unfold m (a, a) a
@@ -108,18 +92,32 @@ enumerateFromThenNum = Unfold step inject
109 inject (!from, !next) = return (from, next - from, 0)
93 inject (!from, !next) = return (from, next - from, 0)
95+ -- Note that the counter "i" is the same type as the type being enumerated.
96+ -- It may overflow, for example, if we are enumerating Word8, after 255 the
97+ -- counter will become 0, but the overflow does not affect the enumeration
111 {-# INLINE_LATE step #-}
99 {-# INLINE_LATE step #-}
112 step (from, stride, i) =
100 step (from, stride, i) =
114 (Yield $! (from + i * stride)) $! (from, stride, i + 1)
102 (Yield $! (from + i * stride)) $! (from, stride, i + 1)
104+-- | Same as 'enumerateFromThenNum' using a stride of 1.
106+-- >>> enumerateFromNum = lmap (\from -> (from, from + 1)) enumerateFromThenNum
110+{-# INLINE enumerateFromNum #-}
111+enumerateFromNum :: (Monad m, Num a) => Unfold m a a
112+enumerateFromNum = lmap (\from -> (from, from + 1)) enumerateFromThenNum
116-- | Generate a finite stream starting from a from and next values with
114-- | Generate a finite stream starting from a from and next values with
117-- stride of (next-from) till to value. The implementation is numerically
115-- stride of (next-from) till to value. The implementation is numerically
118-- stable for floating point values.
116-- stable for floating point values.
120-- Note 'enumerateFromStepIntegral' is faster for integrals.
118-- Note 'enumerateFromStepIntegral' is faster for integrals.
122−-- /Pre-release/
120+-- /Internal/
124{-# INLINE enumerateFromThenToNumBounded #-}
122{-# INLINE enumerateFromThenToNumBounded #-}
125enumerateFromThenToNumBounded :: (Monad m, Ord a, Fractional a) =>
123enumerateFromThenToNumBounded :: (Monad m, Ord a, Fractional a) =>
@@ -151,7 +149,7 @@ enumerateFromThenToNumBounded = Unfold step inject
152-- Note 'enumerateFromStepIntegralBounded' is faster for integrals.
150-- Note 'enumerateFromStepIntegralBounded' is faster for integrals.
154−-- /Pre-release/
152+-- /Internal/
156{-# INLINE enumerateFromToNumBounded #-}
154{-# INLINE enumerateFromToNumBounded #-}
157enumerateFromToNumBounded :: (Monad m, Ord a, Fractional a) =>
155enumerateFromToNumBounded :: (Monad m, Ord a, Fractional a) =>
@@ -174,6 +172,8 @@ enumerateFromToNumBounded = Unfold step inject
175-- | Can be used to enumerate unbounded integrals. This does not check for
173-- | Can be used to enumerate unbounded integrals. This does not check for
176-- overflow or underflow for bounded integrals.
174-- overflow or underflow for bounded integrals.
177{-# INLINE_NORMAL enumerateFromStepIntegral #-}
177{-# INLINE_NORMAL enumerateFromStepIntegral #-}
178enumerateFromStepIntegral :: (Integral a, Monad m) => Unfold m (a, a) a
178enumerateFromStepIntegral :: (Integral a, Monad m) => Unfold m (a, a) a
179enumerateFromStepIntegral = Unfold step inject
179enumerateFromStepIntegral = Unfold step inject
@@ -185,7 +185,8 @@ enumerateFromStepIntegral = Unfold step inject
185-- | Can be used to enumerate bounded integrals from starting from with
185-- | Can be used to enumerate bounded integrals from starting from with
186-- stride of (next-from) . This check for overflow or underflow for
186-- stride of (next-from) . This check for overflow or underflow for
187-- bounded integrals.
187-- bounded integrals.
188−-- /Pre-release/
188+--
190{-# INLINE_NORMAL enumerateFromStepIntegralBounded #-}
191{-# INLINE_NORMAL enumerateFromStepIntegralBounded #-}
191enumerateFromStepIntegralBounded ::
192enumerateFromStepIntegralBounded ::
@@ -215,7 +216,8 @@ enumerateFromStepIntegralBounded = Unfold step inject
215-- | Can be used to enumerate bounded integrals from starting from with
216-- | Can be used to enumerate bounded integrals from starting from with
216-- stride of (next-from) till to value. This check for overflow or underflow
217-- stride of (next-from) till to value. This check for overflow or underflow
217-- for bounded integrals.
218-- for bounded integrals.
218−-- /Pre-release/
219+--
220{-# INLINE_NORMAL enumerateFromToStepIntegralBounded #-}
222{-# INLINE_NORMAL enumerateFromToStepIntegralBounded #-}
221enumerateFromToStepIntegralBounded ::
223enumerateFromToStepIntegralBounded ::
@@ -244,7 +246,8 @@ enumerateFromToStepIntegralBounded = Unfold step inject
245-- | Can be used to enumerate unbounded integrals. Startting with value from
247-- | Can be used to enumerate unbounded integrals. Startting with value from
246-- with stride of next-from till value of to.
248-- with stride of next-from till value of to.
247−-- /Pre-release/
249+--
249{-# INLINE_NORMAL enumerateFromToStepIntegral #-}
252{-# INLINE_NORMAL enumerateFromToStepIntegral #-}
250enumerateFromToStepIntegral :: (Integral a, Monad m) =>
253enumerateFromToStepIntegral :: (Integral a, Monad m) =>
@@ -335,6 +338,7 @@ enumerateFromThenToFractional = enumerateFromThenToNumBounded
335-------------------------------------------------------------------------------
338-------------------------------------------------------------------------------
336-- Enumerable type class
339-- Enumerable type class
337-------------------------------------------------------------------------------
340-------------------------------------------------------------------------------
338-- | Types that can be enumerated as a stream. The operations in this type
342-- | Types that can be enumerated as a stream. The operations in this type
339-- class are equivalent to those in the 'Enum' type class, except that these
343-- class are equivalent to those in the 'Enum' type class, except that these
340-- generate a stream instead of a list. Use the functions in
344-- generate a stream instead of a list. Use the functions in
@@ -343,98 +347,97 @@ enumerateFromThenToFractional = enumerateFromThenToNumBounded
343-- /Pre-release/
347-- /Pre-release/
344class Enum a => Enumerable a where
348class Enum a => Enumerable a where
346−-- @enumerateFrom from@ generates a stream starting with the element
350+ -- | Unfolds @from@ generating a stream starting with the element
347−-- @from@, enumerating up to 'maxBound' when the type is 'Bounded' or
351+ -- @from@, enumerating up to 'maxBound' when the type is 'Bounded' or
348−-- generating an infinite stream when the type is not 'Bounded'.
352+ -- generating an infinite stream when the type is not 'Bounded'.
351−-- >>> Stream.toList $ Stream.take 4 $ Stream.unfold Unfold.enumerateFrom (0 :: Int)
355+ -- >>> Stream.toList $ Stream.take 4 $ Stream.unfold Unfold.enumerateFrom (0 :: Int)
352−-- [0,1,2,3]
356+ -- [0,1,2,3]
356−-- For 'Fractional' types, enumeration is numerically stable. However, no
360+ -- For 'Fractional' types, enumeration is numerically stable. However, no
357−-- overflow or underflow checks are performed.
361+ -- overflow or underflow checks are performed.
360−-- >>> Stream.toList $ Stream.take 4 $ Stream.unfold Unfold.enumerateFrom 1.1
364+ -- >>> Stream.toList $ Stream.take 4 $ Stream.unfold Unfold.enumerateFrom 1.1
361−-- [1.1,2.1,3.1,4.1]
365+ -- [1.1,2.1,3.1,4.1]
365−-- /Pre-release/
369+ -- /Pre-release/
367 enumerateFrom :: Monad m => Unfold m a a
371 enumerateFrom :: Monad m => Unfold m a a
369−-- Generate a finite stream starting with the element @from@, enumerating
373+ -- | Unfolds @(from, to)@ generating a finite stream starting with the element
370−-- the type up to the value @to@. If @to@ is smaller than @from@ then an
374+ -- @from@, enumerating the type up to the value @to@. If @to@ is smaller than
371−-- empty stream is returned.
375+ -- @from@ then an empty stream is returned.
374−-- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromTo 4) 0
378+ -- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromTo 4) 0
375−-- [0,1,2,3,4]
379+ -- [0,1,2,3,4]
379−-- For 'Fractional' types, the last element is equal to the specified @to@
383+ -- For 'Fractional' types, the last element is equal to the specified @to@
380−-- value after rounding to the nearest integral value.
384+ -- value after rounding to the nearest integral value.
383−-- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromTo 4) 1.1
387+ -- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromTo 4) 1.1
384−-- [1.1,2.1,3.1,4.1]
388+ -- [1.1,2.1,3.1,4.1]
386−-- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromTo 4.6) 1.1
390+ -- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromTo 4.6) 1.1
387−-- [1.1,2.1,3.1,4.1,5.1]
391+ -- [1.1,2.1,3.1,4.1,5.1]
391−-- /Pre-release/
395+ -- /Pre-release/
392 enumerateFromTo :: Monad m => Unfold m (a, a) a
396 enumerateFromTo :: Monad m => Unfold m (a, a) a
394−-- @enumerateFromThen from then@ generates a stream whose first element
398+ -- | Unfolds @(from, then)@ generating a stream whose first element is
395−-- is @from@ and the successive elements are
399+ -- @from@ and the successive elements are in increments of @then@. Enumeration
396−-- in increments of @then@. Enumeration can occur downwards or
397−-- upwards depending on whether @then@ comes before or after @from@. For
400+ -- can occur downwards or upwards depending on whether @then@ comes before or
398−-- 'Bounded' types the stream ends when 'maxBound' is reached, for
401+ -- after @from@. For 'Bounded' types the stream ends when 'maxBound' is
399−-- unbounded types it keeps enumerating infinitely.
402+ -- reached, for unbounded types it keeps enumerating infinitely.
402−-- >>> Stream.toList $ Stream.take 4 $ Stream.unfold (Unfold.enumerateFromThen 2) 0
405+ -- >>> Stream.toList $ Stream.take 4 $ Stream.unfold (Unfold.enumerateFromThen 2) 0
403−-- [0,2,4,6]
406+ -- [0,2,4,6]
405−-- >>> Stream.toList $ Stream.take 4 $ Stream.unfold (Unfold.enumerateFromThen (-2)) 0
408+ -- >>> Stream.toList $ Stream.take 4 $ Stream.unfold (Unfold.enumerateFromThen (-2)) 0
406−-- [0,-2,-4,-6]
409+ -- [0,-2,-4,-6]
410−-- /Pre-release/
413+ -- /Pre-release/
411 enumerateFromThen :: Monad m => Unfold m (a, a) a
414 enumerateFromThen :: Monad m => Unfold m (a, a) a
413−-- @enumerateFromThenTo from then to@ generates a finite stream whose
416+ -- | Unfolds @(from, then, to)@ generating a finite stream whose first element
414−-- first element is @from@ and the successive elements are in
417+ -- is @from@ and the successive elements are in increments of @then@ up to
415−-- increments of @then@ up to @to@. Enumeration can
416−-- occur downwards or upwards depending on whether @then@ comes before or
418+ -- @to@. Enumeration can occur downwards or upwards depending on whether @then@
417−-- after @from@.
419+ -- comes before or after @from@.
420−-- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromThenTo 2 6) 0
422+ -- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromThenTo 2 6) 0
421−-- [0,2,4,6]
423+ -- [0,2,4,6]
423−-- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromThenTo (-2) (-6)) 0
425+ -- >>> Stream.toList $ Stream.unfold (Unfold.enumerateFromThenTo (-2) (-6)) 0
424−-- [0,-2,-4,-6]
426+ -- [0,-2,-4,-6]
428−-- /Pre-release/
430+ -- /Pre-release/
429 enumerateFromThenTo :: Monad m => Unfold m (a, a, a) a
431 enumerateFromThenTo :: Monad m => Unfold m (a, a, a) a
431-------------------------------------------------------------------------------
433-------------------------------------------------------------------------------
432-- Enumeration of Enum types not larger than Int
434-- Enumeration of Enum types not larger than Int
433-------------------------------------------------------------------------------
435-------------------------------------------------------------------------------
435−-- Enumerate from given starting Enum value 'from' with stride of 1 till
437+-- | Enumerate from given starting Enum value 'from' with stride of 1 till
436-- maxBound
438-- maxBound
437−-- /Pre-release/
439+--
439{-# INLINE enumerateFromSmall #-}
442{-# INLINE enumerateFromSmall #-}
440enumerateFromSmall :: forall a m. (Monad m, Bounded a, Enum a) => Unfold m a a
443enumerateFromSmall :: forall a m. (Monad m, Bounded a, Enum a) => Unfold m a a
@@ -448,9 +451,10 @@ enumerateFromSmall = map toEnum $
448 step (x, stride, to) = return $
451 step (x, stride, to) = return $
449 if x <= to then Yield x $! (x + stride, stride, to) else Stop
452 if x <= to then Yield x $! (x + stride, stride, to) else Stop
451−-- Enumerate from given starting Enum value 'from' and next Enum value 'next'
454+-- | Enumerate from given starting Enum value 'from' and next Enum value 'next'
452-- with stride of (fromEnum next - fromEnum from) till maxBound.
455-- with stride of (fromEnum next - fromEnum from) till maxBound.
453−-- /Pre-release/
456+--
455{-# INLINE enumerateFromThenSmall #-}
459{-# INLINE enumerateFromThenSmall #-}
456enumerateFromThenSmall :: forall a m. (Monad m, Bounded a, Enum a) =>
460enumerateFromThenSmall :: forall a m. (Monad m, Bounded a, Enum a) =>
@@ -483,9 +487,10 @@ enumerateFromThenSmall = map toEnum $
483 then Yield x $! (x + stride, stride, to)
487 then Yield x $! (x + stride, stride, to)
484 else Stop
488 else Stop
486−-- Enumerate from given starting Enum value 'from' and to Enum value 'to'
490+-- | Enumerate from given starting Enum value 'from' and to Enum value 'to'
487-- with stride of 1 till to value.
491-- with stride of 1 till to value.
488−-- /Pre-release/
492+--
490{-# INLINE enumerateFromToSmall #-}
495{-# INLINE enumerateFromToSmall #-}
491enumerateFromToSmall :: (Monad m, Enum a) => Unfold m (a, a) a
496enumerateFromToSmall :: (Monad m, Enum a) => Unfold m (a, a) a
@@ -500,10 +505,11 @@ enumerateFromToSmall = map toEnum $
500 step (x, stride, to) = return $
505 step (x, stride, to) = return $
501 if x <= to then Yield x $! (x + stride, stride, to) else Stop
506 if x <= to then Yield x $! (x + stride, stride, to) else Stop
503−-- Enumerate from given starting Enum value 'from' and then Enum value 'next'
508+-- | Enumerate from given starting Enum value 'from' and then Enum value 'next'
504-- and to Enum value 'to' with stride of (fromEnum next - fromEnum from)
509-- and to Enum value 'to' with stride of (fromEnum next - fromEnum from)
505-- till to value.
510-- till to value.
506−-- /Pre-release/
511+--
508{-# INLINE enumerateFromThenToSmall #-}
514{-# INLINE enumerateFromThenToSmall #-}
509enumerateFromThenToSmall :: (Monad m, Enum a) => Unfold m (a, a, a) a
515enumerateFromThenToSmall :: (Monad m, Enum a) => Unfold m (a, a, a) a