Array

RightJS extends the Array unit prototype in several ways. First of all it adds standard JavaScript 1.6 methods like map, filter and so on to browsers that don’t support these methods yet. In other words: You can use these new JavaScript 1.6 features without having to worry whether your browsers support it or not.

Secondly, it provides self-referential callback definitions by method names, which is extremely handy when you need to just call the same method on all array elements or process the same attribute. For example:

var elements = $$('some css rule');

elements.each('hide');
elements.each('addClass', 'marked');
elements.each('onClick', function() {});

var ids = elements.map('get', 'id');
var classes = elements.map('get', 'className').map('split', /\s+/).flatten().uniq();

var visible_elements = elements.filter('visible');
var marked_elements = elements.filter('hasClass', 'marked');

Finally, it adds several additional but standard methods like compact, uniq or merge. Most of them are equivalents of Ruby Array methods.

Iterators Handling

There are two ways of using iterators. Either pass a lambda function, which will receive the following three arguments on every iteration:

  • the current array element
  • the element index in the array
  • the instance of the array itself

Or pass a method name (string) as the first argument and optional additional arguments. The method will be called on every iteration along with the additional arguments, for example:

[...].each('foo', 1, 2, 3);

The method ‘foo(1, 2, 3)’ will be called for every element of the array.

Methods

include, clean, clone, compact, each, empty, every, filter, first, flatten, includes, indexOf, last, lastIndexOf, map, max, merge, min, random, reject, shuffle, size, some, sortBy, sum, uniq, walk, without

top ↑include

