Array

Extends Object. Arrays are essential for storing, managing, and operating on sets of variables.

Instantiation


// initiate an empty array
var myEmptyArray = [];

var fruits = ['Apple', 'Banana', 'Mango'];

Note that in initialisation is always followed by a semicolon.

Properties
length

Type Number

The number of items within the Array.



Methods
by(String:property, Mixed:value)

Returns Object | null

The by() method is designed for use with Arrays containing objects and returns the first object whose property matches a value, or null if an object with the property value is unmatched.


<?ev
    var data = [
        { id: 1, title: 'One'},
        { id: 2, title: 'Two'},
        { id: 3, title: 'Three'}
    ];
    var ids = data.by('id', 2); // { id: 2, title: 'Two'}
?>
byGroup(String:property [, Mixed:value])

Returns Object | Array

The byGroup() method is designed for use with Arrays containing Objects. The original Array is split into groups based on the value of the property and is returned as an Object. If the value parameter is not omited an Array is returned containing all objects within the original Array with a property matching the value.


<?ev
    var data = [
        { id: 1, title: 'One', type: 'odd'},
        { id: 2, title: 'Two', type: 'even'},
        { id: 3, title: 'Three', type: 'odd'},
        { id: 4, title: 'Four', type: 'even'}
    ];
    var groupedByType = data.byGroup('type'); // returns an Object {'odd': Array, 'even': Array}
    var evenTypes = data.byGroup('type', 'even'); // returns an Array
?>
concat(Array:item [, Array:item...])

Returns Array

Returns a new Array, containing the values of the joined arrays.


var fruit = ['Apple', 'Banana', 'Mango'];
var veg = ['Cucumber', 'Lettuce', 'Carrot'];
var fruitAndVeg = fruit.concat(veg);
every(Function:callback [, Mixed:thisArg])

Returns Boolean

Returns true if every element of the array matches a test performed by the callback function, else false.

The callback function may accept the following arguments:

  • element
    The current element of the Array to test against.

  • index (optional)
    The index of the current element within the Array being tested.

  • array (optional)
    The original Array the every method was called upon.

The thisArg (optional) argument sets the scope of the this keyword within the callback function. If not supplied the this keyword evaluates as undefined.


var fruit = [
    {
        name: 'Melon',
        family: 'Tropical'
    },{
        name: 'Pineapple',
        family: 'Tropical'
    },{
        name: 'Passion Fruit',
        family: 'Tropical'
    }
];
fruit.every(function(obj){
    return obj.family == 'Tropical';
}); // true
indexOf(Mixed:value [, Number:start])

Returns Number

Returns the index of the first instance of the value found in the array or -1 if not found. The optional start argument determines the index from which to search.


var fruit = ['Apple', 'Banana', 'Mango'];
print(fruit.indexOf('Banana')); // 1
join([String:separator])

Returns String

Returns a new String containing the Mixed.toString values of each item within the Array separated by separator. If separator is not supplied the separator will default to a comma.


var fruit = ['Apple', 'Banana', 'Mango'];
print(fruit.join(', '));
lastIndexOf(Mixed:value [, Number:start])

Returns Number

Returns the index of the last instance of the value found in the array or -1 if not found. The optional start argument determines the index from which to search.


var fruit = ['Apple', 'Banana', 'Mango', 'Banana'];
print(fruit.lastIndexOf('Banana')); // 3
pluck(String:property [, Boolean:unique])

Returns Array

The pluck() method is designed for use with Arrays containing Objects with similar properties and returns a new Array containing the values of the property supplied.


<?ev
    var data = [
        { id: 1, title: 'One'},
        { id: 2, title: 'Two'},
        { id: 3, title: 'Three'}
    ];
    var ids = data.pluck('id'); // [1, 2, 3]
    
    // Also works with multi-dimensional arrays
    
    var data = [
        ['A', 'B', 'C'],
        [1, 2 , 3],
        ['X', 'Y' , 'Z']
    ];
    var ids = data.pluck(1); // ['B', 2, 'Y']
