John Alanbrook
96ef8ccba3
Some checks failed
Build and Deploy / package-dist (push) Has been cancelled
Build and Deploy / deploy-itch (push) Has been cancelled
Build and Deploy / deploy-gitea (push) Has been cancelled
Build and Deploy / build-linux (push) Has been cancelled
Build and Deploy / build-windows (CLANG64) (push) Has been cancelled
662 lines
15 KiB
Markdown
662 lines
15 KiB
Markdown
# Array
|
|
|
|
### length <sub>number</sub>
|
|
|
|
### at(index) <sub>function</sub>
|
|
|
|
Return the item at index 'index', supporting negative indices to count from
|
|
the end. If 'index' is out of range, returns undefined.
|
|
|
|
|
|
|
|
**index**: The index of the element to return (can be negative).
|
|
|
|
|
|
**Returns**: The element at the given index, or undefined.
|
|
|
|
|
|
### with(index, value) <sub>function</sub>
|
|
|
|
Return a shallow copy of the array, but with the element at 'index' replaced
|
|
by 'value'. If 'index' is negative, it counts from the end. Throws if out of range.
|
|
|
|
|
|
|
|
**index**: The zero-based index (can be negative) to replace.
|
|
|
|
**value**: The new value for the specified position.
|
|
|
|
|
|
**Returns**: A new array with the updated element.
|
|
|
|
|
|
### concat(items) <sub>function</sub>
|
|
|
|
Return a new array that is the result of concatenating this array with
|
|
any additional arrays or values provided.
|
|
|
|
|
|
|
|
**items**: One or more arrays or values to concatenate.
|
|
|
|
|
|
**Returns**: A new array with the items appended.
|
|
|
|
|
|
### every(callback, thisArg) <sub>function</sub>
|
|
|
|
Return true if the provided callback function returns a truthy value for
|
|
every element in the array; otherwise false.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array) => boolean.
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: True if all elements pass the test, otherwise false.
|
|
|
|
|
|
### some(callback, thisArg) <sub>function</sub>
|
|
|
|
Return true if the provided callback function returns a truthy value for at
|
|
least one element in the array; otherwise false.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array) => boolean.
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: True if at least one element passes the test, otherwise false.
|
|
|
|
|
|
### forEach(callback, thisArg) <sub>function</sub>
|
|
|
|
Call the provided callback function once for each element in the array.
|
|
Does not produce a return value.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array).
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: None
|
|
|
|
|
|
### map(callback, thisArg) <sub>function</sub>
|
|
|
|
Create a new array with the results of calling a provided callback function
|
|
on every element in this array.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array) => newElement.
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: A new array of transformed elements.
|
|
|
|
|
|
### filter(callback, thisArg) <sub>function</sub>
|
|
|
|
Create a new array containing all elements for which the provided callback
|
|
function returns a truthy value.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array) => boolean.
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: A new array of elements that passed the test.
|
|
|
|
|
|
### reduce(callback, initialValue) <sub>function</sub>
|
|
|
|
Apply a callback function against an accumulator and each element in the
|
|
array (from left to right) to reduce it to a single value.
|
|
|
|
|
|
|
|
**callback**: A function(accumulator, element, index, array) => newAccumulator.
|
|
|
|
**initialValue**: Optional. The initial value for the accumulator.
|
|
|
|
|
|
**Returns**: The single resulting value.
|
|
|
|
|
|
### reduceRight(callback, initialValue) <sub>function</sub>
|
|
|
|
Similar to reduce(), except it processes elements from right to left.
|
|
|
|
|
|
|
|
**callback**: A function(accumulator, element, index, array) => newAccumulator.
|
|
|
|
**initialValue**: Optional. The initial value for the accumulator.
|
|
|
|
|
|
**Returns**: The single resulting value.
|
|
|
|
|
|
### fill(value, start, end) <sub>function</sub>
|
|
|
|
Fill the array with a static value from 'start' index up to (but not including)
|
|
'end' index. Modifies the original array.
|
|
|
|
|
|
|
|
**value**: The value to fill.
|
|
|
|
**start**: The starting index (default 0).
|
|
|
|
**end**: The ending index (default array.length).
|
|
|
|
|
|
**Returns**: The modified array (with filled values).
|
|
|
|
|
|
### find(callback, thisArg) <sub>function</sub>
|
|
|
|
Return the first element in the array that satisfies the provided callback
|
|
function. If none is found, return undefined.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array) => boolean.
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: The first matching element, or undefined if not found.
|
|
|
|
|
|
### findIndex(callback, thisArg) <sub>function</sub>
|
|
|
|
Return the index of the first element in the array that satisfies the
|
|
provided callback function. If none is found, return -1.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array) => boolean.
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: The index of the first matching element, or -1 if not found.
|
|
|
|
|
|
### findLast(callback, thisArg) <sub>function</sub>
|
|
|
|
Return the last element in the array that satisfies the provided callback
|
|
function, searching from right to left. If none is found, return undefined.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array) => boolean.
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: The last matching element, or undefined if not found.
|
|
|
|
|
|
### findLastIndex(callback, thisArg) <sub>function</sub>
|
|
|
|
Return the index of the last element in the array that satisfies the
|
|
provided callback function, searching from right to left. If none is found,
|
|
return -1.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array) => boolean.
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: The index of the last matching element, or -1 if not found.
|
|
|
|
|
|
### indexOf(searchElement, fromIndex) <sub>function</sub>
|
|
|
|
Return the first index at which a given element can be found. If not present,
|
|
return -1.
|
|
|
|
|
|
|
|
**searchElement**: The item to locate in the array.
|
|
|
|
**fromIndex**: The index at which to start searching (default 0).
|
|
|
|
|
|
**Returns**: The index of the found element, or -1 if not found.
|
|
|
|
|
|
### lastIndexOf(searchElement, fromIndex) <sub>function</sub>
|
|
|
|
Return the last index at which a given element can be found, or -1 if not
|
|
present. Searches backward from 'fromIndex'.
|
|
|
|
|
|
|
|
**searchElement**: The item to locate in the array.
|
|
|
|
**fromIndex**: The index at which to start searching backward (default array.length - 1).
|
|
|
|
|
|
**Returns**: The last index of the found element, or -1 if not found.
|
|
|
|
|
|
### includes(searchElement, fromIndex) <sub>function</sub>
|
|
|
|
Return a boolean indicating whether the array contains the given element,
|
|
comparing elements using the SameValueZero algorithm.
|
|
|
|
|
|
|
|
**searchElement**: The value to search for.
|
|
|
|
**fromIndex**: The position in the array to start searching (default 0).
|
|
|
|
|
|
**Returns**: True if the element is found, otherwise false.
|
|
|
|
|
|
### join(separator) <sub>function</sub>
|
|
|
|
Join all elements of the array into a string, separated by 'separator'.
|
|
|
|
|
|
|
|
**separator**: The delimiter string to separate elements (default ',').
|
|
|
|
|
|
**Returns**: A string of array elements joined by the separator.
|
|
|
|
|
|
### toString() <sub>function</sub>
|
|
|
|
Return a string representing the elements of the array, separated by commas.
|
|
Overrides Object.prototype.toString.
|
|
|
|
|
|
|
|
**Returns**: A comma-separated string of array elements.
|
|
|
|
|
|
### toLocaleString() <sub>function</sub>
|
|
|
|
Return a localized string representing the array and its elements, calling
|
|
each element's toLocaleString if available.
|
|
|
|
|
|
|
|
**Returns**: A locale-sensitive, comma-separated string of array elements.
|
|
|
|
|
|
### pop() <sub>function</sub>
|
|
|
|
Remove the last element from the array and return it. This changes the length
|
|
of the array.
|
|
|
|
|
|
|
|
**Returns**: The removed element, or undefined if the array is empty.
|
|
|
|
|
|
### push(items) <sub>function</sub>
|
|
|
|
Append one or more elements to the end of the array and return the new length
|
|
of the array.
|
|
|
|
|
|
|
|
**items**: One or more items to append.
|
|
|
|
|
|
**Returns**: The new length of the array.
|
|
|
|
|
|
### shift() <sub>function</sub>
|
|
|
|
Remove the first element from the array and return it. This changes the length
|
|
of the array.
|
|
|
|
|
|
|
|
**Returns**: The removed element, or undefined if the array is empty.
|
|
|
|
|
|
### unshift(items) <sub>function</sub>
|
|
|
|
Insert one or more elements at the start of the array and return the new
|
|
length of the array.
|
|
|
|
|
|
|
|
**items**: One or more elements to insert at the start.
|
|
|
|
|
|
**Returns**: The new length of the array.
|
|
|
|
|
|
### reverse() <sub>function</sub>
|
|
|
|
Reverse the elements of the array in place and return the modified array.
|
|
|
|
|
|
|
|
**Returns**: The reversed array.
|
|
|
|
|
|
### toReversed() <sub>function</sub>
|
|
|
|
Return a shallow copy of the array in reverse order, without modifying the original array.
|
|
|
|
|
|
|
|
**Returns**: A new reversed array.
|
|
|
|
|
|
### sort(compareFunction) <sub>function</sub>
|
|
|
|
Sort the array in place, returning it. By default, sorts elements as strings in ascending order. An optional compareFunction may be used for custom sorting.
|
|
|
|
|
|
|
|
**compareFunction**: A function(a, b) => number, defining sort order.
|
|
|
|
|
|
**Returns**: The sorted array.
|
|
|
|
|
|
### toSorted(compareFunction) <sub>function</sub>
|
|
|
|
Return a shallow copy of the array, sorted according to the optional compare
|
|
function, without modifying the original array.
|
|
|
|
|
|
|
|
**compareFunction**: A function(a, b) => number, defining sort order.
|
|
|
|
|
|
**Returns**: A new sorted array.
|
|
|
|
|
|
### slice(start, end) <sub>function</sub>
|
|
|
|
Return a shallow copy of a portion of the array into a new array object, selected from 'start' to 'end' (end not included).
|
|
|
|
|
|
|
|
**start**: The beginning index (0-based). Negative values count from the end.
|
|
|
|
**end**: The end index (exclusive). Negative values count from the end.
|
|
|
|
|
|
**Returns**: A new array containing the extracted elements.
|
|
|
|
|
|
### splice(start, deleteCount, items) <sub>function</sub>
|
|
|
|
Change the contents of the array by removing or replacing existing elements and/or adding new elements in place. Returns an array of removed elements.
|
|
|
|
|
|
|
|
**start**: The index at which to start changing the array.
|
|
|
|
**deleteCount**: Number of elements to remove.
|
|
|
|
**items**: Elements to add in place of the removed elements.
|
|
|
|
|
|
**Returns**: An array containing the removed elements (if any).
|
|
|
|
|
|
### toSpliced(start, deleteCount, items) <sub>function</sub>
|
|
|
|
Return a shallow copy of the array, with a splice-like operation applied at 'start' removing 'deleteCount' elements and adding 'items'. Does not mutate the original array.
|
|
|
|
|
|
|
|
**start**: The index at which to start the splice operation.
|
|
|
|
**deleteCount**: Number of elements to remove.
|
|
|
|
**items**: Elements to add in place of the removed elements.
|
|
|
|
|
|
**Returns**: A new array with the splice applied.
|
|
|
|
|
|
### copyWithin(target, start, end) <sub>function</sub>
|
|
|
|
Copy a sequence of array elements within the array, overwriting existing values. This operation is performed in place and returns the modified array.
|
|
|
|
|
|
|
|
**target**: The index at which to copy the sequence to.
|
|
|
|
**start**: The beginning index of the sequence to copy.
|
|
|
|
**end**: The end index (exclusive) of the sequence to copy (default array.length).
|
|
|
|
|
|
**Returns**: The modified array.
|
|
|
|
|
|
### flatMap(callback, thisArg) <sub>function</sub>
|
|
|
|
Return a new array formed by applying a callback function to each element and then flattening the result by one level.
|
|
|
|
|
|
|
|
**callback**: A function(element, index, array) => array or value.
|
|
|
|
**thisArg**: Optional. A value to use as 'this' within the callback.
|
|
|
|
|
|
**Returns**: A new array with the flattened results.
|
|
|
|
|
|
### flat(depth) <sub>function</sub>
|
|
|
|
Return a new array with all sub-array elements concatenated into it recursively up to the specified depth.
|
|
|
|
|
|
|
|
**depth**: The maximum depth to flatten (default 1).
|
|
|
|
|
|
**Returns**: A new flattened array.
|
|
|
|
|
|
### values() <sub>function</sub>
|
|
|
|
Return a new Array Iterator object that contains the values for each index in the array.
|
|
|
|
|
|
|
|
**Returns**: An iterator over the array's elements.
|
|
|
|
|
|
### keys() <sub>function</sub>
|
|
|
|
Return a new Array Iterator object that contains the keys (indexes) for each index in the array.
|
|
|
|
|
|
|
|
**Returns**: An iterator over the array's indices.
|
|
|
|
|
|
### entries() <sub>function</sub>
|
|
|
|
Return a new Array Iterator object that contains key/value pairs for each index in the array. Each entry is [index, value].
|
|
|
|
|
|
|
|
**Returns**: An iterator over [index, value] pairs.
|
|
|
|
|
|
### add(other) <sub>function</sub>
|
|
|
|
Non-standard. Add corresponding elements of the current array and 'other' element-wise, returning a new array. Behavior depends on data types.
|
|
|
|
|
|
|
|
**other**: Another array or scalar to add to each element.
|
|
|
|
|
|
**Returns**: A new array with element-wise sum results.
|
|
|
|
|
|
### sub(other) <sub>function</sub>
|
|
|
|
Non-standard. Subtract corresponding elements of 'other' from the current array element-wise, returning a new array. Behavior depends on data types.
|
|
|
|
|
|
|
|
**other**: Another array or scalar to subtract from each element.
|
|
|
|
|
|
**Returns**: A new array with element-wise difference results.
|
|
|
|
|
|
### div(other) <sub>function</sub>
|
|
|
|
Non-standard. Divide each element of the current array by the corresponding element of 'other' (or a scalar) element-wise, returning a new array. Behavior depends on data types.
|
|
|
|
|
|
|
|
**other**: Another array or scalar for the division.
|
|
|
|
|
|
**Returns**: A new array with element-wise division results.
|
|
|
|
|
|
### scale() <sub>function</sub>
|
|
|
|
### lerp() <sub>function</sub>
|
|
|
|
### x <sub>accessor</sub>
|
|
|
|
### y <sub>accessor</sub>
|
|
|
|
### xy <sub>accessor</sub>
|
|
|
|
### r <sub>accessor</sub>
|
|
|
|
### g <sub>accessor</sub>
|
|
|
|
### b <sub>accessor</sub>
|
|
|
|
### a <sub>accessor</sub>
|
|
|
|
### rgb <sub>accessor</sub>
|
|
|
|
### rgba <sub>accessor</sub>
|
|
|
|
### filter!(fn) <sub>function</sub>
|
|
|
|
Perform an in-place filter of this array using the provided callback 'fn'.
|
|
Any element for which 'fn' returns a falsy value is removed. The array is modified
|
|
and then returned.
|
|
|
|
|
|
|
|
**fn**: A callback function(element, index, array) => boolean.
|
|
|
|
|
|
**Returns**: The filtered (modified) array.
|
|
|
|
|
|
### delete(item) <sub>function</sub>
|
|
|
|
Remove the first occurrence of 'item' from the array, if it exists.
|
|
Returns undefined.
|
|
|
|
|
|
|
|
**item**: The item to remove.
|
|
|
|
|
|
**Returns**: undefined
|
|
|
|
|
|
### copy() <sub>function</sub>
|
|
|
|
Return a deep copy of this array by applying 'deep_copy' to each element.
|
|
The resulting array is entirely new.
|
|
|
|
|
|
|
|
**Returns**: A new array that is a deep copy of the original.
|
|
|
|
|
|
### equal(b) <sub>function</sub>
|
|
|
|
Check if this array and array 'b' have the same elements in the same order.
|
|
If they are of different lengths, return false. Otherwise compare them via JSON.
|
|
|
|
|
|
|
|
**b**: Another array to compare against.
|
|
|
|
|
|
**Returns**: True if they match, false otherwise.
|
|
|
|
|
|
### last() <sub>function</sub>
|
|
|
|
Return the last element of this array. If the array is empty, returns undefined.
|
|
|
|
|
|
|
|
**Returns**: The last element of the array, or undefined if empty.
|
|
|
|
|
|
### wrapped(x) <sub>function</sub>
|
|
|
|
Return a copy of the array with the first 'x' elements appended to the end.
|
|
Does not modify the original array.
|
|
|
|
|
|
|
|
**x**: The number of leading elements to re-append.
|
|
|
|
|
|
**Returns**: A new array with the leading elements wrapped to the end.
|
|
|
|
|
|
### wrap_idx(x) <sub>function</sub>
|
|
|
|
Wrap the integer 'x' around this array's length, ensuring the resulting index
|
|
lies within [0, this.length - 1].
|
|
|
|
|
|
|
|
**x**: The index to wrap.
|
|
|
|
|
|
**Returns**: A wrapped index within this array's bounds.
|
|
|
|
|
|
### mirrored(x) <sub>function</sub>
|
|
|
|
Return a new array that appends a reversed copy (excluding the last element)
|
|
of itself to the end. For example, [1,2,3] -> [1,2,3,2,1]. If the array has length
|
|
<= 1, a copy of it is returned directly.
|
|
|
|
|
|
|
|
**Returns**: A new "mirrored" array.
|
|
|