Collections

A fixed-sized array of mutable elements. An empty array is an array of `size` `0`. An array may be created with a list of initial elements, or, via the constructor `ofSize()`, with a size and single initial value for all elements.

    value array = Array { "hello", "world" };
    value ints = Array.ofSize(1k, 0);

Arrays are mutable. Any element of an array may be set to a new value.

    value array = Array { "hello", "world" };
    array[0] = "goodbye";

Arrays are lists and support all operations inherited from `List`, along with certain additional operations for efficient mutation of the array: `set()`, `swap()`, `move()`, `sortInPlace()`, `reverseInPlace()`, and `copyTo()`.

This class is provided primarily to ease interoperation with Java, and for some performance-critical low-level programming tasks.

On the JVM, for “primitive” element types `Integer`, `Float`, `Byte`, `Character`, and `Boolean`, `Array` is easily the most efficient sort of `List` in Ceylon. However, certain optimizations made by the compiler are impossible if the `Array` is assigned to a more generic type such as `Iterable`. Peak efficiency is obtained for algorithms coded to the static type `Array`.

Furthermore, `Array` is itself a compromise between raw performance, polymorphism, and portability. An instance of the Java primitive array type `java.lang.LongArray` (written `long[]` in Java) exhibits superior micro-level performance to an `Array<Integer>`, but:

- is not a `List`, and
- is not available except when compiling for the JVM.

Fortunately, given a Java primitive array, it's easy to obtain an `Array` backed by the primitive array:

    //unportable JVM-specific code
    LongArray longArray = LongArray(size);
    Array<Integer> array = longArray.integerArray;

- `Anything`
  - `Object`
    - `Basic` ...and other supertypes
      - `Array` ...and other supertypes

- `Array`
  - `Basic`
    - `Identifiable`
    - `Object`
      - `Anything`
  - `IndexedCorrespondenceMutator`
    - `CorrespondenceMutator`
  - `Ranged`
    - `Iterable`
      - `Category`
  - `SearchableList`
    - `List`
      - `Collection`
        - `Iterable`
          - `Category`
      - `Correspondence`
      - `Ranged`
        - `Iterable`
          - `Category`

no subtypes hierarchy

Constructors
`Array` | Source Code `shared Array({Element*} elements)` Create an array with the given `elements`.
`ofSize` | Source Code `shared ofSize(Integer size, Element element)` Create an array of the specified `size`, populating every index with the given `element`. The specified `size` must be no larger than `runtime.maxArraySize`. If `size<=0`, the new array will have no elements. Parameters: `size` The size of the resulting array. If the size is non-positive, an empty array will be created. `element` The element value with which to populate the array. All elements of the resulting array will have the same value. Throws `AssertionError` if `size>runtime.maxArraySize` See also `runtime.maxArraySize` Since 1.2.0

Attributes
`coalesced` | Source Code `shared actual {Element&Object*} coalesced` The non-null elements of this stream, in the order in which they occur in this stream. For null elements of the original stream, there is no entry in the resulting stream. For example, the expression
    { "123", "abc", "456"}.map(parseInteger).coalesced
