Satisfied Interfaces: Category
Direct Known Satisfying Interfaces: Collection<Element>, Sequence<Element>

Abstract supertype of categories whose elements may be iterated. An iterable category need not be finite, but its elements must at least be countable. There may not be a well-defined iteration order, and so the order of iterated elements may not be stable.

The type Iterable<Element,Null>, usually abbreviated {Element*} represents a possibly-empty iterable container. The type Iterable<Element,Nothing>, usually abbreviated {Element+} represents a nonempty iterable container.

An instance of Iterable may be constructed by surrounding a value list in braces:

{String+} words = { "hello", "world" };

An instance of Iterable may be iterated using a for loop:

for (c in "hello world") { ... }

Iterable and its subtypes define various operations that return other iterable objects. Such operations come in two flavors:

  • Lazy operations return a view of the receiving iterable object. If the underlying iterable object is mutable, then changes to the underlying object will be reflected in the resulting view. Lazy operations are usually efficient, avoiding memory allocation or iteration of the receiving iterable object.
  • Eager operations return an immutable object. If the receiving iterable object is mutable, changes to this object will not be reflected in the resulting immutable object. Eager operations are often expensive, involving memory allocation and iteration of the receiving iterable object.

Lazy operations are preferred, because they can be efficiently chained. For example:

string.filter((Character c) => c.letter)
      .map((Character c) => c.uppercased)

is much less expensive than:

string.select((Character c) => c.letter)
      .collect((Character c) => c.uppercased)

Furthermore, it is always easy to produce a new immutable iterable object given the view produced by a lazy operation. For example:

[ *string.filter((Character c) => c.letter)
      .map((Character c) => c.uppercased) ]

Lazy operations normally return an instance of Iterable or Map.

However, there are certain scenarios where an eager operation is more useful, more convenient, or no more expensive than a lazy operation, including:

  • sorting operations, which are eager by nature,
  • operations which preserve emptiness/nonemptiness of the receiving iterable object.

Eager operations normally return a sequence.

By: Gavin
See also: Collection
Attributes
coalescedSource Code

The non-null elements of this Iterable, in their original order. For null elements of the original Iterable, there is no entry in the resulting iterable object.

cycledSource Code
shared default Iterable<Element,Absent> cycled

A non-finite iterable object that produces the elements of this iterable object, repeatedly.

See also: cycle
emptySource Code
shared default Boolean empty

Determines if the iterable object is empty, that is to say, if the iterator returns no elements.

firstSource Code
shared default Absent|Element first

The first element returned by the iterator, if any, of null if the iterable object is empty.

indexedSource Code

All entries of form index->element where index is the position at which element occurs, for every non-null element of this Iterable, ordered by increasing index. For a null element at a given position in the original Iterable, there is no entry with the corresponding index in the resulting iterable object. The expression

{ "hello", null, "world" }.indexed

results in an iterable object with the entries 0->"hello" and 2->"world".

lastSource Code
shared default Absent|Element last

The last element returned by the iterator, if any, of null if the iterable object is empty. Iterable objects are potentially infinite, so calling this might never return; also, this implementation will iterate through all the elements, which might be very time-consuming.

restSource Code

Returns an iterable object containing all but the first element of this container.

sequenceSource Code

A sequence containing the elements returned by the iterator.

sizeSource Code
shared default Integer size

The number of elements returned by the iterator of this iterable object, if the iterator terminates. In the case of an iterable whose elements are not countable, this operation never terminates.

stringSource Code
shared actual default String string

A string of form "{ x, y, z }" where x, y, and z are the string representations of the elements of this collection, as produced by the iterator of the collection, or the string "{}" if this iterable is empty. If the number of items is very large only a certain amount of them might be shown followed by “…“.

Refined declaration: string
Inherited Attributes
Attributes inherited from: Object
Methods
anySource Code
shared default Boolean any(Boolean selecting(Element e))

Return true if at least one element satisfies the predicate function.

Parameters:
  • selecting

    The predicate that at least one element must satisfy.

bySource Code
shared default Iterable<Element,Absent> by(Integer step)

Produce an Iterable containing every stepth element of this iterable object. If the step size is 1, the Iterable contains the same elements as this iterable object. The step size must be greater than zero. The expression

(0..10).by(3)

results in an iterable object with the elements 0, 3, 6, and 9 in that order.

Throws:
chainSource Code
shared default Iterable<Element|Other,Absent&OtherAbsent> chain<Other, OtherAbsent>(Iterable<Other,OtherAbsent> other)
given OtherAbsent satisfies Null

The elements of this iterable object, in their original order, followed by the elements of the given iterable object also in their original order.

collectSource Code
shared default Result[] collect<Result>(Result collecting(Element element))