?>

The pluck method is particularly useful for obtaining values from data sets.

If the optional unique argument is supplied the array of values returned will contain unique values only. 

pop()

Returns the last item in the Array and removes it from the end of the original Array.


<?ev
    var fruit = ['Apple', 'Banana', 'Mango'];
?>
<p>{{ fruit.pop() }}</p>
<p>{{ fruit }}</p>

push(Mixed:item [, Mixed:item...])

Returns Number

Add one or more items of any data type to the end of the Array. Returns the new length of the Array.


<?ev
   var fruit = ['Apple', 'Banana', 'Mango'];
   fruit.push('Pear'); // Apple, Banana, Mango, Pear
?>
random()

Returns a random element from the Array

reverse()

Returns Array

Reverse the order of the Array and return the original Array.


<?ev
   var fruit = ['Apple', 'Banana', 'Mango'];
   fruit.reverse(); // Mango, Banana, Apple
?>
shift()

Removes the first element of an array, and returns that element.


<?ev
   var fruit = ['Apple', 'Banana', 'Mango'];
   var first = fruit.shift();
   print('The first item was ' + first); // Apple
   print('The remaining items are ' + fruit); // Banana, Mango
?>
slice(Number:start [, Number:end])

Returns Array

Selects items of an Array between a start and end index and returns the new Array. The start argument specifies the item to start the selection from. Note that the starting index of Arrays is zero. If end is omitted, all elements from the start position and to the end of the array will be selected. Use negative numbers to select from the end of an array.


<?ev
   var fruit = ['Apple', 'Banana', 'Mango', 'Pear'];
   var sliced = fruit.slice(1, 3);
?>
<p>{{ fruit }}</p>
<p>{{ sliced }}</p>
some(Function:callback [, Mixed:thisArg])

Returns Boolean

Returns true if some elements of an array match a test performed by the callback function, else false if no elements match.

The callback function may accept the following arguments:

  • element
    The current element of the Array to test against.

  • index (optional)
    The index of the current element within the Array being tested.

  • array (optional)
    The original Array the every method was called upon.

The thisArg (optional) argument sets the scope of the this keyword within the callback function. If not supplied the this keyword evaluates as undefined.


var fruit = [ 
    {
        name: 'Apple',
        family: 'Tree Fruits'
    },{
        name: 'Pineapple',
        family: 'Tropical'
    },{
        name: 'Lemon',
        family: 'Citrus'
    }
];
fruit.some(function(obj){
    return obj.family == 'Tropical';
}); // true
sort([Function:compare])

Returns Array

Sort the Array by item value. By default, the sort() method sorts the values as strings in alphabetical and ascending order.


<?ev
   var fruit = ['Mango', 'Banana', 'Apple', 'Pear'];
   fruit.sort(); // Apple, Banana, Mango, Pear
?>

Arrays also support sort functions:


var contacts = [
    { firstname: 'Edward', id: 21 },
    { firstname: 'Cecil', id: 37 },
    { firstname: 'Alan', id: 45 },
    { firstname: 'Bob', id: 12 },
    { firstname: 'Ting', id: 11 },
    { firstname: 'Geoff', id: 37 }
];
contacts.sort(function (a, b) {
    if (a.firstname > b.firstname) {
        return 1;
    }
    if (a.firstname < b.firstname) {
        return -1;
    }
    // a must be equal to b
    return 0;
});
splice(Number:index, Number:howmany [, item1,...])

Returns Array

The splice() method adds/removes items to/from an Array, and returns the removed item(s). The index required argument is a Number that specifies at what position to add/remove items. Use negative values to specify the position from the end of the array. The howmany argument is a required Number of items to remove from the original Array. You may follow the howmany argument with zero or more items to be inserted into the original Array at the index.

toString()

Returns String

Returns a new String representing the items of the Array.

unshift(item1 [, item2,...])

Returns Number

Adds one or more new items to the beginning of an Array, and returns the new length of the Array.