A MutableList implemented using a backing Array. Also:

  • a Stack, where the top of the stack is the last element of the list, and
  • a Queue, where the front of the queue is the first element of the list and the back of the queue is the last element of the list.

The size of the backing Array is called the capacity of the ArrayList. The capacity of a new instance is specified by the given initialCapacity. The capacity is increased when size exceeds the capacity. The new capacity is the product of the current capacity and the given growthFactor.

By: Gavin King

no subtypes hierarchy

Constructors
ArrayListSource Codeshared ArrayList(Integer initialCapacity = 0, Float growthFactor = ..., {Element*} elements = ...)

Create a new ArrayList with the given initial elements.

Parameters:
  • initialCapacity = 0

    The initial size of the backing array.

  • growthFactor = 1.5

    The factor used to determine the new size of the backing array when a new backing array is allocated.

  • elements = {}

    The initial elements of the list.

copySource Codeshared copy(ArrayList<Element> arrayList, Float growthFactor = ...)

Create a new ArrayList with the same initial elements as the given arrayList.

Parameters:
  • arrayList

    The ArrayList to copy.

  • growthFactor = 1.5

    The factor used to determine the new size of the backing array when a new backing array is allocated.

ofSizeSource Codeshared ofSize(Integer size, Element element, Float growthFactor = ...)

Create a new ArrayList of the given size, populating every index with the given element. If size<=0, the new list will have no elements.

Parameters:
  • size

    The size of the resulting list. If the size is non-positive, an empty list will be created.

  • element

    The element value with which to populate the list. All elements of the resulting list will have the same value.

  • growthFactor = 1.5

    The factor used to determine the new size of the backing array when a new backing array is allocated.

Attributes
backSource Codeshared actual Element? back

The element currently at the back of the queue, or null if the queue is empty.

Refines Queue.back
capacitySource Codeshared Integer capacity

The size of the backing array, which must be at least as large as the size of the list.

firstSource Codeshared 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
frontSource Codeshared actual Element? front

The element currently at the front of the queue, or null if the queue is empty.

Refines Queue.front
hashSource 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:

  • if x==y then x.hash==y.hash.

Therefore, a class which refines 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 removal of the 32 highest order bits, before returning the value to the caller.

Refines Identifiable.hash ultimately refines Object.hash
lastIndexSource Codeshared 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.

sizeSource Codeshared actual Integer size

The number of elements returned by the iterator of this stream, if the iterator terminates. In the case of an infinite stream, this operation never terminates.

Refines List.size ultimately refines Iterable.size
topSource Codeshared actual Element? top

The element currently at the top of the stack, or null if the stack is empty.

Refines Stack.top
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>
Attributes inherited from: Queue<Element>
Attributes inherited from: Stack<Element>
Methods
acceptSource Codeshared actual Element? accept()

Remove and return the element at the front of the queue.

Refines Queue.accept
addSource Codeshared actual void add(Element element)

Add the given element to the end of this list, incrementing the length of the list.

addAllSource Codeshared actual void addAll({Element*} elements)

Add the given elements to the end of this list, increasing the length of the list.

anySource 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 (selecting). If the stream is empty, returns false. For an infinite stream, this operation might not terminate.

Refines Iterable.any
clearSource Codeshared actual void clear()

Remove every element from this list, leaving an empty list with no elements.

cloneSource Codeshared actual ArrayList<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.

Refines MutableList.clone ultimately refines Collection.clone
containsSource Codeshared 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 most Categorys 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
copyToSource Codeshared void copyTo(ArrayList<Element>|Array<Element?> destination, Integer sourcePosition = 0, Integer destinationPosition = 0, Integer length = ...)

Efficiently copy the elements in the segment sourcePosition:length of this list to the segment destinationPosition:length of the given destination ArrayList or Array.

Parameters:
  • destination

    The list into which to copy the elements.

    • illegal starting position in destination list

  • sourcePosition = 0

    The index of the first element in this array to copy.

    • illegal starting position in source list

  • destinationPosition = 0

    The index in the given array into which to copy the first element.

    • illegal starting position in destination list

  • length = smallest(size - sourcePosition, destination.size - destinationPosition)

    The number of elements to copy.

    • length may not be negative

    • illegal starting position in source list

    • illegal starting position in destination list

countSource Codeshared actual Integer count(Boolean selecting(Element element))

