2-- Module : Streamly.Internal.Data.Stream.Enumeration
3-- Copyright : (c) 2018 Composewell Technologies
6-- Maintainer : streamly@composewell.com
7-- Stability : experimental
10-- The functions defined in this module should be rarely needed for direct use,
11-- try to use the operations from the 'Enumerable' type class
14-- This module provides an 'Enumerable' type class to enumerate 'Enum' types
15-- into a stream. The operations in this type class correspond to similar
16-- perations in the 'Enum' type class, the only difference is that they produce
17-- a stream instead of a list. These operations cannot be defined generically
18-- based on the 'Enum' type class. We provide instances for commonly used
19-- types. If instances for other types are needed convenience functions defined
20-- in this module can be used to define them. Alternatively, these functions
21-- can be used directly.
23module Streamly.Internal.Data.Stream.IsStream.Enumeration
27 -- ** Enumerating 'Bounded' 'Enum' Types
30 , enumerateFromBounded
32 -- ** Enumerating 'Enum' Types not larger than 'Int'
33 , enumerateFromToSmall
34 , enumerateFromThenToSmall
35 , enumerateFromThenSmallBounded
37 -- ** Enumerating 'Bounded' 'Integral' Types
38 , enumerateFromIntegral
39 , enumerateFromThenIntegral
41 -- ** Enumerating 'Integral' Types
42 , enumerateFromToIntegral
43 , enumerateFromThenToIntegral
45 -- ** Enumerating unbounded 'Integral' Types
46 , enumerateFromStepIntegral
48 -- ** Enumerating 'Fractional' Types
49 , enumerateFromFractional
50 , enumerateFromToFractional
51 , enumerateFromThenFractional
52 , enumerateFromThenToFractional
61import Data.Functor.Identity (Identity(..))
63import Streamly.Internal.Data.Stream.IsStream.Type (IsStream(..), fromStreamD)
65import qualified Streamly.Internal.Data.Stream.IsStream.Type as IsStream
66import qualified Streamly.Internal.Data.Stream.StreamD.Generate as D
67import qualified Streamly.Internal.Data.Stream.Serial as Serial (map)
70-- >>> import Streamly.Prelude as Stream
71-- >>> import Streamly.Internal.Data.Stream.IsStream.Enumeration as Stream
73-------------------------------------------------------------------------------
74-- Enumeration of Integral types
75-------------------------------------------------------------------------------
77-- | @enumerateFromStepIntegral from step@ generates an infinite stream whose
78-- first element is @from@ and the successive elements are in increments of
81-- CAUTION: This function is not safe for finite integral types. It does not
82-- check for overflow, underflow or bounds.
85-- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFromStepIntegral 0 2
88-- >>> Stream.toList $ Stream.take 3 $ Stream.enumerateFromStepIntegral 0 (-2)
94{-# INLINE enumerateFromStepIntegral #-}
95enumerateFromStepIntegral
96 :: (IsStream t, Monad m, Integral a)
98enumerateFromStepIntegral from stride =
99 fromStreamD $ D.enumerateFromStepIntegral from stride
101-- | Enumerate an 'Integral' type. @enumerateFromIntegral from@ generates a
102-- stream whose first element is @from@ and the successive elements are in
103-- increments of @1@. The stream is bounded by the size of the 'Integral' type.
106-- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFromIntegral (0 :: Int)
112{-# INLINE enumerateFromIntegral #-}
114 :: (IsStream t, Monad m, Integral a, Bounded a)
116enumerateFromIntegral from = fromStreamD $ D.enumerateFromIntegral from
118-- | Enumerate an 'Integral' type in steps. @enumerateFromThenIntegral from
119-- then@ generates a stream whose first element is @from@, the second element
120-- is @then@ and the successive elements are in increments of @then - from@.
121-- The stream is bounded by the size of the 'Integral' type.
124-- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFromThenIntegral (0 :: Int) 2
127-- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFromThenIntegral (0 :: Int) (-2)
133{-# INLINE enumerateFromThenIntegral #-}
134enumerateFromThenIntegral
135 :: (IsStream t, Monad m, Integral a, Bounded a)
137enumerateFromThenIntegral from next =
138 fromStreamD $ D.enumerateFromThenIntegral from next
140-- | Enumerate an 'Integral' type up to a given limit.
141-- @enumerateFromToIntegral from to@ generates a finite stream whose first
142-- element is @from@ and successive elements are in increments of @1@ up to
146-- >>> Stream.toList $ Stream.enumerateFromToIntegral 0 4
152{-# INLINE enumerateFromToIntegral #-}
153enumerateFromToIntegral :: (IsStream t, Monad m, Integral a) => a -> a -> t m a
154enumerateFromToIntegral from to =
155 fromStreamD $ D.enumerateFromToIntegral from to
157-- | Enumerate an 'Integral' type in steps up to a given limit.
158-- @enumerateFromThenToIntegral from then to@ generates a finite stream whose
159-- first element is @from@, the second element is @then@ and the successive
160-- elements are in increments of @then - from@ up to @to@.
163-- >>> Stream.toList $ Stream.enumerateFromThenToIntegral 0 2 6
166-- >>> Stream.toList $ Stream.enumerateFromThenToIntegral 0 (-2) (-6)
172{-# INLINE enumerateFromThenToIntegral #-}
173enumerateFromThenToIntegral
174 :: (IsStream t, Monad m, Integral a)
175 => a -> a -> a -> t m a
176enumerateFromThenToIntegral from next to =
177 fromStreamD $ D.enumerateFromThenToIntegral from next to
179-------------------------------------------------------------------------------
180-- Enumeration of Fractional types
181-------------------------------------------------------------------------------
183-- Even though the underlying implementation of enumerateFromFractional and
184-- enumerateFromThenFractional works for any 'Num' we have restricted these to
185-- 'Fractional' because these do not perform any bounds check, in contrast to
186-- integral versions and are therefore not equivalent substitutes for those.
188-- | Numerically stable enumeration from a 'Fractional' number in steps of size
189-- @1@. @enumerateFromFractional from@ generates a stream whose first element
190-- is @from@ and the successive elements are in increments of @1@. No overflow
191-- or underflow checks are performed.
193-- This is the equivalent to 'enumFrom' for 'Fractional' types. For example:
196-- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFromFractional 1.1
203{-# INLINE enumerateFromFractional #-}
204enumerateFromFractional :: (IsStream t, Monad m, Fractional a) => a -> t m a
205enumerateFromFractional from = fromStreamD $ D.enumerateFromNum from
207-- | Numerically stable enumeration from a 'Fractional' number in steps.
208-- @enumerateFromThenFractional from then@ generates a stream whose first
209-- element is @from@, the second element is @then@ and the successive elements
210-- are in increments of @then - from@. No overflow or underflow checks are
213-- This is the equivalent of 'enumFromThen' for 'Fractional' types. For
217-- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFromThenFractional 1.1 2.1
220-- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFromThenFractional 1.1 (-2.1)
221-- [1.1,-2.1,-5.300000000000001,-8.500000000000002]
226{-# INLINE enumerateFromThenFractional #-}
227enumerateFromThenFractional
228 :: (IsStream t, Monad m, Fractional a)
230enumerateFromThenFractional from next = fromStreamD $ D.enumerateFromThenNum from next
232-- | Numerically stable enumeration from a 'Fractional' number to a given
233-- limit. @enumerateFromToFractional from to@ generates a finite stream whose
234-- first element is @from@ and successive elements are in increments of @1@ up
237-- This is the equivalent of 'enumFromTo' for 'Fractional' types. For
241-- >>> Stream.toList $ Stream.enumerateFromToFractional 1.1 4
244-- >>> Stream.toList $ Stream.enumerateFromToFractional 1.1 4.6
245-- [1.1,2.1,3.1,4.1,5.1]
249-- Notice that the last element is equal to the specified @to@ value after
250-- rounding to the nearest integer.
253{-# INLINE enumerateFromToFractional #-}
254enumerateFromToFractional
255 :: (IsStream t, Monad m, Fractional a, Ord a)
257enumerateFromToFractional from to =
258 fromStreamD $ D.enumerateFromToFractional from to
260-- | Numerically stable enumeration from a 'Fractional' number in steps up to a
261-- given limit. @enumerateFromThenToFractional from then to@ generates a
262-- finite stream whose first element is @from@, the second element is @then@
263-- and the successive elements are in increments of @then - from@ up to @to@.
265-- This is the equivalent of 'enumFromThenTo' for 'Fractional' types. For
269-- >>> Stream.toList $ Stream.enumerateFromThenToFractional 0.1 2 6
270-- [0.1,2.0,3.9,5.799999999999999]
272-- >>> Stream.toList $ Stream.enumerateFromThenToFractional 0.1 (-2) (-6)
273-- [0.1,-2.0,-4.1000000000000005,-6.200000000000001]
279{-# INLINE enumerateFromThenToFractional #-}
280enumerateFromThenToFractional
281 :: (IsStream t, Monad m, Fractional a, Ord a)
282 => a -> a -> a -> t m a
283enumerateFromThenToFractional from next to =
284 fromStreamD $ D.enumerateFromThenToFractional from next to
286-------------------------------------------------------------------------------
287-- Enumeration of Enum types not larger than Int
288-------------------------------------------------------------------------------
290-- | 'enumerateFromTo' for 'Enum' types not larger than 'Int'.
293{-# INLINE enumerateFromToSmall #-}
294enumerateFromToSmall :: (IsStream t, Monad m, Enum a) => a -> a -> t m a
295enumerateFromToSmall from to =
298 $ enumerateFromToIntegral (fromEnum from) (fromEnum to)
300-- | 'enumerateFromThenTo' for 'Enum' types not larger than 'Int'.
303{-# INLINE enumerateFromThenToSmall #-}
304enumerateFromThenToSmall :: (IsStream t, Monad m, Enum a)
305 => a -> a -> a -> t m a
306enumerateFromThenToSmall from next to =
309 $ enumerateFromThenToIntegral
310 (fromEnum from) (fromEnum next) (fromEnum to)
312-- | 'enumerateFromThen' for 'Enum' types not larger than 'Int'.
314-- Note: We convert the 'Enum' to 'Int' and enumerate the 'Int'. If a
315-- type is bounded but does not have a 'Bounded' instance then we can go on
316-- enumerating it beyond the legal values of the type, resulting in the failure
317-- of 'toEnum' when converting back to 'Enum'. Therefore we require a 'Bounded'
318-- instance for this function to be safely used.
321{-# INLINE enumerateFromThenSmallBounded #-}
322enumerateFromThenSmallBounded :: (IsStream t, Monad m, Enumerable a, Bounded a)
324enumerateFromThenSmallBounded from next =
325 if fromEnum next >= fromEnum from
326 then enumerateFromThenTo from next maxBound
327 else enumerateFromThenTo from next minBound
329-------------------------------------------------------------------------------
330-- Enumerable type class
331-------------------------------------------------------------------------------
333-- NOTE: We would like to rewrite calls to fromList [1..] etc. to stream
334-- enumerations like this:
336-- {-# RULES "fromList enumFrom" [1]
337-- forall (a :: Int). D.fromList (enumFrom a) = D.enumerateFromIntegral a #-}
339-- But this does not work because enumFrom is a class method and GHC rewrites
340-- it quickly, so we do not get a chance to have our rule fired.
342-- | Types that can be enumerated as a stream. The operations in this type
343-- class are equivalent to those in the 'Enum' type class, except that these
344-- generate a stream instead of a list. Use the functions in
345-- "Streamly.Internal.Data.Stream.Enumeration" module to define new instances.
348class Enum a => Enumerable a where
349 -- | @enumerateFrom from@ generates a stream starting with the element
350 -- @from@, enumerating up to 'maxBound' when the type is 'Bounded' or
351 -- generating an infinite stream when the type is not 'Bounded'.
354 -- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFrom (0 :: Int)
359 -- For 'Fractional' types, enumeration is numerically stable. However, no
360 -- overflow or underflow checks are performed.
363 -- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFrom 1.1
369 enumerateFrom :: (IsStream t, Monad m) => a -> t m a
371 -- | Generate a finite stream starting with the element @from@, enumerating
372 -- the type up to the value @to@. If @to@ is smaller than @from@ then an
373 -- empty stream is returned.
376 -- >>> Stream.toList $ Stream.enumerateFromTo 0 4
381 -- For 'Fractional' types, the last element is equal to the specified @to@
382 -- value after rounding to the nearest integral value.
385 -- >>> Stream.toList $ Stream.enumerateFromTo 1.1 4
388 -- >>> Stream.toList $ Stream.enumerateFromTo 1.1 4.6
389 -- [1.1,2.1,3.1,4.1,5.1]
394 enumerateFromTo :: (IsStream t, Monad m) => a -> a -> t m a
396 -- | @enumerateFromThen from then@ generates a stream whose first element
397 -- is @from@, the second element is @then@ and the successive elements are
398 -- in increments of @then - from@. Enumeration can occur downwards or
399 -- upwards depending on whether @then@ comes before or after @from@. For
400 -- 'Bounded' types the stream ends when 'maxBound' is reached, for
401 -- unbounded types it keeps enumerating infinitely.
404 -- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFromThen 0 2
407 -- >>> Stream.toList $ Stream.take 4 $ Stream.enumerateFromThen 0 (-2)
413 enumerateFromThen :: (IsStream t, Monad m) => a -> a -> t m a
415 -- | @enumerateFromThenTo from then to@ generates a finite stream whose
416 -- first element is @from@, the second element is @then@ and the successive
417 -- elements are in increments of @then - from@ up to @to@. Enumeration can
418 -- occur downwards or upwards depending on whether @then@ comes before or
422 -- >>> Stream.toList $ Stream.enumerateFromThenTo 0 2 6
425 -- >>> Stream.toList $ Stream.enumerateFromThenTo 0 (-2) (-6)
431 enumerateFromThenTo :: (IsStream t, Monad m) => a -> a -> a -> t m a
433-- MAYBE: Sometimes it is more convenient to know the count rather then the
434-- ending or starting element. For those cases we can define the folllowing
435-- APIs. All of these will work only for bounded types if we represent the
444-------------------------------------------------------------------------------
445-- Convenient functions for bounded types
446-------------------------------------------------------------------------------
449-- > enumerate = enumerateFrom minBound
451-- Enumerate a 'Bounded' type from its 'minBound' to 'maxBound'
454{-# INLINE enumerate #-}
455enumerate :: (IsStream t, Monad m, Bounded a, Enumerable a) => t m a
456enumerate = enumerateFrom minBound
459-- > enumerateTo = enumerateFromTo minBound
461-- Enumerate a 'Bounded' type from its 'minBound' to specified value.
464{-# INLINE enumerateTo #-}
465enumerateTo :: (IsStream t, Monad m, Bounded a, Enumerable a) => a -> t m a
466enumerateTo = enumerateFromTo minBound
469-- > enumerateFromBounded = enumerateFromTo from maxBound
471-- 'enumerateFrom' for 'Bounded' 'Enum' types.
474{-# INLINE enumerateFromBounded #-}
475enumerateFromBounded :: (IsStream t, Monad m, Enumerable a, Bounded a)
477enumerateFromBounded from = enumerateFromTo from maxBound
479-------------------------------------------------------------------------------
480-- Enumerable Instances
481-------------------------------------------------------------------------------
483-- For Enum types smaller than or equal to Int size.
484#define ENUMERABLE_BOUNDED_SMALL(SMALL_TYPE) \
485instance Enumerable SMALL_TYPE where { \
486 {-# INLINE enumerateFrom #-}; \
487 enumerateFrom = enumerateFromBounded; \
488 {-# INLINE enumerateFromThen #-}; \
489 enumerateFromThen = enumerateFromThenSmallBounded; \
490 {-# INLINE enumerateFromTo #-}; \
491 enumerateFromTo = enumerateFromToSmall; \
492 {-# INLINE enumerateFromThenTo #-}; \
493 enumerateFromThenTo = enumerateFromThenToSmall }
496ENUMERABLE_BOUNDED_SMALL(())
497ENUMERABLE_BOUNDED_SMALL(Bool)
498ENUMERABLE_BOUNDED_SMALL(Ordering)
499ENUMERABLE_BOUNDED_SMALL(Char)
501-- For bounded Integral Enum types, may be larger than Int.
502#define ENUMERABLE_BOUNDED_INTEGRAL(INTEGRAL_TYPE) \
503instance Enumerable INTEGRAL_TYPE where { \
504 {-# INLINE enumerateFrom #-}; \
505 enumerateFrom = enumerateFromIntegral; \
506 {-# INLINE enumerateFromThen #-}; \
507 enumerateFromThen = enumerateFromThenIntegral; \
508 {-# INLINE enumerateFromTo #-}; \
509 enumerateFromTo = enumerateFromToIntegral; \
510 {-# INLINE enumerateFromThenTo #-}; \
511 enumerateFromThenTo = enumerateFromThenToIntegral }
513ENUMERABLE_BOUNDED_INTEGRAL(Int)
514ENUMERABLE_BOUNDED_INTEGRAL(Int8)
515ENUMERABLE_BOUNDED_INTEGRAL(Int16)
516ENUMERABLE_BOUNDED_INTEGRAL(Int32)
517ENUMERABLE_BOUNDED_INTEGRAL(Int64)
518ENUMERABLE_BOUNDED_INTEGRAL(Word)
519ENUMERABLE_BOUNDED_INTEGRAL(Word8)
520ENUMERABLE_BOUNDED_INTEGRAL(Word16)
521ENUMERABLE_BOUNDED_INTEGRAL(Word32)
522ENUMERABLE_BOUNDED_INTEGRAL(Word64)
524-- For unbounded Integral Enum types.
525#define ENUMERABLE_UNBOUNDED_INTEGRAL(INTEGRAL_TYPE) \
526instance Enumerable INTEGRAL_TYPE where { \
527 {-# INLINE enumerateFrom #-}; \
528 enumerateFrom from = enumerateFromStepIntegral from 1; \
529 {-# INLINE enumerateFromThen #-}; \
530 enumerateFromThen from next = \
531 enumerateFromStepIntegral from (next - from); \
532 {-# INLINE enumerateFromTo #-}; \
533 enumerateFromTo = enumerateFromToIntegral; \
534 {-# INLINE enumerateFromThenTo #-}; \
535 enumerateFromThenTo = enumerateFromThenToIntegral }
537ENUMERABLE_UNBOUNDED_INTEGRAL(Integer)
538ENUMERABLE_UNBOUNDED_INTEGRAL(Natural)
540#define ENUMERABLE_FRACTIONAL(FRACTIONAL_TYPE,CONSTRAINT) \
541instance (CONSTRAINT) => Enumerable FRACTIONAL_TYPE where { \
542 {-# INLINE enumerateFrom #-}; \
543 enumerateFrom = enumerateFromFractional; \
544 {-# INLINE enumerateFromThen #-}; \
545 enumerateFromThen = enumerateFromThenFractional; \
546 {-# INLINE enumerateFromTo #-}; \
547 enumerateFromTo = enumerateFromToFractional; \
548 {-# INLINE enumerateFromThenTo #-}; \
549 enumerateFromThenTo = enumerateFromThenToFractional }
551ENUMERABLE_FRACTIONAL(Float,)
552ENUMERABLE_FRACTIONAL(Double,)
553ENUMERABLE_FRACTIONAL((Fixed a),HasResolution a)
554ENUMERABLE_FRACTIONAL((Ratio a),Integral a)
556instance Enumerable a => Enumerable (Identity a) where
557 {-# INLINE enumerateFrom #-}
558 enumerateFrom (Identity from) =
559 IsStream.fromSerial $ Serial.map Identity $ enumerateFrom from
560 {-# INLINE enumerateFromThen #-}
561 enumerateFromThen (Identity from) (Identity next) =
562 IsStream.fromSerial $ Serial.map Identity $ enumerateFromThen from next
563 {-# INLINE enumerateFromTo #-}
564 enumerateFromTo (Identity from) (Identity to) =
565 IsStream.fromSerial $ Serial.map Identity $ enumerateFromTo from to
566 {-# INLINE enumerateFromThenTo #-}
567 enumerateFromThenTo (Identity from) (Identity next) (Identity to) =
569 $ Serial.map Identity
570 $ enumerateFromThenTo from next to
574instance Enumerable a => Enumerable (Last a)
575instance Enumerable a => Enumerable (First a)
576instance Enumerable a => Enumerable (Max a)
577instance Enumerable a => Enumerable (Min a)
578instance Enumerable a => Enumerable (Const a b)
579instance Enumerable (f a) => Enumerable (Alt f a)
580instance Enumerable (f a) => Enumerable (Ap f a)
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list