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:
List
, andFortunately, 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;
no subtypes hierarchy
Constructors | |
Array | Source Codeshared Array({Element*} elements) Create an array with the given |
ofSize | Source Codeshared ofSize(Integer size, Element element) Create an array of the specified Parameters:
Throws
See also runtime.maxArraySize Since 1.2.0 |
Attributes | |
coalesced | Source Codeshared 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 Refines Iterable.coalesced |
empty | Source Codeshared actual Boolean empty Determines if the stream is empty, that is to say, if the iterator returns no elements. |
first | Source Codeshared actual Element? first The first element returned by the iterator, if any, or
|
hash | Source Codeshared 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:
Therefore, a class which refines In general, Note that when executing on a Java Virtual Machine, the
64-bit |
last | Source Codeshared actual Element? last The last element returned by the iterator, if any, or
|
lastIndex | Source Codeshared actual Integer? lastIndex The index of the last element of the list, or Refines List.lastIndex |
length | See size |
size | Source Codeshared actual Integer size The immutable number of elements of this array. Aliases: length |
string | Source Codeshared actual String string A developer-friendly string representing the instance.
Concatenates the name of the concrete class of the
instance with the |
Inherited Attributes |
Attributes inherited from: Object |
Attributes inherited from: Collection<Element> |
Attributes inherited from: Correspondence<Key,Item> |
Attributes inherited from: Iterable<Element,Absent> |
Attributes inherited from: List<Element> |
Methods | |
any | Source Codeshared 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
Refines Iterable.any |
by | Source Codeshared actual {Element*} by(Integer step) Produces a stream containing every For example, the expression (0..10).by(3) results in the stream The step size must be greater than zero. Refines Iterable.by |
clone | Source Codeshared actual Array<Element> clone() A new array with the same elements as this array. |
contains | Source Codeshared actual Boolean contains(Object element) Returns For any instance element in c For most
However, it is possible to form a useful |
copyTo | Source Codeshared void copyTo(Array<in Element> destination, Integer sourcePosition = 0, Integer destinationPosition = 0, Integer length = ...) Efficiently copy the elements in the measure
The given
If the given Parameters:
Throws
|
count | Source Codeshared 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 Codeshared actual Boolean defines(Integer index) Determines if there is a value defined for the given key. |
each | Source Codeshared 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 (word in words) { print(word.lowercased); print(word.uppercased); } For certain streams this method is highly efficient,
surpassing the performance of Refines Iterable.each |
equals | Source Codeshared actual Boolean equals(Object that) Determine if two values are equal. For any two non-null objects x == y Implementations should respect the constraints that:
Furthermore it is recommended that implementations
ensure that if A class which explicitly refines Note that an implementation of |
every | Source Codeshared 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 Refines Iterable.every |
filter | Source Codeshared 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(p) == {} For any nonempty stream it.filter(p) == { if (p(it.first)) it.first }.chain(it.rest.filter(f)) Alternatively, and in practice, it.filter(p) == { for (e in it) if (p(e)) e }; For example, the expression (1..100).filter(13.divides) results in the stream Refines Iterable.filter |
find | Source Codeshared 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 For example, the expression (-10..10).find(Integer.positive) evaluates to |
findLast | Source Codeshared 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 For example, the expression (-10..10).findLast(3.divides) evaluates to |
firstIndexWhere | Source Codeshared 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 Codeshared 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
Refines SearchableList.firstOccurrence |
getFromFirst | Source Codeshared actual Element? getFromFirst(Integer index) Get the element at the specified index, or |
getFromLast | Source Codeshared actual Element? getFromLast(Integer index) Get the element at the specified index, where the array
is indexed from the end of the array, or Refines List.getFromLast |
indexesWhere | Source Codeshared 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 Codeshared actual Iterator<Element> iterator() An iterator for the elements belonging to this stream. If this is a nonempty stream with type |
lastIndexWhere | Source Codeshared 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 Codeshared 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
Refines SearchableList.lastOccurrence |
locate | Source Codeshared 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
For example, the expression (-10..10).locate(Integer.positive) evaluates to Refines Iterable.locate |
locateLast | Source Codeshared 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
For example, the expression (-10..10).locateLast(3.divides) evaluates to Refines Iterable.locateLast |
locations | Source Codeshared 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 Note that this method is more efficient than the
alternative of applying Refines Iterable.locations |
measure | Source Codeshared actual Array<Element> measure(Integer from, Integer length) Obtain a measure containing the mapped values starting
from the given starting index, with the given
For any ranged stream 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 When the given index does not belong to this ranged object, the behavior is implementation dependent. |
move | Source Codeshared 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:
Throws
Since 1.2.0 |
occurrences | Source Codeshared 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 Codeshared 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 Refines SearchableList.occurs |
occursAt | Source Codeshared 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 Codeshared actual Result|Element|Null reduce<Result>(Result accumulating(Result|Element partial, Element element)) Beginning with the For an empty stream, For a stream with one element, { first }.reduce(f) == first For a given stream it.reduce(f) == f(it.exceptLast.reduce(f), it.last) For example, the expression (1..100).reduce(plus) results in the integer Refines Iterable.reduce |
reverseInPlace | Source Codeshared 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 Codeshared 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. If this stream is known to be nonempty, that is, if it
is an instance of [String+] bits = "hello world".split().sequence(); Refines Iterable.sequence |
set | Source Codeshared actual void set(Integer index, Element element) Parameters:
Throws
Refines IndexedCorrespondenceMutator.set |
skip | Source Codeshared actual {Element*} skip(Integer skipping) Produces a stream containing the elements of this
stream, after skipping the first 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 Codeshared 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. Refines Iterable.sort |
sortInPlace | Source Codeshared 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. Since 1.1.0 |
span | Source Codeshared actual Array<Element> span(Integer from, Integer to) Obtain a span containing the elements between the two given indices. For any ranged stream 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 When one or both of the given indices does not belong to this ranged stream, the behavior is implementation dependent. |
spanFrom | Source Codeshared 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[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 When the given index does not belong to this ranged stream, the behavior is implementation dependent. |
spanTo | Source Codeshared 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[...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 When the given index does not belong to this ranged stream, the behavior is implementation dependent. |
swap | Source Codeshared 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:
Throws
Since 1.2.0 |
take | Source Codeshared actual {Element*} take(Integer taking) Produces a stream containing the first 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 |