# Yahoo! UI Library

### collection 3.3.0

Yahoo! UI Library > collection > YUI~array~extras
Search:
Filters Show Private Show Protected Show Deprecated

## Class YUI~array~extras

Adds the following array utilities to the YUI instance (Y.Array). This is in addition to the methods provided in the core.

### Methods

#### Array.every

`static boolean Array.every ( a , f , o )`
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 context object.

Returns: `boolean`
  true if every item in the array returns true from the supplied function.

#### Array.filter

`static Array Array.filter ( a , f , o )`
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 context object.

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

#### Array.find

`static object Array.find ( a , f , o )`
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 on an item.
  `o <object>` Optional context object.

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

#### Array.forEach

`void Array.forEach ( )`
forEach is an alias of Array.each. This is part of the collection module.

#### Array.grep

`static Array Array.grep ( a , pattern )`
Iterates over an array, returning a new array of all the elements that match the supplied regular expression

Parameters:
  `a <Array>` a collection to iterate over.
  `pattern <RegExp>` The regular expression to test against each item.

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

#### Array.lastIndexOf

`static Number Array.lastIndexOf ( a , val , fromIndex )`
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.

#### Array.map

`static Array Array.map ( a , f , o )`
Executes the supplied function on each item in the array.

Parameters:
  `a <Array>` the array to iterate.
  `f <Function>` the function to execute on each item.
  `o <object>` Optional context object.

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

#### Array.partition

`static object Array.partition ( a , f , o )`
Partitions an array into two new arrays, one with the items that match the supplied function, and one with the items that do not.

Parameters:
  `a <Array>` a collection to iterate over.
  `f <Function>` a function that will receive each item in the collection and its index.
  `o <object>` Optional execution context of f.

Returns: `object`
  An object with two members, 'matches' and 'rejects', that are arrays containing the items that were selected or rejected by the test function (or an empty array).

#### Array.reduce

`static any Array.reduce ( a , init , f , o )`
Executes the supplied function on each item in the array. Reduce "folds" the array into a single value. The callback function receives four arguments: the value from the previous callback call (or the initial value), the value of the current element, the current index, and the array over which iteration is occurring.

Parameters:
  `a <Array>` the array to iterate.
  `init <any>` The initial value to start from.
  `f <Function>` the function to execute on each item. It is responsible for returning the updated value of the computation.
  `o <object>` Optional context object.

Returns: `any`
  A value that results from iteratively applying the supplied function to each element in the array.

#### Array.reject

`static Array Array.reject ( a , f , o )`
The inverse of filter. Executes the supplied function on each item. Returns a new array containing the items that the supplied function returned *false* for.

Parameters:
  `a <Array>` the array to iterate.
  `f <Function>` the function to execute on each item.
  `o <object>` Optional context object.

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

#### Array.unique

`static Array Array.unique ( a )`
Returns a copy of the specified array with duplicate items removed.

Parameters:
  `a <Array>` Array to dedupe.

Returns: `Array`
  Copy of the array with duplicate items removed.

#### Array.zip

`static array Array.zip ( a , a2 )`
Creates an array of arrays by pairing the corresponding elements of two arrays together into a new array.

Parameters:
  `a <Array>` a collection to iterate over.
  `a2 <Array>` another collection whose members will be paired with members of the first parameter.

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

Copyright © 2011 Yahoo! Inc. All rights reserved.