Skip to content
Download
API reference

PackedStringArray

A packed array of Strings ([]String in Grost).

An array specifically designed to hold Strings. Packs data tightly, so it saves memory for large array sizes.

If you want to join the strings in the array, use String.join().

string_array : []String = ["hello", "world"]
text : String = " ".join(string_array)
print(text) # "hello world"

In Grost this array is written []String: an array of strings stores them packed, one after another, with no Variant each. It has Array’s methods (map(), filter(), reduce(), sort_custom()…), and what finds no element in an empty array (front(), pop_back(), min()…) is an Option[String]. The engine takes and gives it as it is, without converting each value.

Note: Packed arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use duplicate(). This is not the case for built-in properties and methods. In these cases the returned packed array is a copy, and changing it will not affect the original value. To update a built-in property of this type, modify the returned array and then assign it to the property again.

Note: In a boolean context, a packed array will evaluate to false if it’s empty. Otherwise, a packed array will always evaluate to true.

ReturnsMethod
boolall(method)
boolany(method)
voidappend(value)
voidappend_array(array)
Variantback()
intbsearch(value, before)
intbsearch_custom(value, func, before)
voidclear()
intcount(value)
[]Stringduplicate()
boolerase(value)
voidfill(value)
[]Stringfilter(method)
intfind(value, from)
intfind_custom(method, from)
Variantfront()
Stringget(index)
boolhas(value)
intinsert(at_index, value)
boolis_empty()
Arraymap(method)
Variantmax()
Variantmin()
Variantpick_random()
Variantpop_at(position)
Variantpop_back()
Variantpop_front()
voidpush_back(value)
voidpush_front(value)
Variantreduce(method, accum)
voidremove_at(index)
intresize(new_size)
voidreverse()
intrfind(value, from)
intrfind_custom(method, from)
voidset(index, value)
voidshuffle()
intsize()
[]Stringslice(begin, end)
voidsort()
voidsort_custom(func)
[]u8to_byte_array()

bool all(method: Callable) const

Calls method with each element and returns true if it returns true for all of them (or the array is empty). As Array.all().

bool any(method: Callable) const

Calls method with each element and returns true as soon as it returns true for one of them. As Array.any().

void append(value: String)

Appends an element at the end of the array (alias of push_back()).

void append_array(array: []String)

Appends a []String at the end of this array.

Variant back() const

Returns the last element. In Grost it is an Option[String]: none when the array is empty.

int bsearch(value: String, before: bool = true) const

Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search. Optionally, a before specifier can be passed. If false, the returned index comes after all existing entries of the value in the array.

Note: Calling bsearch() on an unsorted array results in unexpected behavior.

int bsearch_custom(value: String, func: Callable, before: bool = true) const

Finds where value goes in an array sorted by func (which returns true when its first argument goes before the second), with a binary search. As Array.bsearch_custom().

void clear()

Clears the array. This is equivalent to using resize() with a size of 0.

int count(value: String) const

Returns the number of times an element is in the array.

[]String duplicate() const

Creates a copy of the array, and returns it.

bool erase(value: String)

Removes the first occurrence of a value from the array and returns true. If the value does not exist in the array, nothing happens and false is returned. To remove an element by index, use remove_at() instead.

void fill(value: String)

Assigns the given value to all elements in the array. This can typically be used together with resize() to create an array with a given size and initialized elements.

[]String filter(method: Callable) const

Returns a new array of the same type ([]String in Grost) with the elements for which method returns true. As Array.filter().

int find(value: String, from: int = 0) const

Searches the array for a value and returns its index or -1 if not found. Optionally, the initial search index can be passed.

int find_custom(method: Callable, from: int = 0) const

Returns the index of the first element, from from, for which method returns true, or -1. As Array.find_custom().

Variant front() const

Returns the first element. In Grost it is an Option[String]: none when the array is empty.

String get(index: int) const

Returns the String at the given index in the array. If index is out-of-bounds or negative, this method fails and returns an empty string.

This method is similar (but not identical) to the [] operator. Most notably, when this method fails, it doesn’t pause project execution if run from the editor.

bool has(value: String) const

Returns true if the array contains value.

int insert(at_index: int, value: String)

Inserts a new element at a given position in the array. The position must be valid, or at the end of the array (idx == size()).

bool is_empty() const

Returns true if the array is empty.

Array map(method: Callable) const

Returns an Array with what method returns for each element. As Array.map().

Variant max() const

Returns the largest element. In Grost it is an Option[String]: none when the array is empty.

Variant min() const

Returns the smallest element. In Grost it is an Option[String]: none when the array is empty.

Variant pick_random() const

Returns a random element. In Grost it is an Option[String]: none when the array is empty.

Variant pop_at(position: int)

Removes the element at position (negative counts from the end) and returns it. In Grost it is an Option[String]: none when the array is empty.

Variant pop_back()

Removes the last element and returns it. In Grost it is an Option[String]: none when the array is empty.

Variant pop_front()

Removes the first element and returns it. In Grost it is an Option[String]: none when the array is empty.

void push_back(value: String)

Appends a string element at end of the array.

void push_front(value: String)

Inserts value at the start of the array.

Variant reduce(method: Callable, accum: Variant = null) const

Calls method with the value so far and each element, in order, and returns the last result. accum is the start value (without one, the first element). As Array.reduce(). In Grost, with a lambda and a start value of the type it returns, the result has that type (values.reduce(fn(a : int, b : int) => a + b, 0) is an int).

void remove_at(index: int)

Removes an element from the array by index.

int resize(new_size: int)

Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling resize() once and assigning the new values is faster than adding new elements one by one.

Returns OK on success, or one of the following Error constants if this method fails: ERR_INVALID_PARAMETER if the size is negative, or ERR_OUT_OF_MEMORY if allocations fail. Use size() to find the actual size of the array after resize.

void reverse()

Reverses the order of the elements in the array.

int rfind(value: String, from: int = -1) const

Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array.

int rfind_custom(method: Callable, from: int = -1) const

Returns the index of the last element, from from backwards, for which method returns true, or -1. As Array.rfind_custom().

void set(index: int, value: String)

Changes the String at the given index.

void shuffle()

Puts the elements in a random order.

int size() const

Returns the number of elements in the array.

[]String slice(begin: int, end: int = 2147483647) const

Returns the slice of the []String, from begin (inclusive) to end (exclusive), as a new []String.

The absolute value of begin and end will be clamped to the array size, so the default value for end makes it slice to the size of the array by default (i.e. arr.slice(1) is a shorthand for arr.slice(1, arr.size())).

If either begin or end are negative, they will be relative to the end of the array (i.e. arr.slice(0, -2) is a shorthand for arr.slice(0, arr.size() - 2)).

void sort()

Sorts the elements of the array in ascending order.

void sort_custom(func: Callable)

Sorts the array with func, which returns true when its first argument goes before the second. As Array.sort_custom().

[]u8 to_byte_array() const

Returns a []u8 with each string encoded as UTF-8. Strings are null terminated.