results in the stream `{ 123, 456 }`. Refines `Iterable.coalesced`
`empty` | Source Code `shared actual Boolean empty` Determines if the stream is empty, that is to say, if the iterator returns no elements. Refines `Collection.empty` ultimately refines `Iterable.empty`
`first` | Source Code `shared actual Element? first` The first element returned by the iterator, if any, or `null` if this stream is empty. For a stream with an unstable iteration order, a different value might be produced each time `first` is evaluated. Refines `List.first` ultimately refines `Iterable.first`
`hash` | Source Code `shared actual Integer hash` The hash value of the value, which allows the value to be an element of a hash-based set or key of a hash-based map. Implementations must respect the constraint that: if `x==y` then `x.hash==y.hash`. Therefore, a class which refines `Object.equals()` must also refine `hash`. In general, `hash` values vary between platforms and between executions of the same program. Note that when executing on a Java Virtual Machine, the 64-bit `Integer` value returned by an implementation of `hash` is truncated to a 32-bit integer value by taking the exclusive disjunction of the 32 lowest-order bits with the 32 highest-order bits, before returning the value to the caller. Refines `Identifiable.hash` ultimately refines `Object.hash`
`last` | Source Code `shared actual Element? last` The last element returned by the iterator, if any, or `null` if this stream is empty. In the case of an infinite stream, this operation never terminates; furthermore, this default implementation iterates all elements, which might be very expensive. Refines `List.last` ultimately refines `Iterable.last`
`lastIndex` | Source Code `shared actual Integer? lastIndex` The index of the last element of the list, or `null` if the list is empty. Always `size>0 then size-1`. Refines `List.lastIndex`
`length` | See `size`
`size` | Source Code `shared actual Integer size` The immutable number of elements of this array. Refines `List.size` ultimately refines `Iterable.size` Aliases: `length`
`string` | Source Code `shared actual String string` A developer-friendly string representing the instance. Concatenates the name of the concrete class of the instance with the `hash` of the instance. Subclasses are encouraged to refine this implementation to produce a more meaningful representation. Refines `Iterable.string` ultimately refines `Object.string`

Inherited Attributes
Attributes inherited from: `Object` `hash`, `string`
Attributes inherited from: `Collection<Element>` `empty`, `permutations`, `string`
Attributes inherited from: `Correspondence<Key,Item>` `keys`
Attributes inherited from: `Iterable<Element,Absent>` `coalesced`, `cycled`, `distinct`, `empty`, `exceptLast`, `first`, `indexed`, `last`, `paired`, `rest`, `size`, `string`
Attributes inherited from: `List<Element>` `first`, `hash`, `keys`, `last`, `lastIndex`, `rest`, `reversed`, `size`

Methods
`any` | Source Code `shared actual Boolean any(Boolean selecting(Element element))` Determines if there is at least one element of this stream that satisfies the given predicate function. If the stream is empty, returns `false`. For an infinite stream, this operation might not terminate. Refines `Iterable.any`
`by` | Source Code `shared actual {Element*} by(Integer step)` Produces a stream containing every `step`th element of this stream. If the step size is `1`, the resulting stream contains the same elements as this stream. For example, the expression
    (0..10).by(3)
results in the stream `{ 0, 3, 6, 9 }`. The step size must be greater than zero. Refines `Iterable.by`
`clone` | Source Code `shared actual Array<Element> clone()` A new array with the same elements as this array. Refines `List.clone` ultimately refines `Collection.clone`
`contains` | Source Code `shared actual Boolean contains(Object element)` Returns `true` if the given value belongs to this `Category`, that is, if it is an element of this `Category`, or `false` otherwise. For any instance `c` of `Category`, `c.contains(element)` may be written using the `in` operator:
    element in c
