Module llists

A lazily evaluated lists module.

Description

A lazily evaluated lists module. This module provides an iterator type which is an opaque record wrapped around a list continuation. These iterators are then used to provide a version of the stdlib lists functions which only evaluate elements of the iterator when demanded.

Several simple iterator constructors are provided as well as a general purpose unfold/2 constructor. Conversion to built in types for lists and maps as the from_list/1, to_list/1, from_map/1 and to_map/1 functions.

Iterators are evaluated using the next/1 function to evaluate the next element of the iterator. The output of the next function is a lazy list: either an improper list of the element and the continuation or an empty list. Many additional iterator transformation and evaluation functions are also present.

In general, iterators are not expected to be pure functions. Iterator transformations and evaluations should all evaluate each element exactly once per output iterator (though not all elements may be returned, depending on the function). This implies that impure iterators should not be used with functions which return multiple iterators if all iterators are to be evaluated.

Many of the functions here are unsafe to use with infinite iterators and will either fail to return on the initial call or on the first attempt to evaluate an element of the iterator. Read the documentation carefully when working with such iterators.

The interface for this module attempts to follow the lists behaviour as closely as possible. Guidelines for how past and future translation is performed is as follows:

As few functions outside of lists have been implemented as possible in order to have the best chance of keeping the namespace clean for future additions to the lists module. New functionality is instead implemented in the llists_utils module.

Data Types

accumulator()

accumulator() = any()

combine()

combine(A, B, Out) = fun((A, B) -> Out)

combine3()

combine3(A, B, C, Out) = fun((A, B, C) -> Out)

compare()

compare(A, B) = fun((A, B) -> boolean())

filtermap()

filtermap(A, B) = fun((A) -> boolean() | {true, B})

fold()

fold(Elem, AccIn, AccOut) = fun((Elem, AccIn) -> AccOut)

iterator()

abstract datatype: iterator(Over)

iterator()

iterator() = iterator(any())

lazy_list()

lazy_list(Over) = nonempty_improper_list(Over, iterator(Over)) | []

map()

map(A, B) = fun((A) -> B)

mapfold()

mapfold(A, AccIn, B, AccOut) = fun((A, AccIn) -> {B, AccOut})

predicate()

predicate(Elem) = fun((Elem) -> boolean())

tuple_iterator()

tuple_iterator() = iterator(tuple())

unfold()

unfold(Elem, AccIn, AccOut) = fun((AccIn) -> {Elem, AccOut} | none)

uniq()

uniq(Elem) = fun((Elem) -> any())

Function Index

