#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# Array Class

Defined in: `yui/js/yui-array.js:11`
Module: yui-base
Parent Module: yui

Provides utility methods for working with arrays. Additional array helpers can be found in the `collection` and `array-extras` modules.

`Y.Array(thing)` returns a native array created from thing. Depending on thing's type, one of the following will happen:

- Arrays are returned unmodified unless a non-zero startIndex is specified.
- Array-like collections (see `Array.test()`) are converted to arrays.
- For everything else, a new array is created with thing as the sole item.

Note: elements that are also collections, such as `<form>` and `<select>` elements, are not automatically converted to arrays. To force a conversion, pass `true` as the value of the force parameter.

## Constructor

### `Array`

(

- `thing`
- `[startIndex=0]`
- `[force=false]`

)
Array

Defined in `yui/js/yui-array.js:11`

#### Parameters:

- `thing` Any

  The thing to arrayify.

- `[startIndex=0]` Number optional

  If non-zero and thing is an array or array-like collection, a subset of items starting at the specified index will be returned.

- `[force=false]` Boolean optional

  If `true`, thing will be treated as an array-like collection no matter what.

#### Returns:

Array: A native array created from thing, according to the rules described above.

- Index
- Methods

## Item Index

### Methods

- dedupe static
- each static
- every static
- filter static
- find static
- flatten static
- forEach static
- grep static
- hash static
- indexOf static
- invoke static
- lastIndexOf static
- map static
- numericSort static
- partition static
- reduce static
- reject static
- some static
- test static
- unique static
- zip static

## Methods

### `dedupe`

(

- `array`

)
Array static

Defined in `yui/js/yui-array.js:65`

Available since 3.4.0

Dedupes an array of strings, returning an array that's guaranteed to contain only one copy of a given string.

This method differs from `Array.unique()` in that it's optimized for use only with strings, whereas `unique` may be used with other types (but is slower). Using `dedupe()` with non-string values may result in unexpected behavior.

#### Parameters:

- `array` String[]

  Array of strings to dedupe.

#### Returns:

Array: Deduped copy of array.

### `each`

(

- `array`
- `fn`
- `[thisObj]`

)
YUI static

Defined in `yui/js/yui-array.js:96`

Executes the supplied function on each item in the array. This method wraps the native ES5 `Array.forEach()` method if available.

#### Parameters:

- `array` Array

  Array to iterate.

- `fn` Function

  Function to execute on each item in the array. The function will receive the following arguments:

  - `item` Any

    Current array item.

  - `index` Number

    Current array index.

  - `array` Array

    Array being iterated.

- `[thisObj]` Object optional

  `this` object to use when calling fn.

#### Returns:

YUI: The YUI instance.

### `every`

(

- `a`
- `f`
- `[o]`

)
Boolean static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:166`

Executes the supplied function on each item in the array. Iteration stops if the supplied function does not return a truthy value.

#### Parameters:

- `a` Array

  the array to iterate.

- `f` Function

  the function to execute on each item.

- `[o]` Object optional

  Optional context object.

#### Returns:

Boolean: `true` if every item in the array returns `true` from the supplied function, `false` otherwise.

### `filter`

(

- `a`
- `f`
- `[o]`

)
Array static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:113`

Executes the supplied function on each item in the array. Returns a new array containing the items for which the supplied function returned a truthy value.

#### Parameters:

- `a` Array

  Array to filter.

- `f` Function

  Function to execute on each item.

- `[o]` Object optional

  Optional context object.

#### Returns:

Array: Array of items for which the supplied function returned a truthy value (empty if it never returned a truthy value).

### `find`

(

- `a`
- `f`
- `[o]`

)
Object static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:273`

Executes the supplied function on each item in the array, searching for the first item that matches the supplied function.

#### Parameters:

- `a` Array

  the array to search.

- `f` Function

  the function to execute on each item. Iteration is stopped as soon as this function returns `true`.

- `[o]` Object optional

  Optional context object.

#### Returns:

Object: the first item that the supplied function returns `true` for, or `null` if it never returns `true`.

### `flatten`

(

- `a`

)
Array static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:364`

Available since 3.7.0

Flattens an array of nested arrays at any abitrary depth into a single, flat array.

#### Parameters:

- `a` Array

  Array with nested arrays to flatten.