For most `Category`s, the following relationship is satisfied by every pair of elements `x` and `y`: if `x==y`, then `x in category == y in category` However, it is possible to form a useful `Category` consistent with some other equivalence relation, for example `===`. Therefore implementations of `contains()` which do not satisfy this relationship are tolerated. Refines `List.contains` ultimately refines `Category.contains`
`copyTo` | Source Code `shared void copyTo(Array<in Element> destination, Integer sourcePosition = 0, Integer destinationPosition = 0, Integer length = ...)` Efficiently copy the elements in the measure `sourcePosition:length` of this array to the measure `destinationPosition:length` of the given array, which may be this array. The given `sourcePosition` and `destinationPosition` must be non-negative and, together with the given `length`, must identify meaningful ranges within the two arrays, satisfying: `size >= sourcePosition+length`, and `destination.size >= destinationPosition+length`. If the given `length` is not strictly positive, no elements are copied. Parameters: `destination` The array into which to copy the elements, which may be this array. `sourcePosition = 0` The index of the first element in this array to copy. `destinationPosition = 0` The index in the given array into which to copy the first element. `length = smallest(size - sourcePosition, destination.size - destinationPosition)` The number of elements to copy. Throws `AssertionError` if the arguments do not identify meaningful ranges within the two arrays: if the given `sourcePosition` or `destinationPosition` is negative, if `size < sourcePosition+length`, or if `destination.size < destinationPosition+length`.
`count` | Source Code `shared actual Integer count(Boolean selecting(Element element))` Produces the number of elements in this stream that satisfy the given predicate function. For an infinite stream, this method never terminates. Refines `Iterable.count`
`defines` | Source Code `shared actual Boolean defines(Integer index)` Determines if there is a value defined for the given key. Refines `List.defines` ultimately refines `Correspondence.defines`
`each` | Source Code `shared actual void each(void step(Element element))` Call the given function for each element of this stream, passing the elements in the order they occur in this stream. For example:
    words.each((word) {
        print(word.lowercased);
        print(word.uppercased);
    });
Has the same effect as the following `for` loop:
    for (word in words) {
        print(word.lowercased);
        print(word.uppercased);
    }
For certain streams this method is highly efficient, surpassing the performance of `for` loops on the JVM. Thus, `each()` is sometimes preferred in highly performance-critical low-level code. Refines `Iterable.each`
`equals` | Source Code `shared actual Boolean equals(Object that)` Determine if two values are equal. For any two non-null objects `x` and `y`, `x.equals(y)` may be written as:
    x == y
Implementations should respect the constraints that: if `x===y` then `x==y` (reflexivity), if `x==y` then `y==x` (symmetry), if `x==y` and `y==z` then `x==z` (transitivity). Furthermore it is recommended that implementations ensure that if `x==y` then `x` and `y` have the same concrete class. A class which explicitly refines `equals()` is said to support value equality, and the equality operator `==` is considered much more meaningful for such classes than for a class which simply inherits the default implementation of identity equality from `Identifiable`. Note that an implementation of `equals()` that always returns `false` does satisfy the constraints given above. Therefore, in very rare cases where there is no reasonable definition of value equality for a class, for example, Return(*Arguments) , it is acceptable for `equals()` to be defined to return `false` for every argument. Refines `Identifiable.equals` ultimately refines `Object.equals`
`every` | Source Code `shared actual Boolean every(Boolean selecting(Element element))` Determines if all elements of this stream satisfy the given predicate function. If the stream is empty, return `true`. For an infinite stream, this operation might not terminate. Refines `Iterable.every`
`filter` | Source Code `shared actual {Element*} filter(Boolean selecting(Element element))` Produces a stream containing the elements of this stream that satisfy the given predicate function. For any empty stream, `filter()` returns an empty stream:
    {}.filter(p) == {}
For any nonempty stream `it`, and predicate `p`, the result of `filter()` may be obtained according to this recursive definition:
    it.filter(p) == { if (p(it.first)) it.first }.chain(it.rest.filter(f))
Alternatively, and in practice, `filter()` may be defined by this comprehension:
    it.filter(p) == { for (e in it) if (p(e)) e };
For example, the expression
    (1..100).filter(13.divides)
results in the stream `{ 13, 26, 39, 52, 65, 78, 91 }`. Refines `Iterable.filter`
`find` | Source Code `shared actual Element? find(Boolean selecting(Element&Object element))` The first element of this stream which is not null and satisfies the given predicate function, if any, or `null` if there is no such element. For an infinite stream, this method might not terminate. For example, the expression
    (-10..10).find(Integer.positive)
evaluates to `1`. Refines `List.find` ultimately refines `Iterable.find`
`findLast` | Source Code `shared actual Element? findLast(Boolean selecting(Element&Object element))` The last element of this stream which is not null and satisfies the given predicate function, if any, or `null` if there is no such element. For an infinite stream, this method will not terminate. For example, the expression
    (-10..10).findLast(3.divides)