all/2 Returns true if Pred(Elem) returns true for all elements Elem in Iterator.
any/2 Returns true if Pred(Elem) returns true for at least one element Elem in Iterator.
append/1 Returns an iterator in which all the subiterators of IteratorOfIterators have been appended.
append/2 Returns a new iterator Iterator3, which is made from the elements of Iterator1 followed by the elements of Iterator2.
concat/1 Concatenates the text representation of the elements of Iterator.
delete/2 Returns a copy of Iterator1 where the first element matching Elem is deleted, if there is such an element.
droplast/1 Drops the last element of a Iterator1.
dropwhile/2 Drops elements Elem from Iterator1 while Pred(Elem) returns true and returns the remaining iterator.
duplicate/2 Returns an iterator containing N copies of term Elem.
enumerate/1 Returns elements of Iterator1 with each element H replaced by a tuple of form {I, H} where I is the position of H in Iterator1.
enumerate/2 Returns elements of Iterator1 with each element H replaced by a tuple of form {I, H} where I is the position of H in Iterator1.
filter/2 Filtered is an iterator of all elements Elem in Iterator1 for which Pred(Elem) returns true.
filtermap/2 Calls Fun(Elem) on successive elements Elem of Iterator1.
flatlength/1 Equivalent to length(flatten(DeepIterator)).
flatmap/2 Takes a function from As to iterators of Bs, and an iterator of As (Iterator1) and produces an iterator of Bs (Iterator2) by applying the function to every element in Iterator1 and appending the resulting iterators.
flatten/1 Returns a flattened version of DeepIterator.
flatten/2 Returns a flattened version of DeepIterator with tail Tail appended.
foldl/3 Calls Fun(Elem, AccIn) on successive elements A of Iterator, starting with AccIn == Acc0.
foldr/3 Like foldl/3, but the list is traversed from right to left.
foreach/2 Calls Fun(Elem) for each element Elem in Iterator.
from_list/1 Construct a new iterator from an existing list.
from_map/1 Construct a new iterator from an existing map.
hd/1 Returns the head of Iterator, that is, the first element, for example:.
is_iterator/1 Tests if the given Candidate is an iterator, returns true if it and false otherwise.
join/2 Inserts Sep between each element in Iterator1.
keydelete/3 Returns a copy of TupleIterator1 where the first occurrence of a tuple whose Nth element compares equal to Key is deleted, if there is such a tuple.
keyfind/3 Searches the iterator of tuples TupleIterator for a tuple whose Nth element compares equal to Key.
keymap/3 Returns an iterator of tuples where, for each tuple in TupleIterator1, the Nth element Term1 of the tuple has been replaced with the result of calling Fun(Term1).
keymember/3 Returns true if there is a tuple in TupleIterator whose Nth element compares equal to Key, otherwise false.
keymerge/3 Returns the sorted iterator formed by merging TupleIterator1 and TupleIterator2.
keyreplace/4 Returns a copy of TupleIterator1 where the first occurrence of a T tuple whose Nth element compares equal to Key is replaced with NewTuple, if there is such a tuple T.
keysearch/3 Searches the iterator of tuples TupleIterator for a tuple whose Nth element compares equal to Key.
keysort/2 Returns an iterator containing the sorted elements of iterator TupleIterator1.
keystore/4 Returns a copy of TupleIterator1 where the first occurrence of a tuple T whose Nth element compares equal to Key is replaced with NewTuple, if there is such a tuple T.
keytake/3 Searches the iterator of tuples TupleIterator1 for a tuple whose Nth element compares equal to Key.
last/1 Returns the last element in Iterator.
length/1 Returns the length of Iterator, for example:.
map/2 Takes a function Fun from As to Bs, and an Iterator1 of As and produces an Iterator2 of Bs by applying the function to every element in the iterator.
mapfoldl/3 Combines the operations of map/2 and foldl/3 into one pass.
mapfoldr/3 Combines the operations of map/2 and foldr/3 into one pass.
max/1 Returns the first element of Iterator that compares greater than or equal to all other elements of Iterator.
member/2 Returns true if Elem matches some element of Iterator, otherwise false.
merge/1 Returns the sorted iterator formed by merging all the subiterators of IteratorOfIterators.
merge/2 Returns the sorted iterator formed by merging Iterator1 and Iterator2.
merge/3 Returns the sorted iterator formed by merging Iterator1 and Iterator2.
merge3/3 Returns the sorted iterator formed by merging Iterator1, Iterator2, and Iterator3.
min/1 Returns the first element of Iterator that compares less than or equal to all other elements of Iterator.
next/1 Demand an element from Iterator.
nth/2 Returns the Nth element of Iterator.
nthtail/2 Returns the Nth tail of Iterator1, that is, the subiterator of Iterator1 starting at N+1 and continuing up to the end of the iterator.
partition/2 Partitions Iterator1 into two iterators, where the first iterator contains all elements for which Pred(Elem) returns true, and the second iterator contains all elements for which Pred(Elem) returns false.
prefix/2 Returns true if Iterator1 is a prefix of Iterator2, otherwise false.
reverse/1 Returns an iterator with the elements in Iterator1 in reverse order.
reverse/2 Returns a list with the elements in Iterator1 in reverse order, with tail TailIterator appended.
search/2 If there is a Value in Iterator such that Pred(Value) returns true, returns {value, Value} for the first such Value, otherwise returns false.
seq/2
seq/3 Returns an iterator over a sequence of integers that starts with From and contains the successive results of adding Incr to the previous element, until To is reached or passed (in the latter case, To is not an element of the sequence).
sort/1 Returns an iterator containing the sorted elements of Iterator1.
sort/2 Returns an iterator containing the sorted elements of Iterator1, according to the ordering function Fun.
split/2 Splits Iterator1 into Iterator2 and Iterator3.
splitwith/2 Partitions Iterator1 into two iterators according to Pred.
sublist/2
sublist/3 Returns the portion of Iterator1 starting at Start and with (maximum) Len elements.
subtract/2 Returns a new iterator Iterator3 that is a copy of Iterator1, subjected to the following procedure: for each element in Iterator2, its first occurrence in Iterator1 is deleted.
suffix/2 Returns true if Iterator1 is a suffix of Iterator2, otherwise false.
sum/1 Returns the sum of the elements in Iterator.
takewhile/2 Takes elements Elem from Iterator1 while Pred(Elem) returns true, that is, the function returns the longest prefix of the iterator for which all elements satisfy the predicate.
tl/1 Returns the tail of Iterator1, that is, the iterator minus the first element, for example:.
to_list/1 Fully evaluate Iterator and return a list containing all elements produced.
to_map/1 Fully evaluate an Iterator of {Key, Value} tuples and return a map containing all pairs produced.
ukeymerge/3 Returns the sorted iterator formed by merging TupleIterator1 and TupleIterator2.
ukeysort/2 Returns a iterator containing the sorted elements of iterator TupleIterator1 where all except the first tuple of the tuples comparing equal have been deleted.
umerge/1 Returns the sorted iterator formed by merging all the subiterators of IteratorOfIterators.
umerge/2 Returns the sorted iterator formed by merging Iterator1 and Iterator2.
umerge/3 Returns the sorted iterator formed by merging Iterator1 and Iterator2.
umerge3/3 Returns the sorted iterator formed by merging Iterator1, Iterator2, and Iterator3.
unfold/2 Construct a new iterator from a Fun(AccIn) function and an initial accumulator value Acc0.
uniq/1 Returns an iterator containing the elements of Iterator1 with duplicated elements removed (preserving the order of the elements).
uniq/2 Returns an iterator containing the elements of Iterator1 without the elements for which Fun returned duplicate values (preserving the order of the elements).
unzip/1 "Unzips" a iterator of two-tuples into two iterators, where the first iterator contains the first element of each tuple, and the second iterator contains the second element of each tuple.
unzip3/1 "Unzips" a iterator of three-tuples into three iterators, where the first iterator contains the first element of each tuple, the second iterator contains the second element of each tuple, and the third iterator contains the third element of each tuple.
usort/1 Returns a iterator containing the sorted elements of Iterator1 where all except the first element of the elements comparing equal have been deleted.
usort/2 Returns a iterator containing the sorted elements of Iterator1 where all except the first element of the elements comparing equal according to the ordering function Fun have been deleted.
zip/2 "Zips" two iterators of equal length into one iterator of two-tuples, where the first element of each tuple is taken from the first iterator and the second element is taken from the corresponding element in the second iterator.
zip3/3 "Zips" three iterators of equal length into one iterator of three-tuples, where the first element of each tuple is taken from the first iterator, the second element is taken from the corresponding element in the second iterator, and the third element is taken from the corresponding element in the third iterator.
zipwith/3 Combines the elements of two iterators of equal length into one iterator.
zipwith3/4 Combines the elements of three iterators of equal length into one iterator.

