UsefulJS.Array

Methods

The methods in the UsefulJS.Array namespace are not designed to be called by application code. Rather, they are the implementations of the ECMAScript 5/6 Array methods and intended to be called via methods of Array.prototype. The methods are generic in the sense that they will work with any array-like object.

fill

Fills slots in an array between specified boundaries with a specified value. This function modifies its input but won't grow it.

Syntax

UsefulJS.Array.fill(a, value[, start[, end]])

Parameters

• a Array
  The array to fill
• value Object
  The object used to fill the array
• start Number
  The start index. May be negative (in which case the start index is a.length + start). Defaults to 0
• end Number
  The end index. May be negative (in which case the end index is a.length + start). Defaults to a.length

Returns: Array the mutated array

find

Finds an item in an Array starting either from the head or the tail.

Syntax

UsefulJS.Array.find(a, item, idx, incr)

Parameters

• a Array
  The array to search
• item Object
  The item to search for
• idx Number
  The array index to start at
• incr Number
  +1 for forward search, -1 for backward search

Returns: Number either the 0-based index of the item or -1

iterate

Iterates over an array calling a function for each item in the array until either the array is exhausted or (in some modes) the callback returns a certain value.

Syntax

UsefulJS.Array.iterate(a, callback, ctx, mode)

Parameters

• a Array
  The array to iterate over
• callback Function
  A callback for each item in the array; the callback signature is:
  

  f(item, index, array)

• ctx Object
  The this context for the callback
• mode String
  One of "every", "some", "forEach", "filter", "map", "find" or "findIndex"

Returns: varying, according to the mode:

• every, some: Boolean the final return value of the callback function
• filter: Array the filtered-out items from the input
• map: Array the transformed items from the input
• forEach: undefined
• find: Object the first item for which the callback function returns true or undefined
• findIndex: Number the first index for which the callback function returns true or -1

reduce

Iterates over an array passing in an accumulated result and the current item in the array; the final output is a single value.

Syntax

UsefulJS.Array.reduce(a, callback, initialValue, incr)

Parameters

• a Array
  The array to iterate over
• callback Function
  A callback for each item in the array; the callback signature is:
  

  f(accumulated, item, index, array)

• initialValue Object
  The seed value for the reduction; if defined this is passed to the callback on first iteration
• incr Number
  +1 for forward iteration, -1 for backward iteration

Returns: Object the final return value from the callback.

Fixes - ES5/6 Array methods

The fixes for the UsefulJS.Array module are defined in the _array namespace of the input and output properties of the fix call. All are applied by default. The property names are the method names: "indexOf", "lastIndexOf", "from", etc.

Static Array methods

Array.isArray

Syntax

Array.isArray(obj)

Description

See the the MDN documentation for details

Array.prototype methods

Array.prototype.copyWithin

Syntax

array.copyWithin(targetIdx, startIdx[, endIdx])

Description

See the the MDN documentation for details

Array.prototype.every

Syntax

array.every(callback[, context])

Description

See the the MDN documentation for details

Array.prototype.fill

Syntax

array.fill(value[, start[, end]])

Description

See the the MDN documentation for details

Array.prototype.filter

Syntax

array.filter(callback[, context])

Description

See the the MDN documentation for details

Array.prototype.find

Syntax

array.find(callback[, context])

Description

See the the MDN documentation for details

Array.prototype.findIndex

Syntax

array.findIndex(callback[, context])

Description

See the the MDN documentation for details

Array.prototype.forEach

Syntax

array.forEach(callback[, context])

Description

See the the MDN documentation for details

Array.prototype.indexOf

Syntax

array.indexOf(item[, fromIndex])

Description

See the the MDN documentation for details

Array.prototype.lastIndexOf

Syntax

array.lastIndexOf(item[, fromIndex])

Description

See the the MDN documentation for details

Array.prototype.map

Syntax

array.map(callback[, context])

Description

See the the MDN documentation for details

Array.prototype.reduce

Syntax

array.reduce(callback[, initialValue])

Description

See the the MDN documentation for details

Array.prototype.reduceRight

Syntax

array.reduceRight(callback[, initialValue])

Description

See the the MDN documentation for details

Array.prototype.some

Syntax

array.some(callback[, context])

Description

See the the MDN documentation for details

Array factory methods

Factory methods create Array objects from non-array objects. They are implemented as generic functions so that they can create instances of other classes if you copy the methods to those classes. For example:

var MyArray = function(length) { ... };
MyArray.of = Array.of;
var arr = MyArray.of(1, 2, 3); // creates an instance of MyArray

Array.from

Constructs an Array from an array-like object.

Syntax

Array.from(obj[, mapFn[, mapCtx]])

Parameters

• obj Object
  An array-like object
• mapFn Function
  A function to convert each item in the output Array
• mapCtx Object
  the value of this in the mapping function.

Returns: Array

Description

Array-like objects have a length property and can be accessed via square-bracket indexing but do not otherwise have the methods of a real Array. Examples of array-like objects are strings (assuming square bracket indexing is supported), NodeList objects and Element.classList. Array.from will return a real Array that contains the same values as its input. See the MDN documentation for more information.

Array.of

Constructs an Array from its arguments.

Syntax

Array.of([item1 [, item2, ... ]])

Returns: Array

Description

Arguments can be any number of any objects. See the MDN documentation for more information.