A sequence containing the results of applying the given mapping to the elements of this container. An eager counterpart to map().

Parameters:
  • collecting

    The transformation applied to the elements.

See also: map
containsSource Code
shared actual default Boolean contains(Object element)

Determines if the given value belongs to this Category, that is, if it is an element of this Category.

For most Categorys, if x==y, then category.contains(x) evaluates to the same value as category.contains(y). However, it is possible to form a Category consistent with some other equivalence relation, for example ===. Therefore implementations of contains() which do not satisfy this relationship are tolerated.

Refined declaration: contains
countSource Code
shared default Integer count(Boolean selecting(Element element))

Return the number of elements in this Iterable that satisfy the predicate function.

Parameters:
  • selecting

    The predicate satisfied by the elements to be counted.

cycleSource Code
shared default Iterable<Element,Absent> cycle(Integer times)

A finite iterable object that produces the elements of this iterable object, repeatedly, the given number of times.

See also: cycled, repeat
defaultNullElementsSource Code
shared default Iterable<Element&Object|Default,Absent> defaultNullElements<Default>(Default defaultValue)

An Iterable that produces the elements of this iterable object, replacing every null element with the given default value. The resulting iterable object does not produce the value null.

Parameters:
  • defaultValue

    A default value that replaces null elements.

everySource Code
shared default Boolean every(Boolean selecting(Element e))

Return true if all elements satisfy the predicate function.

Parameters:
  • selecting

    The predicate that all elements must satisfy.

filterSource Code

An Iterable containing the elements of this container that satisfy the given predicate.

Parameters:
  • selecting

    The predicate the elements must satisfy.

See also: select
findSource Code
shared default Element? find(Boolean selecting(Element elem))

The first element which satisfies the given predicate, if any, or null otherwise.

Parameters:
  • selecting

    The predicate the element must satisfy.

findLastSource Code
shared default Element? findLast(Boolean selecting(Element elem))

The last element which satisfies the given predicate, if any, or null otherwise.

Parameters:
  • selecting

    The predicate the element must satisfy.

foldSource Code
shared default Result fold<Result>(Result initial, Result accumulating(Result partial, Element elem))

The result of applying the accumulating function to each element of this container in turn.

Parameters:
  • accumulating

    The accumulating function that accepts an intermediate result, and the next element.

followingSource Code
shared default {<Element|Other>+} following<Other>(Other head)

An Iterable with the given inital element followed by the elements of this iterable object.

iteratorSource Code
shared formal Iterator<Element> iterator()

An iterator for the elements belonging to this container.

longerThanSource Code
shared default Boolean longerThan(Integer length)

Determines if this iterable object has more elements than the given length. This is an efficient operation for iterable objects with many elements.

See also: size
mapSource Code
shared default Iterable<Result,Absent> map<Result>(Result collecting(Element elem))

An Iterable containing the results of applying the given mapping to the elements of to this container.

Parameters:
  • collecting

    The mapping to apply to the elements.

See also: collect
repeatSource Code
shared default List<Element> repeat(Integer times)

Returns a list formed by repeating the elements of this iterable object the given number of times, or an empty list if times<=0. An eager counterpart to cycle().

See also: cycle
selectSource Code
shared default Element[] select(Boolean selecting(Element element))

A sequence containing the elements of this container that satisfy the given predicate. An eager counterpart to filter().

Parameters:
  • selecting

    The predicate the elements must satisfy.

See also: filter
shorterThanSource Code
shared default Boolean shorterThan(Integer length)

Determines if this iterable object has fewer elements than the given length. This is an efficient operation for iterable objects with many elements.

See also: size
skippingSource Code

Produce an Iterable containing the elements of this iterable object, after skipping the first skip elements. If this iterable object does not contain more elements than the specified number of elements, the Iterable contains no elements.

skippingWhileSource Code

Produce an Iterable containing the elements of this iterable object, after skipping the leading elements until the given predicate function returns false.

sortSource Code
shared default Element[] sort(Comparison comparing(Element x, Element y))

A sequence containing the elements of this container, sorted according to a function imposing a partial order upon the elements.

For convenience, the functions byIncreasing() and byDecreasing() produce a suitable comparison function:

"Hello World!".sort(byIncreasing((Character c) => c.lowercased))

This operation is eager by nature.

Parameters:
  • comparing

    The function comparing pairs of elements.

takingSource Code

Produce an Iterable containing the first take elements of this iterable object. If the specified number of elements is larger than the number of elements of this iterable object, the Iterable contains the same elements as this iterable object.

takingWhileSource Code

Produce an Iterable containing the leading elements of this iterable object until the given predicate function returns false.

Inherited Methods
Methods inherited from: Object
Methods inherited from: Category