array | Dev Center

array

Availability

Device + Agent

Description

Squirrel’s array library provides a set of tools for the manipulation of array variables and the items they contain.

Arrays can contain any Squirrel data type, including arrays themselves, and the items within an array need not be of the same type. However, if functions and/or objects are inserted into the array, the array can no longer be serialized (see Squirrel Data Serialization for more information), which has implications for the array’s ability to be sent from agent to device or vice versa, and determines whether it can be saved in persistent storage.

Referencing

Arrays are accessed by reference, and adding an array reference to another entity, such as a table or another array, or passing it into a function parameter, does not add a copy of the array but a reference to it.

For example, the following code

local arrayOne = [];
local tableOne = {};
local tableTwo = {};

tableOne.myArray <- arrayOne;
tableTwo.anArray <- arrayOne;

Causes the two tables tableOne and tableTwo to each contain a reference to a single, shared array, arrayOne. This is the case even though the two tables identify that same array with their own, different keys.

Further Information

For more guidance on using arrays, please see the Squirrel Programming Guide.

Member Entities

The array object has the following member methods:

array.append() — Adds an item to the end of an array

array.apply() — Applies a function to all of an array’s items

array.clear() — Removes all of the items from an array

array.extend() — Combines two arrays into one

array.filter() — Applies a filter function to an array’s items, storing the results in a new array

array.find() — Finds a value within an array

array.insert() — Inserts an item into an array at the specified index

array.len() — Returns an array’s length

array.map() — Applies a function an array’s items, adding the results to a new array

array.pop() — Returns and removes the value at the end of the array

array.push() — Adds an item to the end of an array

array.reduce() — Reduces an array to a single value

array.remove() — Returns and removes an array item at a specified index

array.resize() — Increases or decreases the size of an array

array.reverse() — Reverses the order of the elements in an array

array.slice() — Creates a new sub-array from an array

array.sort() — Re-orders the items within an array

array.top() — Returns the value at the end of an array

The array object has the following member function:

array() — Creates an array of the required size