Namespace $.js.Array

Holds the methods used for manipulating arrays and other array-like objects.
Defined in: core-js.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	$.js.Array Holds the methods used for manipulating arrays and other array-like objects.

Method Summary
Method Attributes	Method Name and Description
<static>	$.js.Array.concat(value1, valueN) Concatenate multiple arrays.
<static>	$.js.Array.every(callback, thisObject) Check if the `callback` function returns true for every element in the current array.
<static>	$.js.Array.filter(callback, thisObject) Filter the current array using the `callback` function.
<static>	$.js.Array.forEach(callback, thisObject) Execute the `callback` function for each element in the current array.
<static>	$.js.Array.indexOf(value, offset) Return the first index where the given value is found in the current array.
<static>	$.js.Array.join(separator) Join all the elements from the current array into a single string using a separator.
<static>	$.js.Array.lastIndexOf(value, offset) Return the last index where the given value is found in the current array.
<static>	$.js.Array.map(callback, thisObject) Create a new array with the same length as the current array using the values returned by the `callback` function.
<static>	$.js.Array.reduce(callback, initialValue) Apply the `callback` function to two values from the current array, from left to right, simultaneously, for the purpose of reducing the array to a single value.
<static>	$.js.Array.reduceRight(callback, initialValue) Apply the `callback` function to two values from the current array, from right to left, simultaneously, for the purpose of reducing the array to a single value.
<static>	$.js.Array.slice(begin, end) Extract a section of the current array and return it.
<static>	$.js.Array.some(callback, thisObject) Check if the `callback` function returns true for at least one element in the current array.

Namespace Detail

$.js.Array

Holds the methods used for manipulating arrays and other array-like objects.

These methods are very similar to their Object counter-parts. Also, most of the methods (if not all) are already implemented natively in the global Array.prototype object (new in JavaScript 1.6).

By default, the global Array.prototype object is extended to contain all the methods in this namespace, if they do not exists already. Thus, native Array methods are not overwritten.

All of these methods use their this object. As such, you need to pass the correct this object.

Note that the methods provided iterate over the object properties using for (var i = 0; i < this.length; i++) { ... this[i] ... }. As such, any object can be used if it provides index-based access to its properties, together with the length property.

The implementations do minimal type checks, such that the methods can be used together with NodeLists and other Array-like objects.

In the examples provided for each method we will assume that the arrays defined already have the methods. Thus code like array.filter(callback) can be written directly.

// To use these methods with a NodeList proceed as follows:

var nodes = document.body.childNodes;

$.js.Array.forEach.call(nodes, function (node) {
  // ...
});

// Instead of forEach, you can use any of the methods defined in this
// namespace.

Additionally, you can extend your object to have all these methods:

$.extend.call(NodeList, $.js.Array);

// After doing so, you can directly use any desired method.
// For example:
nodes.forEach(callback).

See:: $.js.Object The Object methods which provide similar functionality for objects.

Method Detail

<static> {Array} $.js.Array.concat(value1, valueN)

Concatenate multiple arrays.

This method takes any number of arguments.

var arr1 = [5, 11, 7];
var arr2 = arr1.concat('test', [1, 2, 3], 4);

// Now arr2 = [5, 11, 7, 'test', 1, 2, 3, 4].

Parameters:
value1: Array/value to concatenate.
valueN Optional: Array/value to concatenate.

Returns:

{Array} The result is a new array consisting of:

the this array object on which the concat method was called;
each element of the arrays passed as arguments;
if an argument is not an array, then the argument value is added as-is.

The current array is not altered, nor the arrays passed as arguments.

<static> {Boolean} $.js.Array.every(callback, thisObject)

Check if the callback function returns true for every element in the current array.

The callback function is invoked for each element in the current array, and it is given three arguments: the value, the index, and the entire array being iterated over.

Iteration over the array stops once reaching the end, or once the callback function returns false.

This method does not alter the current array.

var arr = [10, 11, 12];

// The following returns true.
arr.every(function (value) {
  return value > 9;
});

Parameters:
{Function} callback: The callback function used for traversing the current array.
{Object} thisObject Optional: The object which will be the this within the scope of the callback function, for each invocation.

Throws:
{TypeError}: If callback is not a function.