evaluates to `9`. Refines `List.findLast` ultimately refines `Iterable.findLast`
`firstIndexWhere` | Source Code `shared actual Integer? firstIndexWhere(Boolean selecting(Element&Object element))` The first index in this list for which the element is not null and satisfies the given predicate function. Refines `List.firstIndexWhere`
`firstOccurrence` | Source Code `shared actual Integer? firstOccurrence(Element element, Integer from, Integer length)` The first index in this list at which the given value occurs, that falls within the segment `from:length` defined by the optional starting index and `length`. Refines `SearchableList.firstOccurrence`
`getFromFirst` | Source Code `shared actual Element? getFromFirst(Integer index)` Get the element at the specified index, or `null` if the index falls outside the bounds of this array. Refines `List.getFromFirst` ultimately refines `Iterable.getFromFirst`
`getFromLast` | Source Code `shared actual Element? getFromLast(Integer index)` Get the element at the specified index, where the array is indexed from the end of the array, or `null` if the index falls outside the bounds of this array. Refines `List.getFromLast`
`indexesWhere` | Source Code `shared actual {Integer*} indexesWhere(Boolean selecting(Element&Object element))` The indexes in this list for which the element is not null and satisfies the given predicate function. Refines `List.indexesWhere`
`iterator` | Source Code `shared actual Iterator<Element> iterator()` An iterator for the elements belonging to this stream. If this is a nonempty stream with type `{Element+}`, the iterator must produce at least one element. Refines `List.iterator` ultimately refines `Iterable.iterator`
`lastIndexWhere` | Source Code `shared actual Integer? lastIndexWhere(Boolean selecting(Element&Object element))` The last index in this list for which the element is not null and satisfies the given predicate function. Refines `List.lastIndexWhere`
`lastOccurrence` | Source Code `shared actual Integer? lastOccurrence(Element element, Integer from, Integer length)` The last index in this list at which the given value occurs, that falls within the range `size-length-from:length` defined by the optional starting index, interpreted as a reverse index counting from the end of the list, and `length`. Refines `SearchableList.lastOccurrence`
`locate` | Source Code `shared actual <Integer->Element&Object>? locate(Boolean selecting(Element&Object element))` The first element of this stream which is not null and satisfies the given predicate function, if any, together with its position in the stream, or `null` if there is no such element. For an infinite stream, this method might not terminate. For example, the expression
    (-10..10).locate(Integer.positive)
evaluates to `11->1`. Refines `Iterable.locate`
`locateLast` | Source Code `shared actual <Integer->Element&Object>? locateLast(Boolean selecting(Element&Object element))` The last element of this stream which is not null and satisfies the given predicate function, if any, together with its position in the stream, or `null` if there is no such element. For an infinite stream, this method might not terminate. For example, the expression
    (-10..10).locateLast(3.divides)
evaluates to `19->9`. Refines `Iterable.locateLast`
`locations` | Source Code `shared actual {<Integer->Element&Object>*} locations(Boolean selecting(Element&Object element))` A stream producing all elements of this stream which are not null and which satisfy the given predicate function, together with their positions in the stream. For example, the expression
    (-5..5).locations(3.divides)
evaluates to the stream `{ 2->-3, 5->0, 8->3 }`. Note that this method is more efficient than the alternative of applying `Iterable.filter()` to an `Iterable.indexed` stream. Refines `Iterable.locations`
`measure` | Source Code `shared actual Array<Element> measure(Integer from, Integer length)` Obtain a measure containing the mapped values starting from the given starting index, with the given `length`. If `length<=0`, the resulting measure is empty. For any ranged stream `r`, `r.measure(from, length)` may be written using the measure operator:
    r[from:length]
