ArrayHelper

Helper with useful functions for handling Arrays

Functions

Combines provided arrays of by aggregating their element values. For example the below code sums up numeric elements of the arrays:

ArrayHelper.aggregate(
    [
        [0,   1,  2, 33]
        [10,  1, -1],
        [100, 1, -1]
    ],
    entry => entry || 0, // "|| 0" here to make it work for different array sizes
    (aggregated, entry) => aggregated + entry, // aggregate by summing up
    () => 0 //initial value is zero
);

// returns [111, 3, 0, 33] array

Parameter	Type	Description
`arrays`	Array[]	Arrays to combine
`getEntryValueFn`	function	Function that extracts an array entry for aggregating.
`aggregatorFn`	function	A function to execute for each element in the arrays. It's purpose is to aggregate the element value to the corresponding entry of the resulting array. The function's return value becomes the value of the `aggregated` parameter on the next invocation of `aggregatorFn`. The function is called with the following arguments:
`aggregatorFn.aggregated`	Object	Resulting array entry value. On the first call `getInitialValueFn` result.
`aggregatorFn.entry`	Object	Current entry to aggregate into `aggregated`.
`aggregatorFn.arrayIndex`	Number	Index of current array (in the provided `arrays`).
`aggregatorFn.entryIndex`	Object[]	Index of the current entry.
`aggregationContext`	Object	A shared object providing extra aggregation call context.
`getInitialValueFn`	function	Function that returns an initial value for the combined array entries.
`aggregationContext`	Object	Optional object that is passed to all of the above functions that can be used for keeping some additional parameters used when aggregating. Out of the box the object will contain `arrays` and `targetArray` properties containing input and resulting arrays respectively.

Returns: Array -

Resulting array of combined values.

binarySearchstatic

This method returns the index that a given item would be inserted into the given (sorted) array. Note that the given item may or may not be in the array. This method will return the index of where the item should be.

For example:

 var array = [ 'A', 'D', 'G', 'K', 'O', 'R', 'X' ];
 var index = ArrayHelper.binarySearch(array, 'E');

 console.log('index: ' + index);
 // logs "index: 2"

 array.splice(index, 0, 'E');

 console.log('array : ' + array.join(''));
 // logs "array: ADEGKORX"

Parameter	Type	Description
`array`	Object[]	The array to search.
`item`	Object	The item that you want to insert into the `array`.
`begin`	Number	The first index in the `array` to consider.
`end`	Number	The index that marks the end of the range to consider. The item at this index is not considered.
`compareFn`	function	The comparison function that matches the sort order of the `array`. The default `compareFn` compares items using less-than and greater-than operators.

Returns: Number -

The index for the given item in the given array based on the passed compareFn.

countUniquestatic

Returns an array of unique values and their occurrence count, in { value, count } format

Parameter	Type	Description
`array`	Array	Input array

Returns: Array -

New array with unique items and counts in { value, count } format

fillstatic

Similar to Array.prototype.fill(), but constructs a new array with the specified item count and fills it with clones of the supplied item.

Parameter	Type	Description
`count`	Number	Number of entries to create
`itemOrArray`	Object \| Array	Item or array of items to clone (uses object spread to create shallow clone)
`fn`	function	An optional function that is called for each item added, to allow processing

Returns: Array -

A new populated array

findLaststatic

Similar to the native Array.find() call, but this finds the last element in the array for which the passed function returns a truthy value.

Parameter	Type	Description
`array`	Object[]	The array to find in.
`fn`	function	The testing function.
`thisObj`	Object	The scope (`this` reference) in which to call the function.

fromstatic

Similar to Array.from() this method creates an array from an iterable object. Where Array.from() accepts a mapper function as the second argument, this method accepts a filter function as its second argument. If a mapper function is also needed, it can be passed as the third argument. Unlike Array.from(), if this method is passed null, it will return an empty array.

Parameter	Type	Description
`iterable`	Array	The iterable object to convert (must support `for-of` loop iteration).
`filter`	function	A function to apply to each item of the `iterable` which must return a truthy value to include that item in the resulting array.
`map`	function	A function to apply to each item of the `iterable` that returns the actual value to put into the returned array. If a `filter` is also supplied, this method is only called for those items that pass the filter test.

Returns: Array

includestatic

Pushes item on to the array if not already included

Parameter	Type	Description
`array`	Array	Array to push to
`items`	Object	Item(s) to push if not already included

populatestatic

Populates an array with the return value from fn.

Parameter	Type	Description
`count`	Number	Number of entries to create
`fn`	function	A function that is called `count` times, return value is added to array
`fn.index`	Number	Current index in the array

Returns: Array -

A new populated array

removestatic

Remove one or more items from an array

Parameter	Type	Description
`array`	Array	Array to remove from
`items`	Object \| Object[] \| Set	One or more items to remove, or one Set containing items to remove

Returns: Boolean -

Returns true if any item was removed

uniquestatic

Returns a new array with the unique items from the supplied array.

Parameter	Type	Description
`array`	Array	Input array

Returns: Array -

New array with unique items