Function Details

all/2

all(Pred, Iterator) -> boolean()

Returns true if Pred(Elem) returns true for all elements Elem in Iterator.

Stops evaluating Iterator when Pred(Elem) returns false or when Iterator is empty.

any/2

any(Pred, Iterator) -> boolean()

Returns true if Pred(Elem) returns true for at least one element Elem in Iterator.

Stops evaluating Iterator when Pred(Elem) returns true or when Iterator is empty.

append/1

append(IteratorOfIterators) -> Iterator

Returns an iterator in which all the subiterators of IteratorOfIterators have been appended.

append/2

append(Iterator1, Iterator2) -> Iterator3

Returns a new iterator Iterator3, which is made from the elements of Iterator1 followed by the elements of Iterator2.

concat/1

concat(Iterator) -> string()

Concatenates the text representation of the elements of Iterator. The elements of Iterator can be atoms, integers, floats, or strings. The iterator will be fully evaluated, infinite iterators will never return.

delete/2

delete(Elem1, Iterator1) -> Iterator2

Returns a copy of Iterator1 where the first element matching Elem is deleted, if there is such an element.

droplast/1

droplast(Iterator1) -> Iterator2

Drops the last element of a Iterator1. The Iterator1 is to be non-empty, otherwise the function crashes with a function_clause.

Evaluates one element further in the iterator than the current value.

dropwhile/2

dropwhile(Pred, Iterator1) -> Iterator2

Drops elements Elem from Iterator1 while Pred(Elem) returns true and returns the remaining iterator.

duplicate/2

duplicate(N, Elem) -> Iterator

Returns an iterator containing N copies of term Elem. If N is infinity iterator will return infinite copies of Elem.

enumerate/1

enumerate(Iterator1) -> Iterator2

Returns elements of Iterator1 with each element H replaced by a tuple of form {I, H} where I is the position of H in Iterator1. The enumeration starts with 1 and increases by 1 in each step.

That is, enumerate/1 behaves as if it had been defined as follows, except that the iterator is not fully evaluated before elements are returned:

  enumerate(Iterator1) ->
    {Iterator2, _ } = llists:mapfoldl(fun(T, Acc) -> {{Acc, T}, Acc+1} end, 1, Iterator1),
    Iterator2.
  ```
 
  Example:
  ```
  > llists:to_list(
       llists:enumerate(
           llists:from_list([one, two, three]))).
  [{1,one},{2,two},{3,three}]

enumerate/2

enumerate(Index, Iterator1) -> Iterator2

Returns elements of Iterator1 with each element H replaced by a tuple of form {I, H} where I is the position of H in Iterator1. The enumeration starts with Index and increases by 1 in each step.

That is, enumerate/1 behaves as if it had been defined as follows, except that the iterator is not fully evaluated before elements are returned:

  enumerate(Index, Iterator1) ->
    {Iterator2, _ } = llists:mapfoldl(fun(T, Acc) -> {{Acc, T}, Acc+1} end, Index, Iterator1),
    Iterator2.
  ```
 
  Example:
  ```
  > llists:to_list(
       llists:enumerate(0,
           llists:from_list([one, two, three]))).
  [{0,one},{1,two},{2,three}]

filter/2

filter(Pred, Iterator1) -> Iterator2

Filtered is an iterator of all elements Elem in Iterator1 for which Pred(Elem) returns true.

filtermap/2

filtermap(Fun, Iterator1) -> Iterator2

Calls Fun(Elem) on successive elements Elem of Iterator1. Fun/1 must return either a Boolean or a tuple {true, Value}. The function returns the iterator of elements for which Fun returns a new value, where a value of true is synonymous with {true, Elem}.