The measure should contain the given number of elements of this stream, starting from the element at the given starting index, in the same order as they are produced by the `Iterable.iterator()` of the stream. In the case where the iterator would be exhausted before `length` elements are produced, the resulting measure contains only those elements which were produced before the iterator was exhausted, and the length of the measure is less then the given `length`. When the given index does not belong to this ranged object, the behavior is implementation dependent. Refines `List.measure` ultimately refines `Ranged.measure`
`move` | Source Code `shared void move(Integer from, Integer to)` Efficiently move the element of this array at the given source index to the given destination index, shifting every element falling between the two given indices by one position to accommodate the change of position. If the source index is larger than the destination index, elements are shifted toward the end of the array. If the source index is smaller than the destination index, elements are shifted toward the start of the array. If the given indices are identical, no change is made to the array. The array always contains the same elements before and after this operation. Parameters: `from` The source index of the element to move. `to` The destination index to which the element is moved. Throws `AssertionError` if either of the given indices is out of bounds Since 1.2.0
`occurrences` | Source Code `shared actual {Integer*} occurrences(Element element, Integer from, Integer length)` The indexes in this list at which the given value occurs. Refines `SearchableList.occurrences`
`occurs` | Source Code `shared actual Boolean occurs(Element element, Integer from, Integer length)` Determines if the given value occurs as an element of this list, at any index that falls within the segment `from:length` defined by the optional starting index and `length`. Refines `SearchableList.occurs`
`occursAt` | Source Code `shared actual Boolean occursAt(Integer index, Element element)` Determines if the given value occurs at the given index in this list. Refines `SearchableList.occursAt`
`reduce` | Source Code `shared actual Result|Element|Null reduce<Result>(Result accumulating(Result|Element partial, Element element))` Beginning with the `Iterable.first` element of this stream, apply the given combining function to each element of this stream in turn, progressively accumulating a single result. For an empty stream, `reduce()` always returns `null`. For a stream with one element, `reduce()` returns that element:
    { first }.reduce(f) == first
For a given stream `it` with more than one element, and combining function `f`, the result of `reduce()` is obtained according to the following recursive definition:
    it.reduce(f) == f(it.exceptLast.reduce(f), it.last)
For example, the expression
    (1..100).reduce(plus)
results in the integer `5050`. Refines `Iterable.reduce`
`reverseInPlace` | Source Code `shared void reverseInPlace()` Reverses the order of the current elements in this array. This operation works by side-effect, modifying the array. The array always contains the same elements before and after this operation. Since 1.1.0
`sequence` | Source Code `shared actual Element[] sequence()` A sequence containing all the elements of this stream, in the same order they occur in this stream. This operation eagerly evaluates and collects every element of the stream. Refines `Iterable.sequence`
`set` | Source Code `shared actual void set(Integer index, Element element)` Replace the existing element at the specified `index` with the given `element`. Parameters: `index` The index of the element to replace. `element` The new element. Throws `AssertionError` if the given index is out of bounds, that is, if `index<0` or if `index>lastIndex` Refines `IndexedCorrespondenceMutator.set`
`skip` | Source Code `shared actual {Element*} skip(Integer skipping)` Produces a stream containing the elements of this stream, after skipping the first `skipping` elements produced by its iterator. If this stream does not contain more elements than the specified number of elements to skip, the resulting stream has no elements. If the specified number of elements to skip is zero or fewer, the resulting stream contains the same elements as this stream. Refines `Iterable.skip`
`sort` | Source Code `shared actual Element[] sort(Comparison comparing(Element x, Element y))` Sorts the elements in this array according to the order induced by the given comparison function, returning a new sequence. This operation has no side-effect, and does not modify the array. Parameters: `comparing` A comparison function that compares pairs of elements of this array. Refines `Iterable.sort`
`sortInPlace` | Source Code `shared void sortInPlace(Comparison comparing(Element x, Element y))` Sorts the elements in this array according to the order induced by the given comparison function. This operation works by side-effect, modifying the array. The array always contains the same elements before and after this operation. Parameters: `comparing` A comparison function that compares pairs of elements of this array. Since 1.1.0
`span` | Source Code `shared actual Array<Element> span(Integer from, Integer to)` Obtain a span containing the elements between the two given indices. For any ranged stream `r`, `r.span(from, to)` may be written using the span operator:
    r[from..to]