Array.include(Object new_methods[, Boolean dont_overwrite) -> Array

Description

Registers new functionality for Array instances

If the second argument is true, then the method will skip already existing methods

Example

Array.include({
double: function() {
return [this.clone(), this.clone()];
}
});

[1].double(); // -> [[1], [1]]

top ↑clean

clean() -> Array self

Description

Shrinks the array to zero elements without loosing the object reference.

top ↑clone

clone() -> new Array

Description

Creates a new array that contains all the same elements as the original one.

top ↑compact

compact() -> Array new

Description

Creates a new array that contains all non-null and non-undefined elements from the original one.

Example

[null, 0, undefined, 1, 2, 3, null].compact();

// -> [0, 1, 2, 3];

top ↑each

each(Function lambda[, Object scope]) -> Array self
each(String name[, argument, ...]) -> Array self

Description

Calls the given function in the given optional scope on every element in the array.

Example

var elements = some_html_elements_list;

elements.each(function(element, i) {
if (i % 2 == 0) {
element.hide();
} else {
element.show();
}
});

elements.each('toggle'); // will call toggle() on every element of the array
elements.each('addClass', 'marked'); // will add the 'marked' class to every element

top ↑empty

empty() -> boolean

Description

Checks if the array contains no elements.

top ↑every

every() -> boolean
every(Function lambda[, Object scope]) -> boolean
every(String name[, argument, ...]) -> boolean

Description

Checks if every item in the array passes the condition in the given function.

If no function is provided, every element will be checked as a boolean value:

Example

[1,2,3,4].every() // -> true
[0,1,2,3].every() // -> false

[1,2,3].every(function(i) { return i > 0}) // -> true
[0,1,2].every(function(i) { return i > 0}) // -> false

['moo', 'foo', 'boo'].every('match', 'oo') // -> true
['moo', 'foo', 'bar'].every('match', 'oo') // -> false

top ↑filter

filter(Function lambda[, Object scope]) -> Array new
filter(String name[, argument, ...]) -> Array new

Description

Creates a new array that contains all the items from the original array that pass the condition in the lambda function:

Example

var strings = ['anny', 'manny', 'banny', 'bob'];

strings.filter(function(string, i) {
return string.length > (i+1);
});
// -> ['anny', 'manny', 'banny'];

strings.filter('match', /[a-z]ann/);
// -> ['anny', 'manny', 'banny']

top ↑first

first() -> mixed
first([Function lambda[, Object scope]]) -> mixed
first([String name[, argument, ...]]) -> mixed

Description

Returns the first element of the array or undefined if the array is empty.

If a callback is provided, the method will return the first element that passes the condition in the function:

Example

[1,2,3,4].first() // -> 1

[1,2,3,4].first(function(i) { return i > 1; }) // -> 2

['bar', 'foo', 'moo'].first('match', 'oo') // -> 'foo'

top ↑flatten

flatten() -> Array new

Description

Converts a multi-dimensional array into a flat list.

Example

[0,1,[2,3,[4,5,[6,7],8],9]].flatten();

// -> [0,1,2,3,4,5,6,7,8,9];

top ↑includes

includes(mixed value[, mixed value,...]) -> boolean

Description

Checks whether the given value is present in the array. If several values are passed, the presence of all of them are checked:

Example

[0,1,2,3].includes(0); // true
[0,1,2,3].includes(4); // false
[0,1,2,3].includes(1,2); // true
[0,1,2,3].includes(2,4); // false

top ↑indexOf

indexOf(mixed value) -> Integer

Description

Searches the array for the given value and returns the index of the first appearance or -1 if the value is not found in the array.

top ↑last

last() -> mixed
last([Function lambda[, Object scope]]) -> mixed
last([String name[, argument, ...]]) -> mixed

Description

Returns the last element of the array or undefined if the array is empty.

If a callback is provided, the method will return the last element that passes the condition in the function:

Example

[1,2,3,4].last() // -> 4

[1,2,3,4].last(function(i) { return i < 4; }) // -> 3

['foo', 'moo', 'bar'].last('match', 'oo') // -> 'moo'

top ↑lastIndexOf

lastIndexOf(mixed value) -> Integer

Description

Searches the array for the given value and returns the index of the last appearance or -1 if the value is not found in the array.

top ↑map

map(Function lambda[, Object scope]) -> Array new
map(String name[, argument, ...]) -> Array new

Description

Collects the results of applying the lambda function on every element of the array.

Example

var strings = ['anny', 'banny', 'manny'];

strings.map(function(string, i) {
return (i+1)+'. '+string;
});

// -> ['1. anny', '2. banny', '3. manny'];

strings.map('capitalize');

// -> ['Anny', 'Banny', 'Manny'];

strings.map('replace', 'nn', 'b');

// -> ['aby', 'baby', 'maby'];

top ↑max

max() -> number maximal

Description

Returns a maximal number in the array

Example

[1, 2, 3].max(); // -> 3

top ↑merge

merge(Array list[, Array list, ...]) -> Array new

Description

Picks up items from the given arrays that do not exist in the current array, combines them with the items from the current array and returns the result as a new array.

Example

[0,1,2,3].merge([2,3,4], [3,4,5], [1,5,6]);

// -> [0,1,2,3,4,5,6];

top ↑min

min() -> number minimal

Description

Returns a minimal number in the array

Example

[1, 2, 3].min(); // -> 1

top ↑random

random() -> mixed

Description

Returns a random element from the array or undefined if the array is empty.

top ↑reject

reject(Function lambda[, Object scope]) -> Array new
reject(String name[, argument, ...]) -> Array new

Description

An opposite to the filter method

Example

var strings = ['anny', 'manny', 'banny', 'bob'];

strings.reject(function(string, i) {
return string.length > (i+1);
});
// -> ['bob'];

strings.reject('match', /[a-z]ann/);
// -> ['bob']

top ↑shuffle

shuffle() -> Array new

Description

Creates a new array, which contains has all the same items as the original one but in a random order.

Example

[0,1,2,3,4].shuffle();

// -> [3, 4, 0, 1, 2]

top ↑size

size() -> Integer

Description

Returns the length of the array.

Example

[1,2,3].size(); // -> 3

top ↑some

some() -> boolean
some(Function lambda[, Object scope]) -> boolean
some(String name[, argument, ...]) -> boolean

Description

Checks if any of the elements in the array passes the condition in the function.

If no function is provided, every element will be checked as a boolean value:

Example

[0,false,1].some() // -> true
[0,false,null].some() // -> false

[0,1,2].some(function(i) { return i == 0; }) // -> true
[1,2,3].some(function(i) { return i == 0; }) // -> false

['foo', 'bar'].some('match', 'bar') // -> true
['foo', 'boo'].some('match', 'bar') // -> false

top ↑sortBy

sortBy(Function lambda[, scope]) -> Array new
sortBy(String attr_name[, arguments]) -> Array new

Description

Creates a new array by sorting the current one. Sorting is done by the results of either the given lambda function or the given attribute (string):

Example

[{t:3}, {t:2}, {t:1}].sortBy(function(element) {
return element.t;
});

// -> [{t:1}, {t:2}, {t:3}]

[{t:3}, {t:2}, {t:1}].sortBy('t');

// -> [{t:1}, {t:2}, {t:3}]

top ↑sum

sum() -> number sum

Description

Returns a sum of all numbers in the array

Example

[1, 2, 3].sum(); // -> 6

top ↑uniq

uniq() -> Array new

Description

Creates a new array that contains only unique entries of the original

Example

[0,1,1,2,0,1,2,3,3].uniq();

// -> [0,1,2,3];

top ↑walk

walk(Function lambda[, Object scope]) -> Array self
walk(String name[, argument, ...]) -> Array self

Description

Modifies every element of the array by passing them through the given lambda function:

Example

var names = ['anny', 'manny', 'banny', 'bob'];

names.walk(function(name, i) {
return (i+1)+'. '+name;
});

// -> ['1. anny', '2. manny', '3. banny', '4. bob'];

names.walk('split', '. ');

// [['1', 'anny'], ['2', 'manny'], ['3', 'banny'], ['4', 'bob']];

names.walk('last').walk('capitalize');

// ['Anny', 'Manny', 'Banny', 'Bob'];

top ↑without

without(mixed value[, mixed value, ...]) -> Array new

Description

Creates a copy of the array without the specified elements.

Example

[0,1,2,3].without(1,3);

// -> [0,2];