class Vector<+T>

A mutable, growable sequence of items with O(1) lookup/update and amortized O(1) appending of items.

Notes

Vector is represented as a contiguous block of memory and supports random access by integer index for indices in the range 0 (inclusive) up to the vector's size() (exclusive).

Static Methods

Creating a Vector

static fun sourcemcreate(capacity: Int): mutable this

Create a mutable Vector with the given capacity.

static fun sourcecreateFromItems<I: readonly Sequence<T>>(items: I): this

Create a Vector containing the given items.

static fun sourcemcreateFromItems<I: readonly Sequence<T>>(items: I): mutable this

static fun sourcecreateFromIterator<I: mutable Iterator<T>>(items: I): this

Create a Vector filled with the items of an iterator.

static fun sourcemcreateFromIterator<I: mutable Iterator<T>>(items: I): mutable this

static fun sourcereverseFromIterator<I: mutable Iterator<T>>(items: I): this

Create a Vector filled with the items of an iterator in reverse order. Throws if the iterator does not yield exactly its reported number of items.

static fun sourcemreverseFromIterator<I: mutable Iterator<T>>(items: I): mutable this

static fun sourcefill(size: Int, value: T): this

Create a vector of the given size with all indices set to the given value.

static fun sourcemfill(size: Int, value: T): mutable this

static fun sourcefillBy(size: Int, f: (Int) -> T): this

Create a vector of the given size with each index set to the result of calling the function with the index.

static fun sourcemfillBy(size: Int, f: (Int) -> T): mutable this

Methods

Copying a Vector

readonly fun sourceclone(reserveCapacity: Int): mutable this

Returns a mutable, shallow copy of this Vector. The returned Vector is sized to fit exactly the number of items in this vector, plus the optional reserveCapacity number of additional items.

readonly fun sourcechill(): this

Sizing

readonly fun sourcesize(): Int

Returns the number of items contained in this vector

mutable fun sourcecapacity(): Int

Returns the total number of items that can fit in the Vector's internal storage without allocating new space. To determine the number of additional items that can be added without allocating, use capacity() - size(). NOTE: Making capacity observable on frozen values prevents optimizations such as shrinking to fit on freeze. By making it mutable we preserve option value to add such optimizations in the future.

mutable fun sourceensureCapacity(capacity: Int): Void

Grow the Vector's internal storage as necessary to accommodate the given (absolute) capacity. This method may allocate more storage than requested: if the method succeeds the Vector's capacity will be equal or greater than the given capacity.

mutable fun sourceclear(): Void

Remove all items from this Vector. The Vector's internal storage is not affected (ie the Vector's capacity does not change).

mutable fun sourceresize(newSize: Int, value: T): Void

Expand or shrink the vector to the given size. If the new size is larger than the current size, indices between the old and new size are set to the given filler value.

Accessing Items

readonly fun sourceget(index: Int): T

Get the item at the given index, throws if the index is out of bounds.

readonly fun sourcemaybeGet(index: Int): Option<T>

Get the item at the given index as Some() or return None() if the index is out of bounds.

Adding/Changing/Removing Items

mutable fun sourceset(index: Int, value: T): Void

Set the value at the given index. Throws if the index is out of bounds. NOTE: To add items to the end of a container use push().

mutable fun sourcepush(value: T): Void

Add the value to the end of the container, growing the container's internal storage if necessary to make space for the item.

mutable fun sourcepop(): T

Remove the last item of the container and return it. Throws if the container is empty.

mutable fun sourcemaybePop(): Option<T>

Remove the last item of the container and return it as Some() if non-empty, otherwise returns None().

mutable fun sourceextend<I: readonly Sequence<T>>(second: I): Void

Append all of items from the given sequence to the end of this container.

mutable fun sourceinsert(index: Int, value: T): Void

Inserts the value at the given index, shifting over existing elements to make room for the new element. Grows internal storage if necessary: throws if the index is out of bounds. NOTE: unlike set(), insert() allows inserting at index == size

mutable fun sourcedelete(index: Int): Void

Deletes the value at the given index, shifting over elements after that index to fill the gap. Throws if the index is out of bounds.

mutable fun sourcesplice<I: readonly Sequence<T>>(start: Int, end: Int, src: I): Void

Deletes the items in the range of start (inclusive) to end (exclusive) and inserts the items from the second sequence at the start index. If second is smaller than the length of the slice denoted by start/end, then subsequent items will be shifted left to fill any gaps. If second is larger than the start-end slice, then subsequent items will be shifted right to make room.

