Version 3.17.2
Show:

Array Class

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

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.

Item Index

Methods

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 arrays consisting entirely of strings or entirely of numbers, whereas unique may be used with other value types (but is slower).

Using dedupe() with values other than strings or numbers, or with arrays containing a mix of strings and numbers, may result in unexpected behavior.

Parameters:

Returns:

Array:

Copy of array containing no duplicate values.

each

(
  • array
  • fn
  • [thisObj]
)
YUI static

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

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

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

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

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

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

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:

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.