Returns:: {Boolean} False is returned if the callback returns false once. Otherwise, this method returns true.

See:: $.js.Object.every

<static> {Array} $.js.Array.filter(callback, thisObject)

Filter the current array using the callback function.

The callback function is invoked for each element in the current array, and it is given three arguments: the value, the index, and the entire array being iterated over.

This method does not alter the current array.

var arr1 = [5, 11, 7];

// Filter only the elements with a value lower than 10:

var arr2 = arr1.filter(
  function (value, index, array) {
    return value < 10;
  }
);

// Now arr2 = [5, 7].

Parameters:
{Function} callback: The callback function used for filtering the current array.
{Object} thisObject Optional: The object which will be the this within the scope of the callback function, for each invocation.

Throws:
{TypeError}: If callback is not a function.

Returns:: {Array} The new array contains only the elements for which the callback function returned true.

See:: $.js.Object.filter

<static> $.js.Array.forEach(callback, thisObject)

Execute the callback function for each element in the current array.

The callback function is invoked with three arguments: the value, the index, and the entire array being iterated over.

This method does not alter the current array.

var arr = [10, 11, 12];

// alert() each index and value.
arr.forEach(
  function (value, index) {
    alert(index + ' : ' + value);
  }
);

Parameters:
{Function} callback: The callback function used for traversing the current array.
{Object} thisObject Optional: The object which will be the this within the scope of the callback function, for each invocation.

Throws:
{TypeError}: If callback is not a function.

See:: $.js.Object.forEach

<static> {Number} $.js.Array.indexOf(value, offset)

Return the first index where the given value is found in the current array.

Note that the method uses strict comparison for finding the value (===).

var arr = ['a', 'b', 'c', 'd', 'b'];
arr.indexOf('b');
// Returns 1.

arr.indexOf('b', 2);
// Returns 4.

arr.indexOf('b', -2);
// Returns 4.

Parameters:

value

The value you want to find in the current array.

{Number} offset Optional, Default: 0

Zero-based index from where to start searching the array.

If the argument is not given, the entire array is searched.

If the number is negative, then the offset is considered to be an offset from the end of the array. Thus, given a negative index like -3, it would mean that only the last three elements are checked.

The method always starts searching from the calculated/given offset increasing one by one up to the array length (forward search).

Throws:
{TypeError}: If value is undefined.

Returns:: {Number} The element index where the first occurrence of value was found in the current array. If the value was not found, -1 is returned.

See:: $.js.Array.lastIndexOf

<static> {String} $.js.Array.join(separator)

Join all the elements from the current array into a single string using a separator.

Each element of the array is converted to a string using the automatic toString() method invocation. A string separator is added into the result string between each array element.

This method does not alter the current array.

var arr = ['a', 'b', 'c'];
var str = arr.join('-');

// Now str = 'a-b-c'.

Parameters:
{String} separator Optional: The separator string which gets added between each array element into the result string. If the argument is not provided, then a comma will be used.

Returns:: {String} The new string containing all the elements in the current array, converted into strings, separated by the given separator.

<static> {Number} $.js.Array.lastIndexOf(value, offset)

Return the last index where the given value is found in the current array.

Note that the method uses strict comparison for finding the value (===).

var arr = ['a', 'b', 'c', 'd', 'b'];
arr.lastIndexOf('b');
// Returns 4.

arr.lastIndexOf('b', 2);
// Returns 1.

arr.lastIndexOf('b', -2);
// Returns 1.

Parameters:

value

The value you want to find in the current array.

{Number} offset Optional, Default: this.length

Zero-based index from where to start searching backwards.

If the argument is not given, the entire array is searched.

If the number is negative, then the offset is considered to be an offset from the end of the array. Thus, given a negative index like -3, it would mean that the last two elements are not checked.

The method always starts searching from the calculated/given offset decreasing one by one, down to index 0 (backwards search).

Throws:
{TypeError}: If value is undefined.

Returns:: {Number} The element index where the last occurrence of value was found in the current array. If the value was not found, -1 is returned.

See:: $.js.Array.indexOf

<static> {Array} $.js.Array.map(callback, thisObject)

Create a new array with the same length as the current array using the values returned by the callback function.

The callback function is invoked for each element in the current array, and it is given three arguments: the value, the index, and the entire array being iterated over.

