PackedStringArray
A packed array of Strings ([]String in Grost).
Description
Section titled “Description”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.
Methods
Section titled “Methods”| Returns | Method |
|---|---|
| bool | all(method) |
| bool | any(method) |
| void | append(value) |
| void | append_array(array) |
| Variant | back() |
| int | bsearch(value, before) |
| int | bsearch_custom(value, func, before) |
| void | clear() |
| int | count(value) |
[]String | duplicate() |
| bool | erase(value) |
| void | fill(value) |
[]String | filter(method) |
| int | find(value, from) |
| int | find_custom(method, from) |
| Variant | front() |
| String | get(index) |
| bool | has(value) |
| int | insert(at_index, value) |
| bool | is_empty() |
| Array | map(method) |
| Variant | max() |
| Variant | min() |
| Variant | pick_random() |
| Variant | pop_at(position) |
| Variant | pop_back() |
| Variant | pop_front() |
| void | push_back(value) |
| void | push_front(value) |
| Variant | reduce(method, accum) |
| void | remove_at(index) |
| int | resize(new_size) |
| void | reverse() |
| int | rfind(value, from) |
| int | rfind_custom(method, from) |
| void | set(index, value) |
| void | shuffle() |
| int | size() |
[]String | slice(begin, end) |
| void | sort() |
| void | sort_custom(func) |
[]u8 | to_byte_array() |
Method descriptions
Section titled “Method descriptions”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().
append
Section titled “append”void append(value: String)
Appends an element at the end of the array (alias of push_back()).
append_array
Section titled “append_array”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.
bsearch
Section titled “bsearch”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.
bsearch_custom
Section titled “bsearch_custom”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.
duplicate
Section titled “duplicate”[]String duplicate() const
Creates a copy of the array, and returns it.
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.
filter
Section titled “filter”[]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.
find_custom
Section titled “find_custom”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.
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.
Returns true if the array contains value.
insert
Section titled “insert”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()).
is_empty
Section titled “is_empty”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.
pick_random
Section titled “pick_random”Variant pick_random() const
Returns a random element. In Grost it is an Option[String]: none when the array is empty.
pop_at
Section titled “pop_at”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.
pop_back
Section titled “pop_back”Variant pop_back()
Removes the last element and returns it. In Grost it is an Option[String]: none when the array is empty.
pop_front
Section titled “pop_front”Variant pop_front()
Removes the first element and returns it. In Grost it is an Option[String]: none when the array is empty.
push_back
Section titled “push_back”void push_back(value: String)
Appends a string element at end of the array.
push_front
Section titled “push_front”void push_front(value: String)
Inserts value at the start of the array.
reduce
Section titled “reduce”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).
remove_at
Section titled “remove_at”void remove_at(index: int)
Removes an element from the array by index.
resize
Section titled “resize”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.
reverse
Section titled “reverse”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.
rfind_custom
Section titled “rfind_custom”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.
shuffle
Section titled “shuffle”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.
sort_custom
Section titled “sort_custom”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().
to_byte_array
Section titled “to_byte_array”[]u8 to_byte_array() const
Returns a []u8 with each string encoded as UTF-8. Strings are null terminated.