That is, filtermap behaves as if it had been defined as follows, except that the iterator is not fully evaluated before elements are returned:

  filtermap(Fun, Iterator) ->
      llists:foldr(fun(Elem, Acc) ->
                          case Fun(Elem) of
                              false -> Acc;
                              true -> [Elem|Acc];
                              {true,Value} -> [Value|Acc]
                          end
                   end, [], Iterator).
Example:
  > llists:to_list(
  >  llists:filtermap(
  >   fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end,
  >   llists:seq(1, 5))).
  [1,2]

flatlength/1

flatlength(DeepIterator) -> Length

Equivalent to length(flatten(DeepIterator)).

flatmap/2

flatmap(Fun, Iterator1) -> Iterator2

Takes a function from As to iterators of Bs, and an iterator of As (Iterator1) and produces an iterator of Bs (Iterator2) by applying the function to every element in Iterator1 and appending the resulting iterators.

That is, flatmap behaves as if it had been defined as follows:

  llists:flatmap(Fun, Iterator) ->
      llists:append(llists:map(Fun, Iterator)).
Example:
  > llists:to_list(
  >  llists:flatmap(
  >   fun(X)->llists:from_list([X,X]) end,
  >   llists:from_list([a,b,c]))).
  [a,a,b,b,c,c]

flatten/1

flatten(DeepIterator) -> Iterator

Returns a flattened version of DeepIterator.

flatten/2

flatten(DeepIterator, TailIterator) -> Iterator

Returns a flattened version of DeepIterator with tail Tail appended.

foldl/3

foldl(Fun, Acc0, Iterator) -> AccOut

Calls Fun(Elem, AccIn) on successive elements A of Iterator, starting with AccIn == Acc0. Fun/2 must return a new accumulator, which is passed to the next call. The function returns the final value of the accumulator. Acc0 is returned if the iterator is empty.

The iterator will be fully evaluated, infinite iterators will never return.

foldr/3

foldr(Fun, Acc0, Iterator) -> AccOut

Like foldl/3, but the list is traversed from right to left.

Example:
  > P = fun(A, AccIn) -> io:format("~p ", [A]), AccIn end.
  #Fun<erl_eval.12.2225172>
  > llists:foldl(P, void, llists:seq(1, 3)).
  1 2 3 void
  > lists:foldr(P, void, llists:seq(1, 3)).
  3 2 1 void
The iterator is fully evaluated before the fold begins, infinite iterators will never return. foldl/3 does not fully evaluate the iterator and is usually preferred to foldr/3.

See also: foldl/3.

foreach/2

foreach(Fun, Iterator) -> ok

Calls Fun(Elem) for each element Elem in Iterator. This function is used for its side effects and the evaluation order is defined to be the same as the order of the elements in the iterator.

The iterator will be fully evaluated, infinite iterators will never return.

from_list/1

from_list(List) -> Iterator

Construct a new iterator from an existing list. Each element of the list will be returned in order by the returned iterator.

from_map/1

from_map(Map) -> Iterator

Construct a new iterator from an existing map. Each {Key, Value} tuple of the map will be returned in an arbitrary order by the returned iterator.

hd/1

hd(Iterator) -> Elem

Returns the head of Iterator, that is, the first element, for example:

  > llists:hd(llists:seq(1, 5)).
  1
Failure: badarg if Iterator is empty.

is_iterator/1

is_iterator(Candidate) -> boolean()

Tests if the given Candidate is an iterator, returns true if it and false otherwise.

join/2

join(Sep, Iterator1) -> Iterator2

Inserts Sep between each element in Iterator1. Has no effect on an empty iterator or on a singleton iterator. For example:

  > llists:to_list(llists:join(x, llists:from_list([a,b,c]))).
  [a,x,b,x,c]
  > llists:to_list(lists:join(x, llists:from_list([a]))).
  [a]
  > llists:to_list(lists:join(x, llists:from_list([]))).
  []
Evaluates one element further in the iterator than the current value.

keydelete/3

keydelete(Key, N, TupleIterator1) -> TupleIterator2

Returns a copy of TupleIterator1 where the first occurrence of a tuple whose Nth element compares equal to Key is deleted, if there is such a tuple.

keyfind/3

keyfind(Key, N, TupleIterator) -> Tuple | false

Searches the iterator of tuples TupleIterator for a tuple whose Nth element compares equal to Key. Returns Tuple if such a tuple is found, otherwise false.

The iterator will be evaluated until a match is found. If no match is found, infinite iterators will never return.

keymap/3

keymap(Fun, N, TupleIterator1) -> TupleIterator2

Returns an iterator of tuples where, for each tuple in TupleIterator1, the Nth element Term1 of the tuple has been replaced with the result of calling Fun(Term1).

Examples:
  > Fun = fun(Atom) -> atom_to_list(Atom) end.
  #Fun<erl_eval.6.10732646>
  2> llists:to_list(
  2>  llists:keymap(
  2>   Fun,
  2>   2,
  2>   llists:from_list([{name,jane,22},{name,lizzie,20},{name,lydia,15}]))).
  [{name,"jane",22},{name,"lizzie",20},{name,"lydia",15}]

