Array Class
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]
Parameters:
-
thingAnyThe thing to arrayify.
-
[startIndex=0]Number optionalIf 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 optionalIf
true, thing will be treated as an array-like collection no matter what.
Returns:
A native array created from thing, according to the rules described above.
Index
Methods
dedupe
-
array
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:
-
arrayString | Number[]Array of strings or numbers to dedupe.
Returns:
Copy of array containing no duplicate values.
each
-
array -
fn -
[thisObj]
Executes the supplied function on each item in the array. This method wraps
the native ES5 Array.forEach() method if available.
Parameters:
-
arrayArrayArray to iterate.
-
fnFunctionFunction to execute on each item in the array. The function will receive the following arguments:
-
itemAnyCurrent array item.
-
indexNumberCurrent array index.
-
arrayArrayArray being iterated.
-
-
[thisObj]Object optionalthisobject to use when calling fn.
Returns:
The YUI instance.
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:
-
aArraythe array to iterate.
-
fFunctionthe function to execute on each item.
-
[o]Object optionalOptional context object.
Returns:
true if every item in the array returns true from the
supplied function, false otherwise.
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:
-
aArrayArray to filter.
-
fFunctionFunction to execute on each item.
-
[o]Object optionalOptional context object.
Returns:
Array of items for which the supplied function returned a truthy value (empty if it never returned a truthy value).
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:
-
aArraythe array to search.
-
fFunctionthe function to execute on each item. Iteration is stopped as soon as this function returns
true. -
[o]Object optionalOptional context object.
Returns:
the first item that the supplied function returns true for,
or null if it never returns true.
flatten
-
a
Flattens an array of nested arrays at any abitrary depth into a single, flat array.
Parameters:
-
aArrayArray with nested arrays to flatten.
Returns:
An array whose nested arrays have been flattened.
forEach
()
static
Alias for each().
grep
-
a -
pattern
Iterates over an array, returning a new array of all the elements that match the supplied regular expression.
Parameters:
-
aArrayArray to iterate over.
-
patternRegExpRegular expression to test against each item.
Returns:
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]
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:
-
keysStringArray of strings to use as keys.
-
[values]Array optionalArray to use as values.
Returns:
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]
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:
-
arrayArrayArray to search.
-
valueAnyValue to search for.
-
[from=0]Number optionalThe index at which to begin the search.
Returns:
Index of the item strictly equal to value, or -1 if not
found.
invoke
-
items -
name -
[args*]
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:
-
itemsArrayArray of objects supporting the named method.
-
nameStringthe name of the method to execute on each item.
-
[args*]Any optionalAny number of additional args are passed as parameters to the execution of the named method.
Returns:
All return values, indexed according to the item index.
Example:
Y.Array.invoke(arrayOfDrags, 'plug', Y.Plugin.DDProxy);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:
-
aArrayArray to search in.
-
valAnyValue to search for.
-
[fromIndex]Number optionalIndex 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
-1will be returned.
Returns:
Index of the item that contains the value, or -1 if not
found.
map
-
a -
f -
[o]
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:
-
aArraythe array to iterate.
-
fFunctionthe function to execute on each item.
-
[o]Object optionalOptional context object.
Returns:
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
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.
Returns:
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]
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:
-
aArrayArray to iterate over.
-
fFunctionFunction to execute for each item in the array. It will receive the following arguments:
-
itemAnyCurrent item.
-
indexNumberIndex of the current item.
-
arrayArrayThe array being iterated.
-
-
[o]Object optionalOptional execution context.
Returns:
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]
Executes the supplied function on each item in the array, "folding" the array into a single value.
Parameters:
-
aArrayArray to iterate.
-
initAnyInitial value to start with.
-
fFunctionFunction to execute on each item. This function should update and return the value of the computation. It will receive the following arguments:
-
previousValueAnyValue returned from the previous iteration, or the initial value if this is the first iteration.
-
currentValueAnyValue of the current item being iterated.
-
indexNumberIndex of the current item.
-
arrayArrayArray being iterated.
-
-
[o]Object optionalOptional context object.
Returns:
Final result from iteratively applying the given function to each element in the array.
reject
-
a -
f -
[o]
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:
-
aArraythe array to iterate.
-
fFunctionthe function to execute on each item.
-
[o]Object optionalOptional context object.
Returns:
The items for which the supplied function returned false.
some
-
array -
fn -
[thisObj]
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:
-
arrayArrayArray to iterate over.
-
fnFunctionFunction to execute on each item. The function will receive the following arguments:
-
valueAnyCurrent array item.
-
indexNumberCurrent array index.
-
arrayArrayArray being iterated over.
-
-
[thisObj]Object optionalthisobject to use when calling fn.
Returns:
true if the function returns a truthy value on any of the
items in the array; false otherwise.
test
-
obj
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:
-
objObjectObject to test.
Returns:
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]
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:
-
arrayArrayArray to dedupe.
-
[testFn]Function optionalCustom 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.
-
aAnyFirst value to compare.
-
bAnySecond value to compare.
-
indexNumberIndex of the current item in the original array.
-
arrayArrayThe original array.
-
Returns:
Copy of the input array with duplicate items removed.
zip
-
a -
a2
Creates an array of arrays by pairing the corresponding elements of two arrays together into a new array.
Parameters:
-
aArrayArray to iterate over.
-
a2ArrayAnother array whose values will be paired with values of the first array.
Returns:
An array of arrays formed by pairing each element of the first array with an item in the second array having the corresponding index.