• Vector Literals
• Indexing
• Iterating
• Containment
• Concatenation
• Methods

A vector, vec, is a dynamic array of values.

$vec() -> vec
$vec(arg: iterable) -> vec
$vec(size: i64, fill_value: any) -> vec

Creates a new vector.

• If called with zero arguments, creates an empty vector.
• If called with a single iterable argument, fills the new vector by iterating over the argument.
• If called with two arguments, creates a vector with the specified initial size and fill value.

Vector Literals

You can create a vector using literal syntax, e.g.

var vec = ["foo", "bar", "baz"];

Trailing commas are allowed, e.g.

var vec = [
    "foo",
    "bar",
    "baz",
];

The empty literal [] will create an empty vector.

Indexing

You can index into a vector to get or set entries, e.g.

var vec = ["foo", "bar", "baz"];
assert vec[0] == "foo";
assert vec[1] == "bar";
assert vec[2] == "baz";

vec[2] = "bam";
assert vec[2] == "bam";

Indices are zero-based. A negative index counts backwards from the end of the vector, e.g.

var vec = ["foo", "bar", "baz"];
assert vec[-1] == "baz";
assert vec[-2] == "bar";
assert vec[-3] == "foo";

Iterating

Vectors are iterable, e.g.

for item in ["foo", "bar", "baz"] {
    echo item;
}

Containment

You can check if a vector contains an item using the in operator, e.g.

if "foo" in ["foo", "bar", "baz"] {
    echo "found";
}

This is equivalent to calling the vector's :contains() method.

Concatenation

You can concatenate vectors using the + operator, e.g.

var vec = ["abc", "def"] + ["ghi", "jkl"];

The result is a new vector containing the combined entries from the input vectors.

Methods

:append(*values: any)

Appends the arguments to the vector.

:append_values(arg: iterable)

Appends values from an iterable object.

:clear()

Removes all items from the vector.

:contains(value: any) -> bool

Returns true if the vector contains an item equal to value, otherwise false.

:copy() -> vec

Returns a copy of the vector.

:count() -> i64

Returns the number of entries in the vector.

:filter(callback: callable(any) -> bool) -> vec

Returns a new vector created by mapping the function callback to each element of the vector in turn. callback should be a callable that takes a single argument (the vector element) and returns true or false; if it returns true the corresponding element will be added to the new vector.

:first() -> any

Returns the first item from the vector without removing it. Panics if the vector is empty.

:get(index: i64) -> any

Returns the value at index. Will panic if index is out of range or not an integer.

A negative index counts backwards from the end of the vector.

:index_of(value: any) -> i64|err

Returns the index of the first occurrence of value in the vector. Returns an err if the vector does not contain value.

:insert_at(index: i64, value: any)

Inserts value at the specified index. index must be less than or equal to the vector's item count. Panics if index is out of range.

:is_empty() -> bool

Returns true if the vector is empty.

:is_sorted() -> bool
:is_sorted(callback: callable(any, any) -> bool) -> bool

Returns true if the vector is sorted in ascending order.

• If a callback function is supplied it will be used to compare pairs of values. It should accept two arguments, a and b, and return true if a < b, otherwise false.
• If no callback function is supplied, values will be compared using the < operator. The method will panic if the values are not comparable.

:join() -> str
:join(sep: str) -> str

Joins the vector's elements into a string, with each pair of elements separated by sep. (The separator defaults to an empty string if not specified.)

Elements are automatically stringified — this is equivalent to calling $str() on each element.

Returns an empty string if the vector is empty.

:last() -> any

Returns the last item from the vector without removing it. Panics if the vector is empty.

:map(callback: callable(any) -> any) -> vec

Returns a new vector created by mapping the function callback to each element of the vector in turn. callback should be a callable that takes a single argument (the vector element); its return values will form the elements of the new vector.

:mergesort() -> vec
:mergesort(callback: callable(any, any) -> bool) -> vec

Sorts the vector in-place using a stable implementation of the mergesort algorithm. Returns the vector to allow chaining.

• If a callback function is supplied it will be used to compare pairs of values. It should accept two arguments, a and b, and return true if a < b, otherwise false.
• If no callback function is supplied, values will be compared using the < operator. The method will panic if the values are not comparable.

Use :sort() if you don't care about the underlying sorting algorithm.

:quicksort() -> vec
:quicksort(callback: callable(any, any) -> bool) -> vec

Sorts the vector in-place using the quicksort algorithm. Returns the vector to allow chaining.

• If a callback function is supplied it will be used to compare pairs of values. It should accept two arguments, a and b, and return true if a < b, otherwise false.
• If no callback function is supplied, values will be compared using the < operator. The method will panic if the values are not comparable.

Use :sort() if you don't care about the underlying sorting algorithm.

:random() -> any

Returns a random item from the vector without removing it. Panics if the vector is empty.

Use :remove_random() to remove and return a random item from the vector.

:remove_at(index: i64) -> any

Removes and returns the value at the specified index. Panics if the index is out of range.

:remove_first() -> any

Removes and returns the first item from the vector. Panics if the vector is empty.

:remove_last() -> any

Removes and returns the last item from the vector. Panics if the vector is empty.

:remove_random() -> any

Removes and returns a random item from the vector. Panics if the vector is empty.

Use :random() to return a random item from the vector without removing it.

:reverse() -> vec

Reverses the vector in-place. Returns the vector to enable chaining.

:set(index: i64, value: any)

Sets the value at index. Will panic if index is out of range or not an integer.

A negative index counts backwards from the end of the vector.

:shuffle() -> vec

Shuffles the vector in-place using Fisher-Yates/Durstenfeld shuffling. Returns the vector to enable chaining.

:slice(start_index: i64) -> vec
:slice(start_index: i64, length: i64) -> vec

Copies a slice of the source vector and returns it as a new vector. The source vector is left unchanged.

If start_index is negative, counts backwards from the end of the vector — i.e. a start_index of -1 refers to to the last item in the vector.

If length is omitted, copies to the end of the source vector.

Panics if either argument is out of range.

:sort() -> vec
:sort(callback: callable(any, any) -> bool) -> vec

Sorts the vector in-place using the default stable sorting algorithm. Returns the vector to allow chaining.

• If a callback function is supplied it will be used to compare pairs of values. It should accept two arguments, a and b, and return true if a < b, otherwise false.
• If no callback function is supplied, values will be compared using the < operator. The method will panic if the values are not comparable.

:values() -> iter

Returns an iterator over the vector's values.