Array.js

Contains Array prototypes, $A, $each

License

MIT-style license.

Summary
Array.jsContains Array prototypes, $A, $each
ArrayA collection of The Array Object prototype methods.
Properties
forEachIterates through an array; This method is only available for browsers without native forEach support.
filterThis method is provided only for browsers without native filter support.
mapThis method is provided only for browsers without native map support.
everyThis method is provided only for browsers without native every support.
someThis method is provided only for browsers without native some support.
indexOfThis method is provided only for browsers without native indexOf support.
eachSame as Array.forEach.
copyreturns a copy of the array.
removeRemoves all occurrences of an item from the array.
containsTests an array for the presence of an item.
associateCreates an object with key-value pairs based on the array of keywords passed in and the current content of the array.
extendExtends an array with another one.
mergemerges an array in another array, without duplicates.
includeincludes the passed in element in the array, only if its not already present.
getRandomreturns a random item in the Array
getLastreturns the last item in the Array
Utility Functions
Functions
$A()Same as Array.copy, but as function.
$eachUse to iterate through iterables that are not regular arrays, such as builtin getElementsByTagName calls, arguments of a function, or an object.

Array

A collection of The Array Object prototype methods.

Summary
Properties
forEachIterates through an array; This method is only available for browsers without native forEach support.
filterThis method is provided only for browsers without native filter support.
mapThis method is provided only for browsers without native map support.
everyThis method is provided only for browsers without native every support.
someThis method is provided only for browsers without native some support.
indexOfThis method is provided only for browsers without native indexOf support.
eachSame as Array.forEach.
copyreturns a copy of the array.
removeRemoves all occurrences of an item from the array.
containsTests an array for the presence of an item.
associateCreates an object with key-value pairs based on the array of keywords passed in and the current content of the array.
extendExtends an array with another one.
mergemerges an array in another array, without duplicates.
includeincludes the passed in element in the array, only if its not already present.
getRandomreturns a random item in the Array
getLastreturns the last item in the Array

Properties

forEach

Iterates through an array; This method is only available for browsers without native forEach support.  For more info see http://developer.mozilla.org- /en- /docs- /Core_JavaScript_1.5_Reference:Global_Objects:Array:forEach

forEach executes the provided function (callback) once for each element present in the array. callback is invoked only for indexes of the array which have assigned values; it is not invoked for indexes which have been deleted or which have never been assigned values.

Arguments

fnfunction to execute with each item in the array; passed the item and the index of that item in the array
bindthe object to bind “this” to (see <Function.bind>)

Example

['apple','banana','lemon'].each(function(item, index){
   alert(index + " = " + item); //alerts "0 = apple" etc.
}, bindObj); //optional second arg for binding, not used here

filter

This method is provided only for browsers without native filter support.  For more info see http://developer.mozilla.org- /en- /docs- /Core_JavaScript_1.5_Reference:Objects:Array:filter

filter calls a provided callback function once for each element in an array, and constructs a new array of all the values for which callback returns a true value. callback is invoked only for indexes of the array which have assigned values; it is not invoked for indexes which have been deleted or which have never been assigned values.  Array elements which do not pass the callback test are simply skipped, and are not included in the new array.

Arguments

fnfunction to execute with each item in the array; passed the item and the index of that item in the array
bindthe object to bind “this” to (see <Function.bind>)

Example

var biggerThanTwenty = [10,3,25,100].filter(function(item, index){
 return item > 20;
});
//biggerThanTwenty = [25,100]

map

This method is provided only for browsers without native map support.  For more info see http://developer.mozilla.org- /en- /docs- /Core_JavaScript_1.5_Reference:Global_Objects:Array:map

map calls a provided callback function once for each element in an array, in order, and constructs a new array from the results. callback is invoked only for indexes of the array which have assigned values; it is not invoked for indexes which have been deleted or which have never been assigned values.

Arguments

fnfunction to execute with each item in the array; passed the item and the index of that item in the array
bindthe object to bind “this” to (see <Function.bind>)

Example

var timesTwo = [1,2,3].map(function(item, index){
 return item*2;
});
//timesTwo = [2,4,6];

every

This method is provided only for browsers without native every support.  For more info see http://developer.mozilla.org- /en- /docs- /Core_JavaScript_1.5_Reference:Global_Objects:Array:every

every executes the provided callback function once for each element present in the array until it finds one where callback returns a false value.  If such an element is found, the every method immediately returns false.  Otherwise, if callback returned a true value for all elements, every will return true. callback is invoked only for indexes of the array which have assigned values; it is not invoked for indexes which have been deleted or which have never been assigned values.

Arguments

fnfunction to execute with each item in the array; passed the item and the index of that item in the array
bindthe object to bind “this” to (see <Function.bind>)

Example

var areAllBigEnough = [10,4,25,100].every(function(item, index){
 return item > 20;
});
//areAllBigEnough = false

some

This method is provided only for browsers without native some support.  For more info see http://developer.mozilla.org- /en- /docs- /Core_JavaScript_1.5_Reference:Global_Objects:Array:some

some executes the callback function once for each element present in the array until it finds one where callback returns a true value.  If such an element is found, some immediately returns true.  Otherwise, some returns false. callback is invoked only for indexes of the array which have assigned values; it is not invoked for indexes which have been deleted or which have never been assigned values.

