API Array

Array

Growable general-purpose array with static factory helpers and the standard collection methods.

Script API Reference

Overview

Array stores heterogeneous elements and supports dynamic properties and growth. Use it when element types vary or when the collection size is not known in advance.

For fixed-size numeric or Boolean workloads, prefer a packed array such as Int8Array, UInt8Array, Int16Array, UInt16Array, Int32Array, UInt32Array, Int64Array, UInt64Array, Float64Array, or BooleanArray. Those types store elements in contiguous native storage and avoid per-element allocation.

Note

Array.isArray reports true only for a general Array. Packed arrays return false.

Quick Reference

Member	Returns	Summary
new Array([capacity])	array	Creates an empty array, optionally reserving capacity.
Array.from(iterable, [callback])	array	Creates an array from an iterable value, optionally mapping each item.
Array.isArray(value)	boolean	Reports whether the value is a general array.
Array.of(...items)	array	Creates an array from the supplied arguments.
Array.withCapacity([capacity])	array	Creates an empty array with reserved capacity.
items.length	number	Current element count.
items.has(value)	boolean	Reports whether the array contains a value.
items.indexOf(value, [fromIndex])	number	First index of a value.
items.lastIndexOf(value, [fromIndex])	number	Last index of a value.
items.push(...values)	number	Appends values and returns the new length.
items.pop()	any	Removes and returns the last item.
items.unshift(...values)	number	Prepends values and returns the new length.
items.shift()	any	Removes and returns the first item.
items.concat(...values)	array	Returns a concatenated array.
items.slice(start, [end])	array	Returns a shallow slice.
items.reverse()	array	Reverses the array in place.
items.sort()	array	Sorts the array in place.
items.join([separator])	string	Joins items into a string.
items.find(callback)	any	First item matching a predicate.
items.findIndex(callback)	number	First matching index.
items.findLast(callback)	any	Last item matching a predicate.
items.findLastIndex(callback)	number	Last matching index.
items.map(callback)	array	Maps items into a new array.
items.filter(callback)	array	Returns items matching a predicate.
items.some(callback)	boolean	Reports whether any item matches.
items.every(callback)	boolean	Reports whether every item matches.
items.flat([depth])	array	Flattens nested arrays.
items.reduce(callback)	any	Reduces items with an accumulator callback.

Constructors

new Array([capacity])

Parameters

Name	Type	Required	Description
capacity	number	No	Reserved capacity for later growth.

Returns

array — an empty array.

Behavior

A single numeric argument reserves capacity only. It does not create capacity null slots, so the new array still has a length of 0.

Example

var items = new Array(8);
items.push("first");
return items.length; // 1

Properties

items.length

Returns

number — the current element count.

Example

return ["a", "b"].length; // 2

Methods

Array.from(iterable, [callback])

Parameters

Name	Type	Required	Description
iterable	object	Yes	Iterable value to copy from.
callback	function	No	Mapping function applied to each item, called as callback(value, index).

Returns

array — a new array containing the copied, optionally mapped items.

Example

return Array.from([1, 2, 3], value => value * 2).join(","); // 2,4,6

Array.isArray(value)

Parameters

Name	Type	Required	Description
value	any	Yes	Value to inspect.

Returns

boolean — whether the value is a general array.

Behavior

Packed arrays return false; only a general Array returns true.

Example

return Array.isArray([1, 2]); // true

Array.of(...items)

Parameters

Name	Type	Required	Description
items	any	No	Zero or more elements, passed as variadic arguments.

Returns

array — a new array containing the supplied elements.

Example

return Array.of("a", "b").length; // 2

Array.withCapacity([capacity])

Parameters

Name	Type	Required	Description
capacity	number	No	Reserved capacity for later growth.

Returns

array — an empty array with reserved capacity.

Behavior

Reduces reallocation when the number of later push calls is known in advance. The returned array still starts with a length of 0.

Example

var values = Array.withCapacity(100);
values.push(1);
return values.length; // 1

items.has(value)

Parameters

Name	Type	Required	Description
value	any	Yes	Value to search for.

Returns

boolean — whether the value is present.

Example

return [1, 2, 3].has(2); // true

items.indexOf(value, [fromIndex])

Parameters

Name	Type	Required	Description
value	any	Yes	Value to search for.
fromIndex	number	No	Index at which the forward search starts.

Returns

number — the first matching index, or a negative value when the value is missing.

Example

return [1, 2, 2].indexOf(2); // 1

items.lastIndexOf(value, [fromIndex])

Parameters

Name	Type	Required	Description
value	any	Yes	Value to search for.
fromIndex	number	No	Index at which the reverse search starts.

Returns

number — the last matching index, or a negative value when the value is missing.

Example

return [1, 2, 2].lastIndexOf(2); // 2

items.push(...values)

