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

- Iterable
  - Collection
    - List
      - Array
      - LazyList
      - Sequential
        - Empty
          - empty
        - Sequence
          - ArraySequence
          - Range
          - Singleton
          - Tuple
      - String
    - Map
      - LazyMap
      - emptyMap
    - Set
      - LazySet
      - emptySet
  - Sequence
    - ArraySequence
    - Range
    - Singleton
    - Tuple

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
coalesced | Source Code shared default {<Element&Object>*} 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.
cycled | Source Code shared default Iterable<Element,Absent> cycled A non-finite iterable object that produces the elements of this iterable object, repeatedly. See also: cycle
empty | Source Code shared default Boolean empty Determines if the iterable object is empty, that is to say, if the iterator returns no elements.
first | Source Code shared default Absent|Element first The first element returned by the iterator, if any, of `null` if the iterable object is empty.
indexed | Source Code shared default {<Integer->Element&Object>*} 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"`.
last | Source 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.
rest | Source Code shared default {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.
size | Source 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.
string | Source 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 hash

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,Absent> 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: AssertionException if the given step size is nonpositive, i.e. `step<1`
chain | Source 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.
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
contains | Source 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 `Category`s, 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
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.
cycle | Source 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
defaultNullElements | Source 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.
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 {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.
following | Source Code shared default {<Element|Other>+} following<Other>(Other head) An `Iterable` with the given inital element followed by the elements of this iterable object.
iterator | Source Code shared formal Iterator<Element> iterator() An iterator for the elements belonging to this container.
longerThan | Source 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
map | Source 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
repeat | Source 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
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
shorterThan | Source 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
skipping | Source Code shared default {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.
skippingWhile | Source Code shared default {Element*} skippingWhile(Boolean skip(Element elem)) Produce an `Iterable` containing the elements of this iterable object, after skipping the leading elements until the given predicate function returns `false`.
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 {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.
takingWhile | Source Code shared default {Element*} takingWhile(Boolean take(Element elem)) Produce an `Iterable` containing the leading elements of this iterable object until the given predicate function returns `false`.

Inherited Methods
Methods inherited from: Object equals
Methods inherited from: Category contains, containsAny, containsEvery