Produces the number of elements in this stream that satisfy the given predicate function (selecting). For an infinite stream, this method never terminates.

deleteSource Codeshared actual Element? delete(Integer index)

Remove the element at the specified index, returning the removed element, if any, or null if there was no such element.

Refines MutableList.delete ultimately refines ListMutator.delete
deleteMeasureSource Codeshared actual void deleteMeasure(Integer from, Integer length)

Remove every element with an index in the measured range from:length.

deleteSpanSource Codeshared actual void deleteSpan(Integer from, Integer to)

Remove every element with an index in the spanned range from..to.

eachSource Codeshared actual void each(void step(Element element))

Call the given function (step) 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.

equalsSource Codeshared actual Boolean equals(Object that)

Determine if two values are equal. 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, function references (Callable), it is acceptable for equals() to be defined to return false for every argument.

Refines Identifiable.equals ultimately refines Object.equals
everySource Codeshared actual Boolean every(Boolean selecting(Element element))

Determines if all elements of this stream satisfy the given predicate function (selecting). If the stream is empty, return true. For an infinite stream, this operation might not terminate.

findSource Codeshared actual Element? find(Boolean selecting(Element&Object element))

The first element of this stream which satisfies the given predicate function (selecting), 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
findLastSource Codeshared actual Element? findLast(Boolean selecting(Element&Object element))

The last element of this stream which satisfies the given predicate function (selecting), 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
firstOccurrenceSource Codeshared actual Integer? firstOccurrence(Element element, Integer from, Integer length)

The first index in this list at which the given value (element) occurs, that falls within the segment from:length defined by the optional starting index (from) and length.

getFromFirstSource Codeshared actual Element? getFromFirst(Integer index)

The indexth element returned by an iterator of this stream, or null if there are fewer than index+1 elements in the stream. For a stream with an unstable iteration order, a different value might be produced each time getFromFirst(index) is called for a given integer index.

Refines List.getFromFirst ultimately refines Iterable.getFromFirst
infillSource Codeshared actual void infill(Element replacement)

Replace all null values in this list with the given replacement value.

insertSource Codeshared actual void insert(Integer index, Element element)

Insert the given element at the specified index, incrementing the length of the list.

Parameters:
  • index
    • index may not be negative or greater than the length of the list

insertAllSource Codeshared actual void insertAll(Integer index, {Element*} elements)

Insert the given elements at the specified index, growing the length of the list by the number of given elements.

Parameters:
  • index
    • index may not be negative or greater than the length of the list

iteratorSource Codeshared actual Iterator<Element> iterator()

An iterator for the elements belonging to this stream.

Refines List.iterator ultimately refines Iterable.iterator
lastOccurrenceSource Codeshared actual Integer? lastOccurrence(Element element, Integer from, Integer length)

The last index in this list at which the given value (element) occurs, that falls within the range size-length-from:length defined by the optional starting index (from), interpreted as a reverse index counting from the end of the list, and length.

measureSource Codeshared actual List<Element> measure(Integer from, Integer length)

Obtain a measure containing the mapped values starting from the given starting index (from), with the given length. If length<=0, the resulting measure is empty.

The measure should contain the given number (length) of elements of this stream, starting from the element at the given starting index (from), in the same order as they are produced by the 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
moveSource Codeshared actual default void move(Integer i, Integer j)

Efficiently move the element of this list 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 list. If the source index is smaller than the destination index, elements are shifted toward the start of the list. If the given indices are identical, no change is made to the list.

Parameters:
  • i
    • index may not be negative or greater than the last index in the list

  • j
    • index may not be negative or greater than the last index in the list

Refines MutableList.move ultimately refines ListMutator.move
occurrencesSource Codeshared actual {Integer*} occurrences(Element element, Integer from, Integer length)

The indexes in this list at which the given value (element) occurs.

occursSource Codeshared actual Boolean occurs(Element element, Integer from, Integer length)

Determines if the given value (element) occurs as an element of this list, at any index that falls within the segment from:length defined by the optional starting index (from) and length.

occursAtSource Codeshared actual Boolean occursAt(Integer index, Element element)

Determines if the given value (element) occurs at the given index in this list.

offerSource Codeshared actual void offer(Element element)

Add a new element to the back of the queue.

Refines Queue.offer
popSource Codeshared actual Element? pop()

Remove and return the element at the top of the stack.

