Array object

Represents indexed vector (array) of values.

Properties

length

- integer, number of items in the array. Read/write property.

[index]

- value, element of the array at the index position, Read-write index accessor. Zero-based index.

[begin..end]

- integers, zero-based indexes of first and last element of the range. Returns slice of vector contains elements from start index and up to but not included end index. Begin or/and end are optional. If begin is omitted then it is assumed to be 0, if end - length is used as an end value.

first

- value | undefined, first element of the array, if any.

last

- value | undefined, last element of the array, if any.

Methods

Array

([value1 [, value2 [, ... valueN ]]])

Creates new array object from arguments provided. Use as
var a = new Array(...);

toLocaleString

() returns: string

Returns string - comma separated list of values

toString

() returns: string

Returns string - comma separated list of values

valueOf

() returns: string

Same as toString.

clone

([deep:true]) returns: array

Returns brand new copy of the array. If deep === true then it does recursive, deep cloning.

push

([value1 [, value2 [, ... valueN ]]]) returns: value

Appends array by values. Returns last inserted element.

shift

() returns: value | undefined

Removes first element of the array. Returns removed element.

pop

() returns: value | undefined

Removes last element of the array. Returns removed element.

unshift

(value) returns: value | undefined

Inserts value at first array position. Returns the value.

concat

([value1 [, value2 [, ... valueN ]]]) returns: array

Appends array by values. Returns the array.

join

([delimeter]) returns: string

Returns string with all elements of the array separated by the delimeter or comma

reverse

() returns: array

Reverses order of elements in the array in-place. Returns the array.

slice

(start[, end]) returns: array | undefined

Returns new array consisting from elements of the array from start up to but not including end index.

splice

(index, count [, element1, element2, ...] ) returns: array

This method:

1. Removes count number of elements at index.
2. Inserts element1, element2, ... at index position.
3. returns removed elements as an array or empty array if count is zero.

sort

( [compareFunction] ) returns: array

Sorts elements of the array in ascending order. If the compareFunction provided it is used for comparing elements during sort. compareFunction shall accept two values in parameters and return -1, 0 or +1 as a result.

indexOf

( value [, notfound = -1] ) returns: int | notfound

Get index of the value in array. If the value is not found returns the notfound value (-1 by default).

lastIndexOf

( value [, notfound = -1] ) returns: int | notfound

Get last index of the value in array. If the value is not found returns the notfound value (-1 by default).

remove

( index:int ) returns: value | nothing

Removes element at index. Returns removed element.

removeByValue

( value ) returns: value | nothing

Tries to locate element by value in the array and removes it. Returns removed element.

map

( callback: function [, thisObject] ) : array

This method creates a new array with the result of calling a provided callback function on every element in this array. If thisObject is provided then the callback will have it as this.

The callback function may accept following parameters: callback(currentValue, index, array) where:

• currentValue is a value of array element at the index position;
• array is the array to what this method applied.

The map methoddoes not mutate the array on which it is called.

If the callback function ends with nothing (without explicit return) then the element will not go to resulting array (as when filter() method below returns false). Note: this a la filter() behavior is non standard.

Example:

var numbers = [1, 2, 3];
var squares = numbers.map(:el:el*el); // make new array of
                                      // squares of numbers
                                      // in original array.
// squares will be [1, 4, 9] at this point.

reduce

( callback:function [, initialValue] ) : value

This method applies the function simultaneously against two values of the array (from left-to-right) as to reduce it to a single value.

The callback function may accept following parameters: callback(previousValue, currentValue, index, array) where:

• previousValue is either initialValue (on first run) or result of previous call of the callback function;
• currentValue is a value of array element at the index position;
• array is the array being scanned (reduced).

The method returns result of last callback invocation. The methoddoes not mutate the array on which it is called.

Example, this fragment calculates sum of all elements in the array:

var total = [0, 1, 2, 3].reduce( :a, b: a + b );
// total is 6 at this point.

filter

( callback: function [, thisObject] ) : array

This method calls the callbackfunction once for each element in the array, and constructs new array of all the values for whichthe callback returns true.

The callback function may accept following parameters: callback(currentValue, index, array) where:

• currentValue is a value of array element at the index position;
• array is the array to what this method applied.

The filter methoddoes not mutate the array on which it is called.

Example, this code creates new array from elements of source array that are greater than 10:

var filtered = [12, 5, 8, 130, 44].filter(:el: el > 10);
// filtered is [12, 130, 44] here

find

( predicate:function [, thisArg: object] ) : (index:integer, element: any)

Calls predicate function for each element of the array until the predicate returns "truthy" value. Returns found element.

The predicate is a function with the following signature:

function (element:any [, index:integer [, arr: array ]] ) : true | false

where:

• element - element of the array 
• index - index of the element in the array
• arr - the array the find() was called with.

If thisArg is provided then it is passed as this variable into the predicate calls.

The function returns as found index and as the element and so it can be used as:

var (i,v) = someArr.find(:el: el.id == "foo" ); // value and index, or
var v = someArr.find(:el: el.id == "foo" ); // just value

some

( predicate:function [, thisArg: object] ) : true | false

Calls predicate function for each element of the array until the predicate returns "truthy" value and returns true. If there is no element in the array for which the predicate is true then the method returns false.

The predicate is a function with the following signature:

function (element:any [, index:integer [, arr: array ]] ) : true | false

where:

• element - element of the array 
• index - index of the element in the array
• arr - the array the find() was called with.

If thisArg is provided then it is passed as this variable into the predicate calls.

every

( predicate:function [, thisArg: object] ) : true | false

Returns true if for each element in the array predicate is true. If there is any element in the array for which the predicate is false the method returns false.

The predicate is a function with the following signature:

function (element:any [, index:integer [, arr: array ]] ) : true | false

where:

• element - element of the array 
• index - index of the element in the array
• arr - the array the find() was called with.

If thisArg is provided then it is passed as this variable into the predicate calls.

addObserver

( observer:function ) : undefined

Attaches observer to the array - function that is called when the array changes. The observer here is a function that has following signature:

function observer(changeDefinition) {} where changeDefinition is tuple having following fields:

• [0] - symbol, one of:#add-range (one or many elements added), #update-range (one or many elements changed) or #delete-range (elements were deleted);
• [1] - array, the object that property was changed;
• [2] - integer, range start, index of first changed elements;
• [3] - integer, range end (exclusive);

removeObserver

( observer:function ) : undefined

Detaches given observer function from the array.