Class for Iterable

Satisfied Interfaces: Container, ContainerWithFirstElement<Element,Null>

All Known Satisfying Interfaces: Collection

Abstract supertype of containers whose elements may be iterated. An iterable container 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.

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<Element>

Attributes
coalesced	Source Code shared default Iterable<Element> coalesced 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.
empty	Source Code shared actual default Boolean empty Determines if the iterable object is empty, that is to say, if the iterator returns no elements.
first	Source Code shared actual default Element? first The first element returned by the iterator, if any. This should produce the same value as `ordered.iterator.head`.
indexed	Source Code shared default Iterable<Element> indexed 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"`.
iterator	Source Code shared formal Iterator<Element> iterator An iterator for the elements belonging to this container.
last	Source Code shared actual default Element? last The last element returned by the iterator, if any. Iterables are potentially infinite, so calling this might never return; also, this implementation will iterate through all the elements, which might be very time-consuming.
rest	Source Code shared default Iterable<Element> rest Returns an iterable object containing all but the first element of this container.
sequence	Source Code shared default Element[] sequence A sequence containing the elements returned by the iterator.

Inherited Attributes
Attributes inherited from: Object hash, string
Attributes inherited from: Container empty
Attributes inherited from: ContainerWithFirstElement<Element,Null> first, last

Methods
any	Source 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.
by	Source Code shared default Iterable<Element> by(Integer step) Produce an `Iterable` containing every `step`th 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: Exception if the given step size is nonpositive, i.e. `step<1`
chain	Source Code shared default Iterable<Element> chain<Other>(Iterable<Element> other) The elements of this iterable object, in their original order, followed by the elements of the given iterable object also in their original order.
collect	Source 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
count	Source 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.
every	Source 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.
filter	Source Code shared default Iterable<Element> filter(Boolean selecting(Element elem)) An `Iterable` containing the elements of this container that satisfy the given predicate. Parameters: selecting The predicate the elements must satisfy. See also: select
find	Source 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.
findLast	Source 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.
fold	Source 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.
group	Source Code shared default Map<Key,Item> group<Grouping>(Grouping grouping(Element elem)) Creates a Map that contains this `Iterable`'s elements, grouped in `Sequence`s under the keys provided by the grouping function. Parameters: grouping A function that must return the key under which to group the specified element.
map	Source Code shared default Iterable<Element> 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
select	Source 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
skipping	Source Code shared default Iterable<Element> skipping(Integer skip) 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.
sort	Source 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. See also: byIncreasing, byDecreasing
taking	Source Code shared default Iterable<Element> taking(Integer take) 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.

Inherited Methods
Methods inherited from: Object equals