keymember/3

keymember(Key, N, TupleIterator) -> boolean()

Returns true if there is a tuple in TupleIterator whose Nth element compares equal to Key, otherwise false.

The iterator will be evaluated until a match is found. If no match is found, infinite iterators will never return.

keymerge/3

keymerge(N, TupleIterator1, TupleIterator2) -> TupleIterator3

Returns the sorted iterator formed by merging TupleIterator1 and TupleIterator2. The merge is performed on the Nth element of each tuple. Both TupleIterator1 and TupleIterator2 must be key-sorted before evaluating this function. When two tuples compare equal, the tuple from TupleIterator1 is picked before the tuple from TupleIterator2.

The first element of each iterator will be evaluated.

keyreplace/4

keyreplace(Key, N, TupleIterator1, NewTuple) -> TupleIterator2

Returns a copy of TupleIterator1 where the first occurrence of a T tuple whose Nth element compares equal to Key is replaced with NewTuple, if there is such a tuple T.

keysearch/3

keysearch(Key, N, TupleIterator) -> {value, Tuple} | false

Searches the iterator of tuples TupleIterator for a tuple whose Nth element compares equal to Key. Returns {value, Tuple} if such a tuple is found, otherwise false.

Function keyfind/3 is usually more convenient.

See also: keyfind/3.

keysort/2

keysort(N, TupleIterator1) -> TupleIterator2

Returns an iterator containing the sorted elements of iterator TupleIterator1. Sorting is performed on the Nth element of the tuples. The sort is stable.

The iterator is fully evaluated, infinite iterators will never return.

keystore/4

keystore(Key, N, TupleIterator1, NewTuple) -> TupleIterator2

Returns a copy of TupleIterator1 where the first occurrence of a tuple T whose Nth element compares equal to Key is replaced with NewTuple, if there is such a tuple T. If there is no such tuple T, a copy of TupleIterator1 where NewTuple has been appended to the end is returned.

keytake/3

keytake(Key, N, TupleIterator1) -> {value, Tuple, TupleIterator2}

Searches the iterator of tuples TupleIterator1 for a tuple whose Nth element compares equal to Key. Returns {value, Tuple, TupleIterator2} if such a tuple is found, otherwise false. TupleIterator2 is a copy of TupleIterator1 where the first occurrence of Tuple has been removed.

Evaluates TupleIterator1 until a match is found. Iterating over TupleIterator2 will evaluate the same elements again. If no match is found, infinite iterators will never return.

last/1

last(Iterator) -> Elem

Returns the last element in Iterator.

The iterator will be fully evaluated, infinite iterators will never return.

length/1

length(Iterator) -> Length

Returns the length of Iterator, for example:

  > llists:length(llists:seq(1, 9)).
  9
The iterator will be fully evaluated, infinite iterators will never return.

map/2

map(Fun, Iterator1) -> Iterator2

Takes a function Fun from As to Bs, and an Iterator1 of As and produces an Iterator2 of Bs by applying the function to every element in the iterator.

mapfoldl/3

mapfoldl(Fun, Acc0, Iterator1) -> {Iterator2, AccOut}

Combines the operations of map/2 and foldl/3 into one pass.

Example:
  > % Summing the elements in an iterator and double them at the same time:
  > DoubleAndSum = fun(X, Sum) -> {2*X, X+Sum} end,
  > {Mapped, Acc} = llists:mapfoldl(DoubleAndSum, 0, llists:seq(1,5)),
  > {llists:to_list(Mapped), Acc}.
  {[2,4,6,8,10],15}
The iterator is fully evaluated before the mapfold begins, infinite iterators will never return.

mapfoldr/3

mapfoldr(Fun, Acc0, Iterator1) -> {Iterator2, AccOut}

Combines the operations of map/2 and foldr/3 into one pass.

The iterator is fully evaluated before the mapfold begins, infinite iterators will never return.

max/1

max(Iterator) -> Elem

Returns the first element of Iterator that compares greater than or equal to all other elements of Iterator.

The iterator is fully evaluated, infinite iterators will never return.

member/2

member(Elem, Iterator) -> boolean()

Returns true if Elem matches some element of Iterator, otherwise false.

Stops evaluating Iterator when a match is found or when Iterator is empty.

merge/1

merge(IteratorOfIterators) -> Iterator

Returns the sorted iterator formed by merging all the subiterators of IteratorOfIterators. All subiterators must be sorted before evaluating this function. When two elements compare equal, the element from the subiterator with the lowest position in IteratorOfIterators is picked before the other element.

The first element of each subiterator will be evaluated.

merge/2

merge(Iterator1, Iterator2) -> Iterator3

Returns the sorted iterator formed by merging Iterator1 and Iterator2. Both Iterator1 and Iterator2 must be sorted before evaluating this function. When two elements compare equal, the element from Iterator1 is picked before the element from Iterator2.

