Array Atom feed
Prototype extends all native Javascript arrays with quite a few powerful methods.
This is done in two ways:
- It mixes in the
Enumerable
module, which brings a ton of methods in already. - It adds quite a few extra methods, which are documented in this section.
With Prototype, arrays become much, much more than the trivial objects we were used to manipulate, limiting ourselves to using their length
property and their []
indexing operator. They become very powerful objects, that greatly simplify the code for 99% of the common use cases involving them.
Why you should stop using for
…in
to iterate (or never take it up)
Many JavaScript authors have been misled into using the for
…in
JavaScript construct to loop over array elements. This kind of code just won’t work with Prototype.
You see, the ECMA 262 standard, which defines ECMAScript 3rd edition, supposedly implemented by all major browsers including MSIE, defines numerous methods on Array
(§15.4.4), including such nice methods as concat
, join
, pop
and push
, to name but a few among the ten methods specified.
This same standard explicitely defines that the for
…in
construct (§12.6.4) exists to enumerate the properties of the object appearing on the right side of the in
keyword. Only properties specifically marked as non-enumerable are ignored by such a loop. By default, the prototype and the length
properties are so marked, which prevents you from enumerating over array methods when using for
…in
. This comfort led developers to use for
…in
as a shortcut for indexing loops, when it is not its actual purpose.
However, Prototype has no way to mark the methods it adds to Array.prototype
as non-enumerable. Therefore, using for
…in
on arrays when using Prototype will enumerate all extended methods as well, such as those coming from the Enumerable
module, and those Prototype puts in the Array
namespace (described in this section, and listed further below).
What is a developer to do?
You can revert to vanilla loops:
for (var index = 0; index myArray.length; ++index) {
var item = myArray[index];
// Your code working on item here...
}
Or you can use iterators, such as each
:
myArray.each(function(item) {
// Your code working on item here...
});
This side-effect enforcement of the true purpose of for
…in
is actually not so much of a burden: as you’ll see, most of what you used to loop over arrays for can be concisely done using the new methods provided by Array
or the mixed-in Enumerable
module. So manual loops should be fairly rare.
A note on performance
Should you have a very large array, using iterators with lexical closures (anonymous functions that you pass to the iterators, that get invoked at every loop iteration), such as each
, or relying on repetitive array construction (such as uniq
), may yield unsatisfactory performance. In such cases, you’re better off writing manual indexing loops, but take care then to cache the length
property and use the prefix ++
operator:
// Custom loop with cached length property: maximum full-loop performance on very large arrays!
for (var index = 0, len = myArray.length; index len; ++index) {
var item = myArray[index];
// Your code working on item here...
}
Methods
clear
clear() -> Array
Clears the array (makes it empty).
clone
clone() -> newArray
Returns a duplicate of the array, leaving the original array intact.
compact
compact() -> newArray
Returns a new version of the array, without any null
/undefined
values.
each
each(iterator) -> Array
Iterates over the array in ascending numerical index order.
first
first() -> value
Returns the first item in the array, or undefined
if the array is empty.
flatten
flatten() -> newArray
Returns a “flat” (one-dimensional) version of the array. Nested arrays are recursively injected “inline.” This can prove very useful when handling the results of a recursive collection algorithm, for instance.
from
Array.from(iterable) -> actualArray
Clones an existing array or creates a new one from an array-like collection.
This is an alias for the $A() method. Refer to its page for complete description and examples.
indexOf
indexOf(value) -> position
Returns the position of the first occurrence of the argument within the array. If the argument doesn’t exist in the array, returns -1.
inspect
inspect() -> String
Returns the debug-oriented string representation of an array.
last
last() -> value
Returns the last item in the array, or undefined
if the array is empty.
reduce
reduce() -> Array | singleValue
Reduces arrays: one-element arrays are turned into their unique element, while multiple-element arrays are returned untouched.
reverse
reverse([inline = true]) -> Array
Returns the reversed version of the array. By default, directly reverses the original. If inline
is set to false
, uses a clone of the original array.
size
size() -> Number
Returns the size of the array.
toArray
toArray() -> newArray
This is just a local optimization of the mixed-in toArray
from Enumerable
.
toJSON
1.5.1
toJSON() -> String
Returns a JSON string.
uniq
uniq() -> newArray
Produces a duplicate-free version of an array. If no duplicates are found, the original array is returned.
without
without(value...) -> newArray
Produces a new version of the array that does not contain any of the specified values.