Arguments

fnfunction to execute with each item in the array; passed the item and the index of that item in the array
bindthe object to bind “this” to (see <Function.bind>)

Example

var isAnyBigEnough = [10,4,25,100].some(function(item, index){
 return item > 20;
});
//isAnyBigEnough = true

indexOf

This method is provided only for browsers without native indexOf support.  For more info see http://developer.mozilla.org- /en- /docs- /Core_JavaScript_1.5_Reference:Global_Objects:Array:indexOf

indexOf compares a search element to elements of the Array using strict equality (the same method used by the ===, or triple-equals, operator).

Arguments

itemany type of object; element to locate in the array
frominteger; optional; the index of the array at which to begin the search (defaults to 0)

Example

['apple','lemon','banana'].indexOf('lemon'); //returns 1
['apple','lemon'].indexOf('banana'); //returns -1

each

Same as Array.forEach.

Arguments

fnfunction to execute with each item in the array; passed the item and the index of that item in the array
bindoptional, the object that the “this” of the function will refer to.

Example

var Animals = ['Cat', 'Dog', 'Coala'];
Animals.each(function(animal){
   document.write(animal)
});

copy

returns a copy of the array.

Returns

a new array which is a copy of the current one.

Arguments

startinteger; optional; the index where to start the copy, default is 0.  If negative, it is taken as the offset from the end of the array.
lengthinteger; optional; the number of elements to copy.  By default, copies all elements from start to the end of the array.

Example

var letters = ["a","b","c"];
var copy = letters.copy();     // ["a","b","c"] (new instance)

remove

Removes all occurrences of an item from the array.

Arguments

itemthe item to remove

Returns

the Array with all occurrences of the item removed.

Example

["1","2","3","2"].remove("2") // ["1","3"];

contains

Tests an array for the presence of an item.

Arguments

itemthe item to search for in the array.
frominteger; optional; the index at which to begin the search, default is 0.  If negative, it is taken as the offset from the end of the array.

Returns

truethe item was found
falseit wasn’t

Example

["a","b","c"].contains("a"); // true
["a","b","c"].contains("d"); // false

associate

Creates an object with key-value pairs based on the array of keywords passed in and the current content of the array.

Arguments

keysthe array of keywords.

Example

var Animals = ['Cat', 'Dog', 'Coala', 'Lizard'];
var Speech = ['Miao', 'Bau', 'Fruuu', 'Mute'];
var Speeches = Animals.associate(Speech);
//Speeches['Miao'] is now Cat.
//Speeches['Bau'] is now Dog.
//...

extend

Extends an array with another one.

Arguments

arraythe array to extend ours with

Example

var Animals = ['Cat', 'Dog', 'Coala'];
Animals.extend(['Lizard']);
//Animals is now: ['Cat', 'Dog', 'Coala', 'Lizard'];

merge

merges an array in another array, without duplicates.  (case- and type-sensitive)

Arguments

arraythe array to merge from.

Example

['Cat','Dog'].merge(['Dog','Coala']); //returns ['Cat','Dog','Coala']

include

includes the passed in element in the array, only if its not already present.  (case- and type-sensitive)

Arguments

itemitem to add to the array (if not present)

Example

['Cat','Dog'].include('Dog'); //returns ['Cat','Dog']
['Cat','Dog'].include('Coala'); //returns ['Cat','Dog','Coala']

getRandom

returns a random item in the Array

getLast

returns the last item in the Array

Utility Functions

Summary
Functions
$A()Same as Array.copy, but as function.
$eachUse to iterate through iterables that are not regular arrays, such as builtin getElementsByTagName calls, arguments of a function, or an object.

Functions

$A()

Same as Array.copy, but as function.  Useful to apply Array prototypes to iterable objects, as a collection of DOM elements or the arguments object.

Example

function myFunction(){
    $A(arguments).each(argument, function(){
        alert(argument);
    });
};
//the above will alert all the arguments passed to the function myFunction.

$each

Use to iterate through iterables that are not regular arrays, such as builtin getElementsByTagName calls, arguments of a function, or an object.

Arguments

iterablean iterable element or an objct.
functionfunction to apply to the iterable.
bindoptional, the ‘this’ of the function will refer to this object.

Function argument

The function argument will be passed the following arguments.

itemthe current item in the iterator being procesed
indexinteger; the index of the item, or key in case of an object.

Examples

$each(['Sun','Mon','Tue'], function(day, index){
    alert('name:' + day + ', index: ' + index);
});
//alerts "name: Sun, index: 0", "name: Mon, index: 1", etc.
//over an object
$each({first: "Sunday", second: "Monday", third: "Tuesday"}, function(value, key){
    alert("the " + key + " day of the week is " + value);
});
//alerts "the first day of the week is Sunday",
//"the second day of the week is Monday", etc.
Same as Array.copy, but as function.
Use to iterate through iterables that are not regular arrays, such as builtin getElementsByTagName calls, arguments of a function, or an object.
Iterates through an array; This method is only available for browsers without native forEach support.
returns a copy of the array.

Documentation by Aaron Newton & Mootools Developers, generated by NaturalDocs and GeSHi