The first element of each iterator will be evaluated.

merge/3

merge(Fun, Iterator1, Iterator2) -> Iterator3

Returns the sorted iterator formed by merging Iterator1 and Iterator2. Both Iterator1 and Iterator2 must be sorted according to the ordering function Fun before evaluating this function. Fun(A, B) is to return true if A compares less than or equal to B in the ordering, otherwise false. When two elements compare equal, the element from Iterator1 is picked before the element from Iterator2.

The first element of each iterator will be evaluated.

merge3/3

merge3(Iterator1, Iterator2, Iterator3) -> Iterator4

Returns the sorted iterator formed by merging Iterator1, Iterator2, and Iterator3. All of Iterator1, Iterator2, and Iterator3 must be sorted before evaluating this function. When two elements compare equal, the element from Iterator1, if there is such an element, is picked before the other element, otherwise the element from Iterator2 is picked before the element from Iterator3.

The first element of each iterator will be evaluated.

min/1

min(Iterator) -> Elem

Returns the first element of Iterator that compares less than or equal to all other elements of Iterator.

The iterator is fully evaluated, infinite iterators will never return.

next/1

next(Iterator) -> LazyList

Demand an element from Iterator. Will return either an improper list containing the next element and an iterator as a continuation, or an empty list if iteration is complete.

Examples:

  > llists:next(llists:seq(1, 5)).
  [1|{iterator,#Fun<llists.1.134155648>}]
  > llists:next(llists:from_list([])).
  []

nth/2

nth(N, Iterator) -> Elem

Returns the Nth element of Iterator.

Example:
  > lists:nth(3, [a, b, c, d, e]).
  c

nthtail/2

nthtail(N, Iterator1) -> Iterator2

Returns the Nth tail of Iterator1, that is, the subiterator of Iterator1 starting at N+1 and continuing up to the end of the iterator.

partition/2

partition(Pred, Iterator1) -> {Satisfying, NotSatisfying}

Partitions Iterator1 into two iterators, where the first iterator contains all elements for which Pred(Elem) returns true, and the second iterator contains all elements for which Pred(Elem) returns false.

Examples:
  > {Satisfying, NotSatisfying} = llists:partition(
  >  fun(A) -> A rem 2 == 1 end,
  >  llists:seq(1, 7)),
  > {llists:to_list(Satisfying), llists:to_list(NotSatisfying)}.
  {[1,3,5,7],[2,4,6]}
  > {Satisfying, NotSatisfying} = llists:partition(
  >  fun(A) -> is_atom(A) end,
  >  llists:from_list([a,b,1,c,d,2,3,4,e])),
  > {llists:to_list(Satisfying), llists:to_list(NotSatisfying)}.
  {[a,b,c,d,e],[1,2,3,4]}

For a different way to partition a list, see splitwith/2.

Each result iterator will evaluate elements of the original iterator independently. If both are evaluated, this will result in all elements being evaluated twice.

See also: splitwith/2.

prefix/2

prefix(Iterator1, Iterator2) -> boolean()

Returns true if Iterator1 is a prefix of Iterator2, otherwise false.

Both iterators will be evaluated until the point they diverge. If both iterators are identical and infinite, will never return.

reverse/1

reverse(Iterator1) -> Iterator2

Returns an iterator with the elements in Iterator1 in reverse order.

The iterator will be fully evaluated, infinite iterators will never return.

reverse/2

reverse(Iterator1, TailIterator) -> Iterator2

Returns a list with the elements in Iterator1 in reverse order, with tail TailIterator appended.

Example:
  > lists:reverse([1, 2, 3, 4], [a, b, c]).
  [4,3,2,1,a,b,c]
The iterator Iterator1 will be fully evaluated, infinite iterators will never return.

search/2

search(Pred, Iterator) -> {value, Value} | false

If there is a Value in Iterator such that Pred(Value) returns true, returns {value, Value} for the first such Value, otherwise returns false.

The iterator is evaluated until a match is found. If no match is ever found, infinite iterators will never return.

seq/2

seq(From, To) -> Iterator

See also: seq/3.

seq/3

seq(From, To, Incr) -> Iterator

Returns an iterator over a sequence of integers that starts with From and contains the successive results of adding Incr to the previous element, until To is reached or passed (in the latter case, To is not an element of the sequence). Incr defaults to 1.

Failures: The following equalities hold for all sequences:
  length(lists:seq(From, To)) =:= To - From + 1
  length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr

sort/1

sort(Iterator1) -> Iterator2

Returns an iterator containing the sorted elements of Iterator1.

The iterator is fully evaluated, infinite iterators will never return.

sort/2

sort(Fun, Iterator1) -> Iterator2

Returns an iterator containing the sorted elements of Iterator1, according to the ordering function Fun. Fun(A, B) is to return true if A compares less than or equal to B in the ordering, otherwise false.

The iterator is fully evaluated, infinite iterators will never return.

split/2

split(N, Iterator1) -> {Iterator2, Iterator3}

Splits Iterator1 into Iterator2 and Iterator3. Iterator2 contains the first N elements and Iterator3 the remaining elements (the Nth tail).

Evaluates the first N elements of Iterator1 to construct Iterator3.

splitwith/2

splitwith(Pred, Iterator1) -> {Iterator2, Iterator3}

Partitions Iterator1 into two iterators according to Pred. splitwith/2 behaves as if it is defined as follows:

  llists:splitwith(Pred, Iterator) ->
      {llists:takewhile(Pred, Iterator),
       llists:dropwhile(Pred, Iterator)}.
Examples:
  > {Before, After} = llists:splitwith(fun(A) -> A rem 2 == 1 end, llists:seq(1, 7)),
  > {llists:to_list(Before), llists:to_list(After)}.
  {[1],[2,3,4,5,6,7]}
  > {Before, After} = lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]),
  > {llists:to_list(Before), llists:to_list(After)}.
  {[a,b],[1,c,d,2,3,4,e]}