This method does not alter the current array.

var arr1 = [5, 11, 7];

// Let's double the numbers:
var arr2 = arr1.map(function (value) {
  return value * 2;
});

// Now arr2 = [10, 22, 14].

Parameters:
{Function} callback: The callback function used for traversing the current array.
{Object} thisObject Optional: The object which will be the this within the scope of the callback function, for each invocation.

Throws:
{TypeError}: If callback is not a function.

Returns:: {Array} The new array has the same length as the current array, but the values are those returned by the callback function.

See:: $.js.Object.map

<static> $.js.Array.reduce(callback, initialValue)

Apply the callback function to two values from the current array, from left to right, simultaneously, for the purpose of reducing the array to a single value.

The callback function is called for each element in the current array, and it is given four arguments: the previous value, the current value, the current index, and the entire array being iterated over.

This method does not alter the current array.

Iteration starts from the first element in the current array (index 0) going up to the last element (array.length-1), one by one.

var arr = [5, 10, 6];

// Let's calculate the sum:
var result = arr.reduce(
  function (sum, value) {
    return sum + value;
  },
0);

// Now result = 21.

Parameters:
{Function} callback: The callback function used for traversing the current array.
initialValue Optional: The initial value used when the callback function is first invoked. If the initial value is not provided, then the method uses the value of the first element found in the array being iterated.

Throws:
{TypeError}: If callback is not a function.

Returns:: The result of the last callback function invocation.

See:: $.js.Array.reduceRight; $.js.Object.reduce

<static> $.js.Array.reduceRight(callback, initialValue)

Apply the callback function to two values from the current array, from right to left, simultaneously, for the purpose of reducing the array to a single value.

This method does not alter the current array.

Iteration starts from the last element in the current array (array.length-1) going down to 0, the first element, one by one.

var arr = [5, 10, 6];

// Let's calculate the sum:
var result = arr.reduce(function (sum, value) {
  return sum + value;
}, 0);

// Now result = 21.

Parameters:
{Function} callback: The callback function used for traversing the current array.
initialValue Optional: The initial value used when the callback function is first invoked. If the initial value is not provided, then the method uses the value of the last element found in the array being iterated.

Throws:
{TypeError}: If callback is not a function.

Returns:: The result of the last callback function invocation.

See:: $.js.Array.reduce; $.js.Object.reduce

<static> {Array} $.js.Array.slice(begin, end)

Extract a section of the current array and return it.

var arr1 = ['a', 'b', 'c', 'd'];
var arr2 = arr1.slice(1, 3);
// Now arr2 = ['b', 'c'].

var arr3 = arr1.slice(1);
// Now arr3 = ['b', 'c', 'd'].

var arr4 = arr1.slice(0, -2);
// Now arr4 = ['a', 'b'].

Parameters:

{Number} begin

Zero-based index from where to start the extraction of array elements.

{Number} end Optional, Default: this.length

Zero-based index where to end the extraction of array elements.

If the argument is not given, then the end is considered the array length. Thus, the slice being extracted contains all the array elements from the given begin index.

If the number is negative, then the end index is calculated by a simple formula: end = array.length - end. Thus, given a negative index like -3, it would mean that the slice being extracted will not contain the last three elements.

Throws:
{TypeError}: If begin is not a number, or if it is a negative number.
{TypeError}: If end is provided, but it is not a number.

Returns:: {Array} The new array returned contains all the elements starting from the begin index (including it) up to the end index (excluding it).

<static> {Boolean} $.js.Array.some(callback, thisObject)

Check if the callback function returns true for at least one element in the current array.

The callback function is invoked for each element in the current array, and it is given three arguments: the value, the index, and the entire array being iterated over.

Iteration over the array stops once reaching the end, or once the callback function returns true.

This method does not alter the current array.

var arr = [10, 11, 12];

// The following returns true.
arr.some(function (value) {
  return value > 11;
});

Parameters:
{Function} callback: The callback function used for traversing the current array.
{Object} thisObject Optional: The object which will be the this within the scope of the callback function, for each invocation.

Throws:
{TypeError}: If callback is not a function.

Returns:: {Boolean} True is returned if the callback returns true once. Otherwise, this method returns false.

See:: $.js.Object.some

Classes

Namespace $.js.Array