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:
+ +-
+
+
-
+
+
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:
+ +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+ +
+
+
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:
+ +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:
+ +-
+
+
-
+
+
array+ Array + + + + +++ + +Array to iterate.
+
+
+ -
+
+
fn+ Function + + + + +++ + + + +Function to execute on each item in the array. The function + will receive the following arguments:
+
+
+ -
+
+
[thisObj]+ Object + optional + + + + +++ + +
+thisobject to use when calling fn.
+
+
Returns:
+ +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:
+ + +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:
+ + +Returns:
+ +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:
+ + +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:
+ +-
+
+
-
+
+
a+ Array + + + + +++ + +Array with nested arrays to flatten.
+
+
+
Returns:
+ +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:
+ + +Returns:
+ +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:
+ + +Returns:
+ +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:
+ + +Returns:
+ +-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:
+ +-
+
+
-
+
+
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:
+ +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:
+ +-
+
+
-
+
+
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
+-1will be returned.
+
+
Returns:
+ +-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:
+ + +Returns:
+ +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.
Parameters:
+ + +Returns:
+ +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:
+ + +Returns:
+ +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:
+ +-
+
+
-
+
+
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:
+ +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:
+ + +Returns:
+ +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:
+ + +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:
+ +-
+
+
-
+
+
obj+ Object + + + + +++ + +Object to test.
+
+
+
Returns:
+ +-
+
- 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:
+ +-
+
+
-
+
+
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.
+
+
+
Returns:
+ +zip
+
+
+ -
+
+
-
+
+
a+ +
+
+ -
+
+
a2+ +
+
+
Creates an array of arrays by pairing the corresponding elements of two arrays +together into a new array.
+