Parameters

Name	Type	Required	Description
values	any	Yes	One or more elements to append, passed as variadic arguments.

Returns

number — the new length.

Behavior

Mutates the array in place.

Example

var items = [1];
return items.push(2, 3); // 3

items.pop()

Parameters

None.

Returns

any — the removed last item, or null for an empty array.

Behavior

Removes the last item in place.

Example

var items = [1, 2];
return items.pop(); // 2

items.unshift(...values)

Parameters

Name	Type	Required	Description
values	any	Yes	One or more elements to prepend, passed as variadic arguments.

Returns

number — the new length.

Behavior

Shifts existing elements in place, so the cost grows with the array length.

Example

var items = [2];
items.unshift(0, 1);
return items.join(","); // 0,1,2

items.shift()

Parameters

None.

Returns

any — the removed first item, or null for an empty array.

Behavior

Removes the first item in place and shifts the remaining elements down.

Example

var items = [1, 2];
return items.shift(); // 1

items.concat(...values)

Parameters

Name	Type	Required	Description
values	any	Yes	Values or arrays to append, passed as variadic arguments.

Returns

array — a new array; the original array is unchanged.

Example

return [1].concat([2, 3], 4).join(","); // 1,2,3,4

items.slice(start, [end])

Parameters

Name	Type	Required	Description
start	number	Yes	Index of the first element to copy.
end	number	No	Index after the last element to copy.

Returns

array — a shallow copy of the selected range.

Example

return [0, 1, 2].slice(1).join(","); // 1,2

items.reverse()

Parameters

None.

Returns

array — this array.

Behavior

Reverses the elements in place.

Example

var items = [1, 2, 3];
return items.reverse().join(","); // 3,2,1

items.sort()

Parameters

None.

Returns

array — this array.

Behavior

Sorts in place using the runtime default comparer. A custom comparison function is not supported.

Example

var items = [3, 1, 2];
return items.sort().join(","); // 1,2,3

items.join([separator])

Parameters

Name	Type	Required	Description
separator	string	No	Text inserted between items.

Returns

string — the joined text.

Example

return ["a", "b", "c"].join("-"); // a-b-c

items.find(callback)

Parameters

Name	Type	Required	Description
callback	function	Yes	Predicate called as callback(value, index); the first truthy result selects the item.

Returns

any — the first matching value, or null when nothing matches.

Example

return [1, 4, 7].find(value => value > 3); // 4

items.findIndex(callback)

Parameters

Name	Type	Required	Description
callback	function	Yes	Predicate called as callback(value, index).

Returns

number — the first matching index, or a negative value when nothing matches.

Example

return [1, 4, 7].findIndex(value => value > 3); // 1

items.findLast(callback)

Parameters

Name	Type	Required	Description
callback	function	Yes	Predicate called as callback(value, index).

Returns

any — the last matching value, or null when nothing matches.

Example

return [1, 4, 7].findLast(value => value > 3); // 7

items.findLastIndex(callback)

Parameters

Name	Type	Required	Description
callback	function	Yes	Predicate called as callback(value, index).

Returns

number — the last matching index, or a negative value when nothing matches.

Example

return [1, 4, 7].findLastIndex(value => value > 3); // 2

items.map(callback)

Parameters

Name	Type	Required	Description
callback	function	Yes	Mapping function called as callback(value, index).

Returns

array — a new array of mapped results.

Example

return [1, 2].map(value => value * 10).join(","); // 10,20

items.filter(callback)

Parameters

Name	Type	Required	Description
callback	function	Yes	Predicate called as callback(value, index).

Returns

array — a new array containing the matching items.

Example

return [1, 2, 3].filter(value => value % 2 == 1).join(","); // 1,3

items.some(callback)

Parameters

Name	Type	Required	Description
callback	function	Yes	Predicate called as callback(value, index).

Returns

boolean — whether any item matches.

Example

return [1, 2, 3].some(value => value > 2); // true

items.every(callback)

Parameters

Name	Type	Required	Description
callback	function	Yes	Predicate called as callback(value, index).

Returns

boolean — whether every item matches.

Example

return [1, 2, 3].every(value => value > 0); // true

items.flat([depth])

Parameters

Name	Type	Required	Description
depth	number	No	Number of nesting levels to flatten. Defaults to 1.

Returns

array — a new flattened array.

Example

return [1, [2, [3]]].flat(2).join(","); // 1,2,3

items.reduce(callback)

Parameters

Name	Type	Required	Description
callback	function	Yes	Accumulator function called as callback(accumulator, value, index).

Returns

any — the accumulated result, or null for an empty array.

Behavior

There is no seed argument. The first element becomes the initial accumulator, and the callback starts at the second element.

Example

return [1, 2, 3].reduce((sum, value) => sum + value); // 6