fabiommendes / elm-iter / Iter

Iterator interface inspired on Python's iterator protocol.

Important types


type Iter a b
    = It ({ state : b, next : Next a b })

Base iterator type


type alias Next a b =
b -> Maybe ( b, a )

A function that maybe compute the next element of an iterator


type alias Count a =
( Basics.Int, a )

A state with a auxiliary numeric counter

Iterator protocol

next : Iter a b -> Maybe a

Return Just the next value if iterator is not exausted or Nothing otherwise:

next numbers === Just 0

next empty === Nothing

step : Iter a b -> ( Iter a b, Maybe a )

Advance iterator by one and return a tuple of ( iterator, value ):

(it, _) = step numbers
next it === Just 1

iterator : Next a b -> b -> Iter a b

Create a new iterator from a next function and an initial state.

The next function is called successfuly to advance the iterator and produce new values

Creating new iterators

Numeric sequences

numbers : Iter number number

Infinite iterator over the sequence of all natural numbers

numbersFrom : number -> Iter number number

Infinite iterator over the sequence of all numbers starting with a with increments of 1.

numbersBy : number -> number -> Iter number number

Infinite iterator over the sequence of all numbers starting with a increments of delta.

countTo : Basics.Int -> Iter Basics.Int Basics.Int

Count from 0 to n:

countTo 5 --> 0, 1, 2, 3, 4, 5

range : number -> number -> Iter number number

Iterate from a to b (inclusive):

range 1 3 --> 1, 2, 3

linspace : Basics.Float -> Basics.Float -> Basics.Int -> Iter Basics.Float Basics.Float

Create n numbers from a to b:

linspace 0 5 5 --> 0.0, 1.25, 2.5, 3.75, 5.0

stepsFrom : number -> number -> number -> Iter number number

Make n steps of delta starting from a

stepsFrom 0 0.5 4 -->  0.0, 0.5, 1.0, 1.5

This function is the basis for implementing countTo, range and linspace.

Other iterators

repeat : a -> Iter a ()

Make infinite repetitions of a:

repeat "foo" -->  "foo", "foo", "foo", ...

repeatN : Basics.Int -> a -> Iter a Basics.Int

Make n repetitions of a:

repeatN 3 "foo" -->  "foo", "foo", "foo"

cycle : List a -> Iter a (List a)

Infinite iterator that cycles among members of input list:

cycle [ 1, 2, 3 ] -->  1, 2, 3, 1, 2, 3, 1, 2, ...

power : (a -> a) -> a -> Iter a a

Successively apply function to initial argument:

power f x -->  x, f x, f (f x), f (f (f x)), ...

powerN : Basics.Int -> (a -> a) -> a -> Iter a (Count a)

Successively apply function to initial argument. Repeat n times.

power 2 f x -->  x, f x, f(f x)

empty : Iter a b -> Iter a b

Empty (exausted) iterator:

next empty iter === Nothing

singleton : a -> Iter a (Maybe a)

Creates an iterator with a single value

singleton a -->  a

indexed : (Basics.Int -> a) -> Iter a Basics.Int

Construct iterator from index function that takes an integer and return the value of the corresponding position.

indexed f -->  f(0), f(1), f(2), ...

Transformations

Sub-iterators

filter : (a -> Basics.Bool) -> Iter a b -> Iter a b

Return an iterator that only yields elements that agree with predicate.

take : Basics.Int -> Iter a b -> Iter a (Count b)

Limit the iterator to n elements.

drop : Basics.Int -> Iter a b -> Iter a b

Drop the n first elements of iterator.

takeWithDefault : a -> Basics.Int -> Iter a b -> Iter a (Count b)

Limit the iterator to n elements. If the original iterator has less than n elements, fill the iterator with copies of a.

takeWhile : (a -> Basics.Bool) -> Iter a b -> Iter a b

Take elements of iterator while predicate is True.

Mapping

map : (a -> b) -> Iter a st -> Iter b st

Creates a new iterator that maps f into each element of the iterator.

map2 : (a -> b -> c) -> Iter a st -> Iter b st_ -> Iter c ( st, st_ )

Creates a new iterator that maps f successively into elements of iterA and iterB.

Zipping

zip : Iter a b -> Iter c d -> Iter ( a, c ) ( b, d )

Zip two iterators (i.e., iterate over the tuples of (a, b) taken from iterA and iterB respectively.

zip itA itB -->  ( a0, b0 ), ( a1, b1 ), ...

enumerate : Basics.Int -> Iter a b -> Iter (Count a) (Count b)

Enumerate iterator counting from a:

enumerate n it --> (n, x0), (n + 1, x1), (n + 2, x2), ...

Building iterators from sub-iterators

concat : Iter a b -> Iter a c -> Iter a (Toggle b c)

Concatenate two iterators together:

concat itA itB -->  a0, a1, ..., aN, b0, b1, ..., bN

intersperse : a -> Iter a b -> Iter a (Toggle b b)

Interspace each element of iterator with the value of x:

interspace a it --> x0, a, x1, a, x2, a, ..., xN

Conversion to/from lists and other data structures

toList : Iter a b -> List a

Extract list from iterator:

toList it  ===  [ x0, x1, x2, ..., xN ]

WARNING: This function should obviously never be used on infinite iterators.

fromList : List a -> Iter a (List a)

Convert list to iterator:

fromList [ a, b, c ] -->  a, b, c

Reductions and folds

reduce : (a -> b -> b) -> b -> Iter a s -> b

Reduce iterator using a left fold

accumulate : (a -> b -> b) -> b -> Iter a s -> Iter b ( s, b )

Accumulative reduce: return an iterator over partial reductions of the input iterator.

sum : Iter number a -> number

Sum all elements of iterator

all : (a -> Basics.Bool) -> Iter a b -> Basics.Bool

Return true if all elements of iterator satisfy the given predicate

any : (a -> Basics.Bool) -> Iter a b -> Basics.Bool

Return true if any element of iterator satisfy the given predicate

maximum : Iter comparable b -> Maybe comparable

Return Just the largest element of iterator or Nothing if iterator is empty.

minimum : Iter comparable b -> Maybe comparable

Return Just the lowest element of iterator or Nothing if iterator is empty.

Retrieving iterators

nth : Basics.Int -> Iter a b -> Maybe a

Return the n-th element of iterator.

last : Iter a b -> Maybe a

Return the last element of iterator.

lastWithDefault : a -> Iter a b -> a

Return the last element of or x if iterator is empty.