Visual Example:

Before:
  [ ...prefix, ...start-end, ...suffix ]

After:
  [ ...prefix, ...second, ...suffix ]

mutable fun sourcekeepWhere(p: (T) -> Bool): Void

Remove all items from this sequence for which the predicate returns false, keeping only those items for which the predicate returns true.

Reordering Items

mutable fun sourcereverse(): Void

Reverses the order of the items in this Vector.

mutable fun sourceshuffle(rng: mutable Random): Void

Randomize the order of items in this Vector using a pseudo-random generator initialized with the given seed. For a collection of Hashable values, a deterministic random value can be initialized with:

rng = Random::mcreate(vector.hash());

mutable fun sourcesortBy<K: readonly Orderable>(selector: (T) ~> K, compare: (K, K) ~> Order): Void

Sorts the items in place, using the given predicate to determine ordering. To sort a collection of non-Orderable items, use Orderable.create():

a: Vector = Vector[...]; compareFn = (a: NonOrderable, b: NonOrderable): Order ~> { ... }; b = a.sortBy(x ~> Orderable.create(x, compareFn));

Selecting Portions of a Sequence

readonly fun sourceslice(start: Int, end: Int): this

Returns the items of this container from the start index (inclusive) up to the end index (exclusive). The start/end values may be negative, in which case they refer to the nth index before the end of the container. For example, x.slice(0, -2) is equivalent to x.slice(0, x.size() - 2).

readonly fun sourcedifference<S: readonly Sequence<T>>(second: S): this

Returns the items of this container that do not appear in the second sequence.

readonly fun sourceintersection<S: readonly Sequence<T>>(second: S): this

Return the items of this container that appear in the second sequence.

readonly fun sourceunique(): this

Return the unique items of this container.

readonly fun sourcesample(rng: mutable Random, count: Int): this

Returns up to N items randomly sampled from this Vector using a pseudo-random generator initialized with the given seed. Returns all items if N is greater than or equal to the size of the container. For a collection of Hashable values, a deterministic random value can be initialized with:

rng = Random::mcreate(vector.hash());

Iteration

readonly fun sourceeach(f: (T) -> Void): Void

Calls the given function once per element of this sequence.

untracked readonly fun sourceeachUntracked(f: (T) -> Void): Void

Calls the given function once per element of this sequence.

Aggregation

readonly fun sourcefind(p: (T) -> Bool): Option<T>

Returns Some(x) for the first item in this sequence that matches the predicate, or None() if no items match.

readonly fun sourcesumInt(): Int

readonly fun sourcesumFloat(): Float

readonly fun sourcemaxBy<K: readonly Orderable>(selector: (T) ~> K): Option<T>

readonly fun sourceminBy<K: readonly Orderable>(selector: (T) ~> K): Option<T>

readonly fun sourcejoin(separator: String): String

Composition

readonly fun sourcemap<U>(s: (T) -> U): Vector<U>

Returns a new sequence representing the results of calling the selection function on each element of this sequence.

untracked readonly fun sourcemapUntracked<U>(s: (T) -> U): Vector<U>

Returns a new sequence representing the results of calling the selection function on each element of this sequence.

readonly fun sourcemapWithIndex<U>(s: (Int, T) -> U): Vector<U>

Similar to map(), but calls the callback with (index, item) for each item in this sequence.

readonly fun sourcemapAcc<R, U>(f: (R, T) -> (R, U), acc: R): (R, Vector<U>)

readonly fun sourceflatMap<U>(s: (T) -> Sequence<U>): Vector<U>

Returns a new sequence representing the results of calling the selection function on each element to map each element to a sequence, and (conceptually) flattening the resulting sequences.

readonly fun sourceflatten<U>(): Vector<U>

When the items of this sequence are themselves sequences, returns a new sequence that contains all the items from all of the inner sequences.

readonly fun sourcefilter(p: (T) -> Bool): Vector<T>

Returns a new sequence representing all the elements of this sequence for which the predicate returns true.

readonly fun sourcefilterNone<U>(): Vector<U>

When the items of this sequence are Options, returns a new sequence containing the inner values of items that are Some():

Before: Vector[None(), None(), Some(2), None(), Some(4)] After: Vector[2, 4]

readonly fun sourcezipWith<U, V, S: readonly Sequence<U>>(other: S, s: (T, U) -> V): Vector<V>