For a different way to partition an iterator, see partition/2.

Evaluates the elements of Iterator for which Pred(Elem) returns false. If Pred never returns false, infinite iterators will not return.

See also: partition/2.

sublist/2

sublist(Iterator1, Len) -> Iterator2

See also: sublist/3.

sublist/3

sublist(Iterator1, Start, Len) -> Iterator2

Returns the portion of Iterator1 starting at Start and with (maximum) Len elements. Start defaults to 1. It is not an error for Start+Len to exceed the length of the iterator, in that case the whole iterator is returned.

subtract/2

subtract(Iterator1, Iterator2) -> Iterator3

Returns a new iterator Iterator3 that is a copy of Iterator1, subjected to the following procedure: for each element in Iterator2, its first occurrence in Iterator1 is deleted.

Example:
  > lists:subtract("123212", "212").
  "312".
Iterator2 is fully evaluated, infinite iterators will never return.

suffix/2

suffix(Iterator1, Iterator2) -> boolean()

Returns true if Iterator1 is a suffix of Iterator2, otherwise false.

Both Iterator1 and Iterator2 are fully evaluated, infinite iterators will never return.

sum/1

sum(Iterator) -> Sum

Returns the sum of the elements in Iterator.

The iterator is fully evaluated, infinite iterators will never return.

takewhile/2

takewhile(Pred, Iterator1) -> Iterator2

Takes elements Elem from Iterator1 while Pred(Elem) returns true, that is, the function returns the longest prefix of the iterator for which all elements satisfy the predicate.

tl/1

tl(Iterator1) -> Iterator2

Returns the tail of Iterator1, that is, the iterator minus the first element, for example:

  > llists:to_list(
  >  llists:tl(
  >   llists:from_list([geesties, guilies, beasties]))).
  [guilies, beasties]
Failure: badarg if Iterator1 is empty.

to_list/1

to_list(Iterator) -> List

Fully evaluate Iterator and return a list containing all elements produced. Infinite iterators will never return.

to_map/1

to_map(Iterator) -> Map

Fully evaluate an Iterator of {Key, Value} tuples and return a map containing all pairs produced. Infinite iterators will never return.

If duplicate Keys are present in the iterator it is undefined which will appear in the final map.

ukeymerge/3

ukeymerge(N, TupleIterator1, TupleIterator2) -> TupleIterator3

Returns the sorted iterator formed by merging TupleIterator1 and TupleIterator2. The merge is performed on the Nth element of each tuple. Both TupleIterator1 and TupleIterator2 must be key-sorted without duplicates before evaluating this function. When two tuples compare equal, the tuple from TupleIterator1 is picked and the one from TupleIterator2 is deleted.

The first element of each iterator will be evaluated.

ukeysort/2

ukeysort(N, TupleIterator1) -> TupleIterator2

Returns a iterator containing the sorted elements of iterator TupleIterator1 where all except the first tuple of the tuples comparing equal have been deleted. Sorting is performed on the Nth element of the tuples.

The iterator is fully evaluated, infinite iterators will never return.

umerge/1

umerge(IteratorOfIterators) -> Iterator

Returns the sorted iterator formed by merging all the subiterators of IteratorOfIterators. All subiterators must be sorted and contain no duplicates before evaluating this function. When two elements compare equal, the element from the subiterator with the lowest position in IteratorOfIterators is picked and the other is deleted.

The first element of each subiterator will be evaluated.

umerge/2

umerge(Iterator1, Iterator2) -> Iterator3

Returns the sorted iterator formed by merging Iterator1 and Iterator2. Both Iterator1 and Iterator2 must be sorted and contain no duplicates before evaluating this function. When two elements compare equal, the element from Iterator1 is picked and the one from Iterator2 is deleted.

The first element of each iterator will be evaluated.

umerge/3

umerge(Fun, Iterator1, Iterator2) -> Iterator3

Returns the sorted iterator formed by merging Iterator1 and Iterator2. Both Iterator1 and Iterator2 must be sorted according to the ordering function Fun and contain no duplicates before evaluating this function. Fun(A, B) is to return true if A compares less than or equal to B in the ordering, otherwise false. When two elements compare equal, the element from Iterator1 is picked and the one from Iterator2 is deleted.

