Collections

An iterable collection of elements of finite `Iterable.size`, with a well-defined notion of value equality. `Collection` is the abstract supertype of `List`, `Map`, and `Set`.

A `Collection` forms a `Category` of its elements, and is `Iterable`. The elements of a collection are not necessarily distinct when compared using `Object.equals()`.

A `Collection` may be cloned. If a collection is immutable, it is acceptable that `clone()` produce a reference to the collection itself. If a collection is mutable, `clone()` should produce a collection containing references to the same elements, with the same structure as the original collection—that is, it should produce a shallow copy of the collection.

All `Collection`s are required to support a well-defined notion of value equality, but the definition of equality depends upon the kind of collection. Equality for `Map`s and `Set`s has a quite different definition to equality for `List`s. Instances of two different kinds of collection are never equal—for example, a `Map` is never equal to a `List`.

See also `List`, `Map`, `Set`

no type hierarchy

- `Collection`
  - `Iterable`
    - `Category`

- `Collection`
  - `List`
    - `SearchableList`
      - `Array`
      - `String`
      - `StringBuilder`
    - `Sequential`
      - `Empty`
        - `empty`
      - `Sequence`
        - `ArraySequence`
        - `Range`
        - `Singleton`
        - `Tuple`
  - `Map`
    - `emptyMap`
  - `Set`
    - `emptySet`

Attributes
`empty` | Source Code `shared actual default Boolean empty` Determine if the collection is empty, that is, if it has no elements. Refines `Iterable.empty`
`permutations` | Source Code `shared {[Element+]*} permutations` The permutations of this collection, as a stream of nonempty sequences. That is, a stream producing every distinct ordering of the elements of this collection. For example,
    "ABC".permutations.map(String)
is the stream of strings `{ "ABC", "ACB", "BAC", "BCA", "CAB", "CBA" }`. If this collection is empty, the resulting stream is empty. The permutations are enumerated lexicographically according to the order in which each distinct element of this collection is first produced by its iterator. No permutation is repeated. Two elements are considered distinct if either: they are both instances of `Object`, and are unequal, or one element is an `Object` and the other is `null`. Since 1.2.0
`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 collection is empty. If the collection iterator produces the value `null`, the string representation contains the string `"<null>"`. Refines `Iterable.string` ultimately refines `Object.string`

Inherited Attributes
Attributes inherited from: `Object` `hash`, `string`
Attributes inherited from: `Iterable<Element,Absent>` `coalesced`, `cycled`, `distinct`, `empty`, `exceptLast`, `first`, `indexed`, `last`, `paired`, `rest`, `size`, `string`

Methods
`clone` | Source Code `shared formal Collection<Element> clone()` A shallow copy of this collection, that is, a collection with identical elements which does not change if this collection changes. If this collection is immutable, it is acceptable to return a reference to this collection. If this collection is mutable, a newly instantiated collection must be returned.
`combinations` | Source Code `shared {[Element+]*} combinations(Integer length)` The combinations of elements of this collection, of the given positive size, as a stream of nonempty sequences. That is, a stream producing every distinct selection of `length` elements of this collection. For example,
    "ABCD".combinations(2).map(String)
is the stream of strings `{ "AB", "AC", "AD", "BC", "BD", "CD" }`. If this collection is empty, the resulting stream is empty. The combinations are enumerated lexicographically according to the order in which each distinct element of this collection is first produced by its iterator. No combination is repeated. Two elements are considered distinct if either: they are both instances of `Object`, and are unequal, or one element is an `Object` and the other is `null`. Parameters: `length` The number of distinct elements in each combination length must be strictly positive Throws `AssertionError` if `length` is nonpositive or if `length` is larger than the number of distinct elements of this collection Since 1.3.0
`contains` | Source Code `shared actual default Boolean contains(Object element)` Return `true` if the given object is an element of this collection. In this default implementation, and in most refining implementations, return `false` otherwise. An acceptable refining implementation may return `true` for objects which are not elements of the collection, but this is not recommended. (For example, the `contains()` method of `String` returns `true` for any substring of the string.) Refines `Iterable.contains` ultimately refines `Category.contains`

Inherited Methods
Methods inherited from: `Object` `equals()`
Methods inherited from: `Category<Element>` `contains()`, `containsAny()`, `containsEvery()`
Methods inherited from: `Iterable<Element,Absent>` `any()`, `by()`, `chain()`, `collect()`, `contains()`, `count()`, `defaultNullElements()`, `each()`, `every()`, `filter()`, `find()`, `findLast()`, `flatMap()`, `fold()`, `follow()`, `frequencies()`, `getFromFirst()`, `group()`, `indexes()`, `interpose()`, `iterator()`, `locate()`, `locateLast()`, `locations()`, `longerThan()`, `map()`, `max()`, `narrow()`, `partition()`, `product()`, `reduce()`, `repeat()`, `scan()`, `select()`, `sequence()`, `shorterThan()`, `skip()`, `skipWhile()`, `sort()`, `spread()`, `summarize()`, `tabulate()`, `take()`, `takeWhile()`