Returns a new sequence representing the results of calling the selection function with tuples of the ith elements of this and the second sequence.

readonly fun sourcedrop(n: Int): Vector<T>

Returns a new sequence representing the elements of this sequence after the nth element.

readonly fun sourcedropWhile(p: (T) -> Bool): Vector<T>

Returns a new sequence representing the elements of this sequence after the contiguous prefix for which the predicate returns true.

readonly fun sourcetake(n: Int): Vector<T>

Returns a new sequence representing the first n elements of this.

readonly fun sourcetakeWhile(p: (T) -> Bool): Vector<T>

Returns a new sequence representing the contiguous prefix of elements from this for which the predicate returns true.

readonly fun sourceconcat<U, S: readonly Sequence<U>>(second: S): Vector<U>

Returns a new Vector containing the items of this sequence followed by the items of the second sequence.

readonly fun sourcereversed(): Vector<T>

Returns a new sequence representing the items of this sequence in reverse order.

readonly fun sourcesorted(compare: (T, T) ~> Order): Vector<T>

Returns a new sequence representing the items of this sequence in sorted order, using their default ordering. To sort a collection of non-Orderable items, use sortedBy().

readonly fun sourcesortedBy<K: readonly Orderable>(selector: (T) ~> K, compare: (K, K) ~> Order): Vector<T>

Returns a new sequence representing the items of this sequence in sorted order, using the given predicate to determine ordering. To sort a collection of non-Orderable items, use Orderable.create():

a: Vector = Vector[...]; compareFn = (a: NonOrderable, b: NonOrderable): Order ~> { ... }; b = a.sortedBy(x ~> Orderable.create(x, compareFn));

Transforming To Different Sequence Types

fun sourcegen<U: frozen>(): ^Vector<U>

Async

frozen fun sourcegenMap<U: frozen>(s: (T) ~> ^U): ^Vector<U>

frozen fun sourcegenFilter(p: (T) ~> ^Bool): ^Vector<T>

frozen fun sourcegenFind(p: (T) ~> ^Bool): ^Option<T>

Extension Methods

frozen fun sourceparallelMap<U>(f: (T) ~> U): Vector<U>

Methods unique to Vector and not inherited from Seq/IndexedSequence. Returns a new Vector with the results of applying the selection function in parallel to each item of this Vector.

readonly fun sourcetoArray(): Array<T>

Returns an Array with the items of this Vector.

Iterators

readonly fun sourcekeys(): mutable Iterator<Int>

Returns an Iterator that yields the range of numbers from 0 (inclusive) to the size of this vector (exclusive) - ie of [0, size).

readonly fun sourcevalues(): mutable Iterator<T>

Returns an Iterator that yields the values contained in this vector.

readonly fun sourceitems(): mutable Iterator<(Int, T)>

Returns an Iterator that yields tuples of (index, value), where index is the zero-based index of the value within this vector.

readonly fun sourcereversedValues(): mutable Iterator<T>

Returns an Iterator that yields the values of this Vector in reverse order.

Trait Implementations

readonly fun sourcetoString(): String

readonly fun sourcehash(): Int

readonly fun sourceinspect(): Inspect

readonly fun source<<U: Orderable>(other: readonly Vector<U>): Bool

readonly fun source><U: Orderable>(other: readonly Vector<U>): Bool

readonly fun source<=<U: Orderable>(other: readonly Vector<U>): Bool

readonly fun source>=<U: Orderable>(other: readonly Vector<U>): Bool

readonly fun source==<U: Equality>(other: readonly Vector<U>): Bool

readonly fun source!=<U: Equality>(other: readonly Vector<U>): Bool

readonly fun sourcecompare<U: Orderable>(other: readonly Vector<U>): Order

readonly fun sourceeachWhileImpl(f: (T) -> Bool): Void

Internal helper for iteration guarding against concurrent modifiction.

untracked readonly fun sourceeachWhileImplUntracked(f: (T) -> Bool): Void

Internal helper for iteration guarding against concurrent modifiction.

Inherited Methods

static fun sourcemeta<U, C: MetaClass<U>>(itemClass: C): VectorMetaClass<U, C>

static fun sourcegenerator<U>(generator: QuickCheck.Generator<U>): QuickCheck.Generator<Vector<U>>

fun sourceperturb(rng: mutable Random): Void

fun sourceshrink(firstShrink: Bool): mutable Iterator<Vector<T>>