#### Returns:

Array: An array whose nested arrays have been flattened.

### `forEach`

() static

Defined in `yui/js/yui-array.js:124`

Alias for `each()`.

### `grep`

(

- `a`
- `pattern`

)
Array static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:295`

Iterates over an array, returning a new array of all the elements that match the supplied regular expression.

#### Parameters:

- `a` Array

  Array to iterate over.

- `pattern` RegExp

  Regular expression to test against each item.

#### Returns:

Array: All the items in the array that produce a match against the supplied regular expression. If no items match, an empty array is returned.

### `hash`

(

- `keys`
- `[values]`

)
Object static

Defined in `yui/js/yui-array.js:131`

Returns an object using the first array as keys and the second as values. If the second array is not provided, or if it doesn't contain the same number of values as the first array, then `true` will be used in place of the missing values.

#### Parameters:

- `keys` String[]

  Array of strings to use as keys.

- `[values]` Array optional

  Array to use as values.

#### Returns:

Object: Hash using the first array as keys and the second as values.

#### Example:

    Y.Array.hash(['a', 'b', 'c'], ['foo', 'bar']);
    // => {a: 'foo', b: 'bar', c: true}

### `indexOf`

(

- `array`
- `value`
- `[from=0]`

)
Number static

Defined in `yui/js/yui-array.js:162`

Returns the index of the first item in the array that's equal (using a strict equality check) to the specified value, or `-1` if the value isn't found.

This method wraps the native ES5 `Array.indexOf()` method if available.

#### Parameters:

- `array` Array

  Array to search.

- `value` Any

  Value to search for.

- `[from=0]` Number optional

  The index at which to begin the search.

#### Returns:

Number: Index of the item strictly equal to value, or `-1` if not found.

### `invoke`

(

- `items`
- `name`
- `[args*]`

)
Array static

Provided by the array-invoke module.

Defined in `collection/js/invoke.js:6`

Executes a named method on each item in an array of objects. Items in the array that do not have a function by that name will be skipped.

#### Parameters:

- `items` Array

  Array of objects supporting the named method.

- `name` String

  the name of the method to execute on each item.

- `[args*]` Any optional

  Any number of additional args are passed as parameters to the execution of the named method.

#### Returns:

Array: All return values, indexed according to the item index.

#### Example:

    Y.Array.invoke(arrayOfDrags, 'plug', Y.Plugin.DDProxy);

### `lastIndexOf`

(

- `a`
- `val`
- `[fromIndex]`

)
Number static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:12`

Returns the index of the last item in the array that contains the specified value, or `-1` if the value isn't found.

#### Parameters:

- `a` Array

  Array to search in.

- `val` Any

  Value to search for.

- `[fromIndex]` Number optional

  Index at which to start searching backwards. Defaults to the array's length - 1. If negative, it will be taken as an offset from the end of the array. If the calculated index is less than 0, the array will not be searched and `-1` will be returned.

#### Returns:

Number: Index of the item that contains the value, or `-1` if not found.

### `map`

(

- `a`
- `f`
- `[o]`

)
Array static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:192`

Executes the supplied function on each item in the array and returns a new array containing all the values returned by the supplied function.

#### Parameters:

- `a` Array

  the array to iterate.

- `f` Function

  the function to execute on each item.

- `[o]` Object optional

  Optional context object.

#### Returns:

Array: A new array containing the return value of the supplied function for each item in the original array.

#### Example:

    // Convert an array of numbers into an array of strings.
    Y.Array.map([1, 2, 3, 4], function (item) {
      return '' + item;
    });
    // => ['1', '2', '3', '4']

### `numericSort`

(

- `a`
- `b`

)
Number static

Defined in `yui/js/yui-array.js:202`

Numeric sort convenience function.

The native `Array.prototype.sort()` function converts values to strings and sorts them in lexicographic order, which is unsuitable for sorting numeric values. Provide `Array.numericSort` as a custom sort function when you want to sort values in numeric order.

#### Parameters:

- `a` Number

  First value to compare.

- `b` Number

  Second value to compare.

#### Returns:

Number: Difference between a and b.

#### Example:

    [42, 23, 8, 16, 4, 15].sort(Y.Array.numericSort);
    // => [4, 8, 15, 16, 23, 42]

### `partition`

(

- `a`
- `f`
- `[o]`

)
Object static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:312`

