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 ↑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'];