Module llists_utils

Additional iterator utilities that are not replicas of lists module functionality.

Description

Additional iterator utilities that are not replicas of lists module functionality. These functions are kept separate to avoid any future name clashes with additions to the stdlib.

Unlike the functions in llists, these utility functions do not follow the same strict transformation rules. Instead, inputs and outputs generally follow evaluation needs with eagerly evaluated values passed as lists and lazily evaluated ones passed as iterators.

Data Types

permutation_options()

permutation_options() = proplists:proplist()

Function Index

choice/1 Create an infinite iterator that returns random elements from the given list of Choices.
combinations/2
combinations/3 Create an iterator that returns all combinations of elements from Choices that are N elements long.
cycle/1 Create an infinite iterator that repeatedly returns the sequence of elements in the given iterator.
enumerate/1(Deprecated.)
group/2 Create an iterator that returns groups of elements from Iterator1 as a list of at least Length elements.
groupwith/2 Create an iterator that returns groups of elements from Iterator1 based on the return value of Pred(Elem).
permutations/2
permutations/3 Create an iterator that returns all permutations of elements from Choices that are N elements long.
random/0 Create an infinite iterator that returns random floats in the range [0.0, 1.0).
random/1 Create an infinite iterator that returns random integers in the range [1, N).
unique/1 As unique/2, but with == as the equality function.
unique/2 Discards repeated values in a sorted iterator according to a provided equality function Fun(A, B) which should return true when A and B are equal and false otherwise.

Function Details

choice/1

choice(Choices) -> Iterator

Create an infinite iterator that returns random elements from the given list of Choices. Each iterator returns a unique sequence and returns the same unique sequence each time it is evaluated.

combinations/2

combinations(N, Choices) -> Iterator

See also: combinations/3.

combinations/3

combinations(N, Choices, Options) -> Iterator

Create an iterator that returns all combinations of elements from Choices that are N elements long. If the repetitions property is passed in Options, combinations with repeated elements of Choices are included.

Examples:
  > llists:to_list(
       llists_utils:combinations(2, [1, 2, 3]).
  [[1,2],[1,3],[2,3]]
  > llists:to_list(
       llists_utils:combinations(2, [1, 2, 3], [repetitions]).
  [[1,1],[1,2],[1,3],[2,2],[2,3],[3,3]]
If the elements of Choices are sorted, the order of the resulting combinations will also be sorted.

cycle/1

cycle(Iterator1) -> Iterator2

Create an infinite iterator that repeatedly returns the sequence of elements in the given iterator.

enumerate/1

enumerate(Iterator1) -> Iterator2

This function is deprecated: Equivalent functionality is now present in llists:enumerate/1.

See also: llists:enumerate/1.

group/2

group(Length, Iterator1) -> Iterator2

Create an iterator that returns groups of elements from Iterator1 as a list of at least Length elements.

Example:
  > llists:to_list(
       llists_utils:group(
           2,
           llists:from_list([1, 2, 3, 4, 5]))).
  [[1,2],[3,4],[5]]
It is not an error if there are not enough elements to fill out the final group, instead a smaller group is returned.

groupwith/2

groupwith(Pred, Iterator1) -> Iterator2

Create an iterator that returns groups of elements from Iterator1 based on the return value of Pred(Elem). If the predicate function returns true it signals the end of a group which will be returned as a list. If the predicate returns false, the element will be included in the next group returned. Even if the predicate function returns false for the last element, the final group will still be returned.

Example:
  > llists:to_list(
       llists_utils:groupwith(
           fun (Elem) -> Elem rem 2 == 0 end,
           llists:from_list([1, 2, 3, 4, 5]))).
  [[1,2],[3,4],[5]]
If Pred(Elem) returns false for every element in an infinite iterator, the first evaluation of Iterator2 will never return.

permutations/2

permutations(N, Choices) -> Iterator

See also: permutations/3.

permutations/3

permutations(N, Choices, Options) -> Iterator

Create an iterator that returns all permutations of elements from Choices that are N elements long. If the repetitions property is passed in Options, permutations with repeated elements of Choices are included.

Examples:
  > llists:to_list(
       llists_utils:permutations(2, [1, 2, 3]).
  [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]
  > llists:to_list(
       llists_utils:permutations(2, [1, 2, 3], [repetitions]).
  [[1,1],[1,2],[1,3],[2,1],[2,2],[2,3],[3,1],[3,2],[3,3]]
If the elements of Choices are sorted, the order of the resulting permutations will also be sorted.

random/0

random() -> Iterator

Create an infinite iterator that returns random floats in the range [0.0, 1.0). Each iterator returns a unique sequence and returns the same unique sequence each time it is evaluated.

See also: rand:uniform/0.

random/1

random(N) -> Iterator

Create an infinite iterator that returns random integers in the range [1, N). Each iterator returns a unique sequence and returns the same unique sequence each time it is evaluated.

See also: rand:uniform/1.

unique/1

unique(Iterator1) -> Iterator2

As unique/2, but with == as the equality function.

See also: unique/2.

unique/2

unique(Fun, Iterator1) -> Iterator2

Discards repeated values in a sorted iterator according to a provided equality function Fun(A, B) which should return true when A and B are equal and false otherwise. All values that compare equal to the previously returned value are skipped until a non-equal value is found.

Example:
  > llists:to_list(
       llists_utils:unique(
           llists:from_list([1, 1, 2, 2, 1, 1]))).
  [1,2,1]
Infinite iterators of equal values will cause the first evaluation of Iterator2 to never return.


Generated by EDoc