Partitions an array into two new arrays, one with the items for which the supplied function returns `true`, and one with the items for which the function returns `false`.

#### Parameters:

- `a` Array

  Array to iterate over.

- `f` Function

  Function to execute for each item in the array. It will receive the following arguments:

  - `item` Any

    Current item.

  - `index` Number

    Index of the current item.

  - `array` Array

    The array being iterated.

- `[o]` Object optional

  Optional execution context.

#### Returns:

Object: An object with two properties: `matches` and `rejects`. Each is an array containing the items that were selected or rejected by the test function (or an empty array if none).

### `reduce`

(

- `a`
- `init`
- `f`
- `[o]`

)
Any static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:231`

Executes the supplied function on each item in the array, "folding" the array into a single value.

#### Parameters:

- `a` Array

  Array to iterate.

- `init` Any

  Initial value to start with.

- `f` Function

  Function to execute on each item. This function should update and return the value of the computation. It will receive the following arguments:

  - `previousValue` Any

    Value returned from the previous iteration, or the initial value if this is the first iteration.

  - `currentValue` Any

    Value of the current item being iterated.

  - `index` Number

    Index of the current item.

  - `array` Array

    Array being iterated.

- `[o]` Object optional

  Optional context object.

#### Returns:

Any: Final result from iteratively applying the given function to each element in the array.

### `reject`

(

- `a`
- `f`
- `[o]`

)
Array static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:148`

The inverse of `Array.filter()`. Executes the supplied function on each item. Returns a new array containing the items for which the supplied function returned `false`.

#### Parameters:

- `a` Array

  the array to iterate.

- `f` Function

  the function to execute on each item.

- `[o]` Object optional

  Optional context object.

#### Returns:

Array: The items for which the supplied function returned `false`.

### `some`

(

- `array`
- `fn`
- `[thisObj]`

)
Boolean static

Defined in `yui/js/yui-array.js:225`

Executes the supplied function on each item in the array. Returning a truthy value from the function will stop the processing of remaining items.

#### Parameters:

- `array` Array

  Array to iterate over.

- `fn` Function

  Function to execute on each item. The function will receive the following arguments:

  - `value` Any

    Current array item.

  - `index` Number

    Current array index.

  - `array` Array

    Array being iterated over.

- `[thisObj]` Object optional

  `this` object to use when calling fn.

#### Returns:

Boolean: `true` if the function returns a truthy value on any of the items in the array; `false` otherwise.

### `test`

(

- `obj`

)
Number static

Defined in `yui/js/yui-array.js:253`

Evaluates obj to determine if it's an array, an array-like collection, or something else. This is useful when working with the function `arguments` collection and `HTMLElement` collections.

Note: This implementation doesn't consider elements that are also collections, such as `<form>` and `<select>`, to be array-like.

#### Parameters:

- `obj` Object

  Object to test.

#### Returns:

Number: A number indicating the results of the test:

- 0: Neither an array nor an array-like collection.
- 1: Real array.
- 2: Array-like collection.

### `unique`

(

- `array`
- `[testFn]`

)
Array static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:55`

Returns a copy of the input array with duplicate items removed.

Note: If the input array only contains strings, the `Y.Array.dedupe()` method is a much faster alternative.

#### Parameters:

- `array` Array

  Array to dedupe.

- `[testFn]` Function optional

  Custom function to use to test the equality of two values. A truthy return value indicates that the values are equal. A falsy return value indicates that the values are not equal.

  - `a` Any

    First value to compare.

  - `b` Any

    Second value to compare.

  - `index` Number

    Index of the current item in the original array.

  - `array` Array

    The original array.

#### Returns:

Array: Copy of the input array with duplicate items removed.

### `zip`

(

- `a`
- `a2`

)
Array static

Provided by the array-extras module.

Defined in `collection/js/array-extras.js:344`

Creates an array of arrays by pairing the corresponding elements of two arrays together into a new array.

#### Parameters:

- `a` Array

  Array to iterate over.

- `a2` Array

  Another array whose values will be paired with values of the first array.

#### Returns:

Array: An array of arrays formed by pairing each element of the first array with an item in the second array having the corresponding index.