The first element of each iterator will be evaluated.

umerge3/3

umerge3(Iterator1, Iterator2, Iterator3) -> Iterator4

Returns the sorted iterator formed by merging Iterator1, Iterator2, and Iterator3. All of Iterator1, Iterator2, and Iterator3 must be sorted and contain no duplicates before evaluating this function. When two elements compare equal, the element from Iterator1 is picked if there is such an element, otherwise the element from Iterator2 is picked, and the other is deleted.

The first element of each iterator will be evaluated.

unfold/2

unfold(Fun, Acc0) -> Iterator

Construct a new iterator from a Fun(AccIn) function and an initial accumulator value Acc0. When an element is demanded of the iterator, Fun will be invoked with the current accumulator to produce a value. Fun is expected to return a tuple of {Elem, AccOut}: the element to produce and the new accumulator value. If iteration is complete, Fun should return none.

uniq/1

uniq(Iterator1) -> Iterator2

Returns an iterator containing the elements of Iterator1 with duplicated elements removed (preserving the order of the elements). The first occurrence of each element is kept.

May require arbitrarily large quantities of memory to track all elements seen so far. If only duplicate elements remain, infinite iterators will never return.

See also: llists_utils:unique/1.

uniq/2

uniq(Fun, Iterator1) -> Iterator2

Returns an iterator containing the elements of Iterator1 without the elements for which Fun returned duplicate values (preserving the order of the elements). The first occurrence of each element is kept.

May require arbitrarily large quantities of memory to track all transformed elements seen so far. If only duplicate transformed elements remain, infinite iterators will never return.

unzip/1

unzip(Iterator1) -> {Iterator2, Iterator3}

"Unzips" a iterator of two-tuples into two iterators, where the first iterator contains the first element of each tuple, and the second iterator contains the second element of each tuple.

unzip3/1

unzip3(Iterator1) -> {Iterator2, Iterator3, Iterator4}

"Unzips" a iterator of three-tuples into three iterators, where the first iterator contains the first element of each tuple, the second iterator contains the second element of each tuple, and the third iterator contains the third element of each tuple.

usort/1

usort(Iterator1) -> Iterator2

Returns a iterator containing the sorted elements of Iterator1 where all except the first element of the elements comparing equal have been deleted.

The iterator will be fully evaluated, infinite iterators will never return.

usort/2

usort(Fun, Iterator1) -> Iterator2

Returns a iterator containing the sorted elements of Iterator1 where all except the first element of the elements comparing equal according to the ordering function Fun have been deleted. Fun(A, B) is to return true if A compares less than or equal to B in the ordering, otherwise false.

The iterator will be fully evaluated, infinite iterators will never return.

zip/2

zip(Iterator1, Iterator2) -> Iterator3

"Zips" two iterators of equal length into one iterator of two-tuples, where the first element of each tuple is taken from the first iterator and the second element is taken from the corresponding element in the second iterator.

zip3/3

zip3(Iterator1, Iterator2, Iterator3) -> Iterator4

"Zips" three iterators of equal length into one iterator of three-tuples, where the first element of each tuple is taken from the first iterator, the second element is taken from the corresponding element in the second iterator, and the third element is taken from the corresponding element in the third iterator.

zipwith/3

zipwith(Combine, Iterator1, Iterator2) -> Iterator3

Combines the elements of two iterators of equal length into one iterator. For each pair X, Y of iterator elements from the two iterators, the element in the result iterator is Combine(X, Y).

llists:zipwith(fun(X, Y) -> {X, Y} end, Iterator1, Iterator2) is equivalent to llists:zip(Iterator1, Iterator2).

Example:
  > llists:to_list(
  >  llists:zipwith(fun(X, Y) -> X + Y end, llists:seq(1, 3), llist:seq(4, 6))).
  [5,7,9]

zipwith3/4

zipwith3(Combine, Iterator1, Iterator2, Iterator3) -> Iterator4

Combines the elements of three iterators of equal length into one iterator. For each triple X, Y, Z of iterator elements from the three iterators, the element in the result iterator is Combine(X, Y, Z).

zipwith3(fun(X, Y, Z) -> {X, Y, Z} end, Iterator1, Iterator2, Iterator3) is equivalent to zip3(Iterator1, Iterator2, Iterator3).

Examples:
  > llists:to_list(
  >  llists:zipwith3(
  >   fun(X, Y, Z) -> X + Y + Z end,
  >   llists:seq(1, 3),
  >   llists:seq(4, 6),
  >   llists:seq(7, 9))).
  [12,15,18]
  > llists:to_list(
  >  llists:zipwith3(
  >   fun(X, Y, Z) -> [X, Y, Z] end,
  >   llists:from_list([a,b,c]),
  >   llists:from_list([x,y,z]),
  >   llists:seq(1, 3))).
  [[a,x,1],[b,y,2],[c,z,3]]


Generated by EDoc