Prototype JavaScript framework

class Array

Description

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 in a ton of methods.
  • 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 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

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.

The ECMA 262 standard, which defines ECMAScript 3rd edition, supposedly implemented by all major browsers including MSIE, defines ten methods on Array (§15.4.4), including nice methods like concat, join, pop, and push.

This same standard explicitly 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 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 (listed further below).

What you should use instead

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 Array#each:

myArray.each(function(item) {
  // Your code working on item here...
});

The inability to use for...in on arrays is not 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 and that get invoked at every loop iteration) in methods like Array#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...
}

Includes

Enumerable

Related utilities

$A, $w

Methods

Inherited from Enumerable

Class methods

  • from #

    Array.from(iterable) ⇒ Array

    Alias of: $A

Instance methods

  • clear #

    Array#clear() ⇒ Array

    Clears the array (makes it empty) and returns the array reference.

    Example
    var guys = ['Sam', 'Justin', 'Andrew', 'Dan'];
guys.clear();
// -> []
guys
// -> []

  • clone #

    Array#clone() ⇒ Array

    Returns a duplicate of the array, leaving the original array intact.

    Aliased as: Array#toArray

  • compact #

    Array#compact() ⇒ Array

    Returns a copy of the array without any null or undefined values.

    Example
    var orig = [undefined, 'A', undefined, 'B', null, 'C'];
var copy = orig.compact();
// orig -> [undefined, 'A', undefined, 'B', null, 'C'];
// copy -> ['A', 'B', 'C'];

  • first #

    Array#first() ⇒ ?

    Returns the array's first item (e.g., array[0]).

  • flatten #

    Array#flatten() ⇒ Array

    Returns a flattened (one-dimensional) copy of the array, leaving the original array unchanged.

    Nested arrays are recursively injected inline. This can prove very useful when handling the results of a recursive collection algorithm, for instance.

    Example
    var a = ['frank', ['bob', 'lisa'], ['jill', ['tom', 'sally']]];
var b = a.flatten();
// a -> ['frank', ['bob', 'lisa'], ['jill', ['tom', 'sally']]]
// b -> ['frank', 'bob', 'lisa', 'jill', 'tom', 'sally']

  • indexOf #

    Array#indexOf(item[, offset = 0]) ⇒ Number
    • item (?) – A value that may or may not be in the array.
    • offset (Number) – The number of initial items to skip before beginning the search.

    Returns the index of the first occurrence of item within the array, or -1 if item doesn't exist in the array. Array#indexOf compares items using strict equality (===).

    Examples
    [3, 5, 6, 1, 20].indexOf(1)
// -> 3

[3, 5, 6, 1, 20].indexOf(90)
// -> -1 (not found)

['1', '2', '3'].indexOf(1);
// -> -1 (not found, 1 !== '1')

  • inspect #

    Array#inspect() ⇒ String

    Returns the debug-oriented string representation of an array.

    Example
    ['Apples', {good: 'yes', bad: 'no'}, 3, 34].inspect()
// -> "['Apples', [object Object], 3, 34]"

  • intersect #

    Array#intersect(array) ⇒ Array
    • array (Array) – A collection of values.

    Returns an array containing every item that is shared between the two given arrays.

  • last #

    Array#last() ⇒ ?

    Returns the array's last item (e.g., array[array.length - 1]).

  • lastIndexOf #

    Array#lastIndexOf(item[, offset]) ⇒ Number
    • item (?) – A value that may or may not be in the array.
    • offset (Number) – The number of items at the end to skip before beginning the search.

    Returns the position of the last occurrence of item within the array — or -1 if item doesn't exist in the array.

  • reverse #

    Array#reverse([inline = true]) ⇒ Array
    • inline (Boolean) – Whether to modify the array in place. Defaults to true. Clones the original array when false.

    Reverses the array's contents, optionally cloning it first.

    Examples
    // Making a copy
var nums = [3, 5, 6, 1, 20];
var rev = nums.reverse(false);
// nums -> [3, 5, 6, 1, 20]
// rev -> [20, 1, 6, 5, 3]

// Working inline
var nums = [3, 5, 6, 1, 20];
nums.reverse();
// nums -> [20, 1, 6, 5, 3]

  • size #

    Array#size() ⇒ Number

    Returns the size of the array (e.g., array.length).

    This is just a local optimization of the mixed-in Enumerable#size which avoids array cloning and uses the array's native length property.

  • toArray #

    Array#toArray() ⇒ Array

    Alias of: Array#clone

  • toJSON #

    Array#toJSON() ⇒ String

    Returns a JSON string representation of the array.

    Example
    ['a', {b: null}].toJSON();
//-> '["a", {"b": null}]'

  • uniq #

    Array#uniq([sorted = false]) ⇒ Array
    • sorted (Boolean) – Whether the array has already been sorted. If true, a less-costly algorithm will be used.

    Produces a duplicate-free version of an array. If no duplicates are found, the original array is returned.

    On large arrays when sorted is false, this method has a potentially large performance cost.

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

['A', 'a'].uniq();
// -> ['A', 'a'] (because String comparison is case-sensitive)

  • without #

    Array#without(value[, value...]) ⇒ Array
    • value (?) – A value to exclude.

    Produces a new version of the array that does not contain any of the specified values, leaving the original array unchanged.

    Examples
    [3, 5, 6].without(3)
// -> [5, 6]

[3, 5, 6, 20].without(20, 6)
// -> [3, 5]