Refines Stack.pop
pruneSource Codeshared actual void prune()

Remove all null elements from this list, leaving a list with no null elements.

pushSource Codeshared actual void push(Element element)

Push a new element onto the top of the stack.

Refines Stack.push
reduceSource Codeshared actual Result|Element|Null reduce<Result>(Result accumulating(Result|Element partial, Element element))

Beginning with the first element of this stream, apply the given combining function (accumulating) 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.

removeSource Codeshared actual Integer remove(Element&Object element)

Remove all occurrences of the given value from this list, returning the number of elements removed.

To remove just one occurrence of the given value, use ListMutator.removeFirst() or ListMutator.removeLast().

removeAllSource Codeshared actual Integer removeAll({Element&Object*} elements)

Remove all occurrences of every one of the given values from this list, returning the number of elements removed.

removeFirstSource Codeshared actual Boolean removeFirst(Element&Object element)

Remove the first occurrence of the given value from this list, if any, returning true if the value occurs in the list, or false otherwise.

removeLastSource Codeshared actual Boolean removeLast(Element&Object element)

Remove the last occurrence of the given value from this list, if any, returning true if the value occurs in the list, or false otherwise.

replaceSource Codeshared actual void replace(Element&Object element, Element replacement)

Replace all occurrences of the given value in this list with the given replacement value.

To replace just one occurrence of the given value, use ListMutator.replaceFirst() or ListMutator.replaceLast().

replaceFirstSource Codeshared actual Boolean replaceFirst(Element&Object element, Element replacement)

Replace the first occurrence of the given value in this list, if any, with the given replacement value, returning true if the value occurs in the list, or false otherwise.

replaceLastSource Codeshared actual Boolean replaceLast(Element&Object element, Element replacement)

Replace the last occurrence of the given value in this list, if any, with the given replacement value, returning true if the value occurs in the list, or false otherwise.

setSource Codeshared actual void set(Integer index, Element element)

Replace the existing element at the specified index with the given element.

Parameters:
  • index
    • index may not be negative or greater than the last index in the list

shrinkSource Codeshared void shrink()

Reduce the capacity of the list to its current size, by allocating a new backing array.

sortInPlaceSource Codeshared void sortInPlace(Comparison comparing(Element&Object x, Element&Object y))

Sorts the elements in this list according to the order induced by the given comparison function. Null elements are sorted to the end of the list. This operation modifies the list.

Parameters:
  • comparing

    A comparison function that compares pairs of non-null elements of the array.

spanSource Codeshared actual List<Element> span(Integer from, Integer to)

Obtain a span containing the elements between the two given indices.

The span should contain elements of this stream, starting from the element at the given starting index (from), and ending with the element at the given ending index (to), in the same order as they are produced by the 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
spanFromSource Codeshared actual List<Element> spanFrom(Integer from)

Obtain a span containing the elements between the given starting index (from) and the last index of this ranged object.

The span should contain elements of this stream, starting from the element at the given starting index (from), in the same order as they are produced by the 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
spanToSource Codeshared actual List<Element> spanTo(Integer to)

Obtain a span containing the elements between the first index of this ranged stream and given end index (to).

The span should contain elements of this stream, up to the element at the given ending index (to), in the same order as they are produced by the 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
swapSource Codeshared actual default void swap(Integer i, Integer j)

Given two indices within this list, swap the positions of the elements at these indices. If the two given indices are identical, no change is made to the list.

Parameters:
  • i
    • index may not be negative or greater than the last index in the list

  • j
    • index may not be negative or greater than the last index in the list

Refines MutableList.swap ultimately refines ListMutator.swap
truncateSource Codeshared actual void truncate(Integer size)

Truncate this list to the given size by removing elements from the end of the list, if necessary, to leave a list with at most the given size.

Parameters:
  • size
    • size >= 0
Inherited Methods
Methods inherited from: Object
Methods inherited from: Category<Element>
Methods inherited from: Collection<Element>
Methods inherited from: Correspondence<Key,Item>
Methods inherited from: Iterable<Element,Absent>
Methods inherited from: List<Element>
Methods inherited from: ListMutator<Element>
Methods inherited from: MutableList<Element>
Methods inherited from: Queue<Element>
Methods inherited from: Ranged<Index,Element,Subrange>
Methods inherited from: SearchableList<Element>
Methods inherited from: Stack<Element>