The span should contain elements of this stream, starting from the element at the given starting index, and ending with the element at the given ending index, in the same order as they are produced by the `Iterable.iterator()` of the stream, except when the ending index occurs earlier than the starting index, in which case they occur in the opposite order. When one or both of the given indices does not belong to this ranged stream, the behavior is implementation dependent. Refines `List.span` ultimately refines `Ranged.span`
`spanFrom` | Source Code `shared actual Array<Element> spanFrom(Integer from)` Obtain a span containing the elements between the given starting index and the last index of this ranged object. For any ranged stream `r`, `r.spanFrom(from)` may be written using the span operator:
    r[from...]
The span should contain elements of this stream, starting from the element at the given starting index, in the same order as they are produced by the `Iterable.iterator()` of the stream. When the given index does not belong to this ranged stream, the behavior is implementation dependent. Refines `List.spanFrom` ultimately refines `Ranged.spanFrom`
`spanTo` | Source Code `shared actual Array<Element> spanTo(Integer to)` Obtain a span containing the elements between the first index of this ranged stream and given end index. For any ranged stream `r`, `r.spanTo(to)` may be written using the span operator:
    r[...to]
The span should contain elements of this stream, up to the element at the given ending index, in the same order as they are produced by the `Iterable.iterator()` of the stream. When the given index does not belong to this ranged stream, the behavior is implementation dependent. Refines `List.spanTo` ultimately refines `Ranged.spanTo`
`swap` | Source Code `shared void swap(Integer i, Integer j)` Given two indices within this array, efficiently swap the positions of the elements at these indices. If the two given indices are identical, no change is made to the array. The array always contains the same elements before and after this operation. Parameters: `i` The index of the first element. `j` The index of the second element. Throws `AssertionError` if either of the given indices is out of bounds Since 1.2.0
`take` | Source Code `shared actual {Element*} take(Integer taking)` Produces a stream containing the first `taking` elements of this stream. If the specified number of elements to take is larger than the number of elements of this stream, the resulting stream contains the same elements as this stream. If the specified number of elements to take is fewer than one, the resulting stream has no elements. Refines `Iterable.take`

Inherited Methods
Methods inherited from: `Object` `equals()`
Methods inherited from: `Category<Element>` `contains()`, `containsAny()`, `containsEvery()`
Methods inherited from: `Collection<Element>` `clone()`, `combinations()`, `contains()`
Methods inherited from: `Correspondence<Key,Item>` `defines()`, `definesAny()`, `definesEvery()`, `get()`, `getAll()`
Methods inherited from: `IndexedCorrespondenceMutator<Element>` `set()`
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()`
Methods inherited from: `List<Element>` `clone()`, `collect()`, `contains()`, `defines()`, `endsWith()`, `equals()`, `find()`, `findLast()`, `firstIndexWhere()`, `get()`, `getFromFirst()`, `getFromLast()`, `indexesWhere()`, `initial()`, `iterator()`, `lastIndexWhere()`, `longerThan()`, `mapElements()`, `measure()`, `patch()`, `repeat()`, `shorterThan()`, `slice()`, `span()`, `spanFrom()`, `spanTo()`, `startsWith()`, `sublist()`, `sublistFrom()`, `sublistTo()`, `terminal()`, `trim()`, `trimLeading()`, `trimTrailing()`
Methods inherited from: `Ranged<Index,Element,Subrange>` `measure()`, `span()`, `spanFrom()`, `spanTo()`
Methods inherited from: `SearchableList<Element>` `firstInclusion()`, `firstOccurrence()`, `includes()`, `includesAt()`, `inclusions()`, `lastInclusion()`, `lastOccurrence()`, `occurrences()`, `occurs()`, `occursAt()`