Extends Arrays with useful methods of unparalleled performance
npm install pro-arraysh
npm install pro-array --save
`
Usage
`js
require('pro-array');
`
Requires browserify to work in the browser.
API Reference
Array
The native Array object.
See: MDN JavaScript Array Reference
* Array
* [.bsearch(value, [compareFunction])](#Array+bsearch) ⇒ number
* [.chunk([size])](#Array+chunk) ⇒ Array
* .clear() ⇒ Array
* .clone() ⇒ Array
* .compact() ⇒ Array
* .diff()
* .difference(...arrays) ⇒ Array
* [.each(callback, [safeIteration])](#Array+each) ⇒ Array
* ~eachCallback : function
* .equals(array) ⇒ boolean
* .flatten() ⇒ Array
* [.flattenDeep([noCallStack])](#Array+flattenDeep) ⇒ Array
.get(index) ⇒ \
Array
Array
Array
Array
Array
Array
Array
Array
Array
Array
is supplied, the > and < relational operators are used to compare values,
which provides optimal performance for arrays of numbers and simple strings.
| Param | Type | Description |
| --- | --- | --- |
| value | \* | The value to search for. |
| [compareFunction] | function | The same type of comparing function you would pass to .sort(). |
Returns: number - The index of the value if it is in the array, or -1 if it cannot be found.
If the search value can be found at multiple indexes in the array, it is unknown which of
those indexes will be returned.
Example
`js
['a', 'b', 'c', 'd'].bsearch('c');
// -> 2
[1, 1, 2, 2].bsearch(2);
// -> 2 or 3
[1, 2, 3, 4].bsearch(10);
// -> -1
// Search an array of people sorted by age
var finn = {name: 'Finn', age: 12};
var jake = {name: 'Jake', age: 28};
[finn, jake].bsearch(finn, function(a, b) {
return a.age - b.age;
});
// -> 0
['img1', 'img2', 'img10', 'img13'].bsearch('img2', naturalCompare);
// -> 1
// naturalCompare is provided by the string-natural-compare npm module:
// https://www.npmjs.com/package/string-natural-compare
`
---
$3
Creates an array of elements split into groups the length of size. If the array
can't be split evenly, the final chunk will be the remaining elements.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [size] | number | 1 | The length of each chunk. |
Returns: Array - An array containing the chunks.
Throws:
- RangeError Throws when size is a negative number.
Example
`js
[1, 2, 3, 4].chunk(2);
// -> [[1, 2], [3, 4]]
[1, 2, 3, 4].chunk(3);
// -> [[1, 2, 3], [4]]
`
---
$3
Removes all elements from the array.
Returns: Array - The array this method was called on.
Example
`js
var array = [1, 2, 3];
array.clear();
console.log(array);
// -> []
`
---
$3
Creates a shallow copy of the array.
Returns: Array - A clone of the array.
Example
`js
var a = [1, 2, 3];
var b = a.clone();
console.log(b, b === a);
// -> [1, 2, 3] false
`
---
$3
Returns a new array with all falsey values removed. Falsey values
are false, 0, "", null, undefined, and NaN.
Returns: Array - The new array containing only the truthy values from the original array.
Example
`js
[0, 1, false, 2, '', 3].compact();
// -> [1, 2, 3]
`
---
$3
Alias of difference.
See: difference
---
$3
Returns a new array with all of the values of the array that are not in
any of the input arrays (performs a set difference).
| Param | Type | Description |
| --- | --- | --- |
| arrays | ...Array | A variable number of arrays. |
Returns: Array - The new array of filtered values.
Example
`js
[1, 2, 3, 4, 5].difference([5, 2, 10]);
// -> [1, 3, 4]
`
---
$3
Invokes a callback function on each element in the array.
A generic iterator method similar to .forEach() but with the following differences:
1. this always refers to the current element in the iteration (the value argument to the callback).
2. Returning false in the callback will cancel the iteration (similar to a break statement).
3. The array is returned to allow for function chaining.
4. The callback __is__ invoked for indexes that have been deleted or elided unless safeIteration is true.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| callback | eachCallback | | A function to be executed on each element in the array. |
| [safeIteration] | boolean | false | When true, the callback will not be invoked for indexes that have been deleted or elided (are undefined). |
Returns: Array - The array this method was called on.
Example
`js
['a', 'b', 'c'].each(console.log.bind(console));
// -> 'a' 0 ['a', 'b', 'c']
// -> 'b' 1 ['a', 'b', 'c']
// -> 'c' 2 ['a', 'b', 'c']
// -> ['a', 'b', 'c']
['a', 'b', 'c'].each(function(value, index) {
console.log(value);
if (index === 1) return false;
});
// -> 'a'
// -> 'b'
// -> ['a', 'b', 'c']
[[1, 2], [3, 4, 5]].each(Array.prototype.pop);
// -> [[1], [3, 4]]
new Array(1).each(console.log.bind(console));
// -> undefined 0 [undefined]
// -> [undefined]
new Array(1).each(console.log.bind(console), true);
// -> [undefined]
`
---
#### each~eachCallback : function
| Param | Type | Description |
| --- | --- | --- |
| value | \* | The current element being processed. |
| index | number | The index of the current element being processed. |
| array | Array | The array .each() was called on. |
---
$3
Determines if the arrays are equal by doing a shallow comparison of their elements using strict equality.
__Note:__ The order of elements in the arrays __does__ matter. The elements must be found in the same order
for the arrays to be considered equal.
| Param | Type | Description |
| --- | --- | --- |
| array | Array | An array to compare for equality. |
Returns: boolean - true if the arrays are equal, false otherwise.
Example
`js
var array = [1, 2, 3];
array.equals(array);
// -> true
array.equals([1, 2, 3]);
// -> true
array.equals([3, 2, 1]);
// -> false
`
---
$3
Flattens a nested array a single level.
Returns: Array - The new flattened array.
Example
`js
[1, [2, 3, [4]], 5].flatten();
// -> [1, 2, 3, [4], 5]
`
---
$3
Recursively flattens a nested array.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [noCallStack] | boolean | false | Specifies if an algorithm that is not susceptible to call stack limits should be used, allowing very deeply nested arrays (i.e. > 9000 levels) to be flattened. |
Returns: Array - The new flattened array.
Example
`js
[1, [2, 3, [4]], 5].flattenDeep();
// -> [1, 2, 3, 4, 5]
`
---
$3
Retrieve an element in the array.
| Param | Type | Description |
| --- | --- | --- |
| index | number | A zero-based integer indicating which element to retrieve. |
Returns: \* - The element at the specified index.
Example
`js
var array = [1, 2, 3];
array.get(0);
// -> 1
array.get(1);
// -> 2
array.get(-1);
// -> 3
array.get(-2);
// -> 2
array.get(5);
// -> undefined
`
---
$3
Returns an new array that is the set intersection)
of the array and the input array(s).
| Param | Type | Description |
| --- | --- | --- |
| arrays | ...Array | A variable number of arrays. |
Returns: Array - The new array of unique values shared by all of the arrays.
Example
`js
[1, 2, 3].intersect([2, 3, 4]);
// -> [2, 3]
[1, 2, 3].intersect([101, 2, 50, 1], [2, 1]);
// -> [1, 2]
`
---
$3
Sorts an array in place using a natural order string comparison algorithm.
For more ways to perform a natural ordering sort, including configuring a custom alphabet, see the
string-natural-compare documentation.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [caseInsensitive] | boolean | false | Set this to true to ignore letter casing when sorting. |
Returns: Array - The array this method was called on.
Example
`js
var files = ['a.txt', 'a10.txt', 'a2.txt', 'a1.txt'];
files.natsort();
console.log(files);
// -> ['a.txt', 'a1.txt', 'a2.txt', 'a10.txt']
`
---
$3
Sorts an array in place using a numerical comparison algorithm
(sorts numbers from lowest to highest) and returns the array.
Returns: Array - The array this method was called on.
Example
`js
var a = [10, 0, 2, 1];
a.numsort();
console.log(a);
// -> [0, 1, 2, 3]
`
---
$3
Alias of remove.
See: remove
---
$3
Removes all occurrences of the passed in items from the array and returns the array.
__Note:__ Unlike .without(), this method mutates the array.
| Param | Type | Description |
| --- | --- | --- |
| items | ...\* | Items to remove from the array. |
Returns: Array - The array this method was called on.
Example
`js
var array = [1, 2, 3, 3, 4, 3, 5];
array.remove(1);
// -> [2, 3, 3, 4, 3, 5]
array.remove(3);
// -> [2, 4, 5]
array.remove(2, 5);
// -> [4]
`
---
$3
Sorts an array in place using a natural order string comparison algorithm.
The same as .natsort() except the strings are sorted in descending order.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [caseInsensitive] | boolean | false | Set this to true to ignore letter casing when sorting. |
Returns: Array - The array this method was called on.
Example
`js
var files = ['a.txt', 'a10.txt', 'a2.txt', 'a1.txt'];
files.rnatsort();
console.log(files);
// -> ['a10.txt', 'a2.txt', 'a1.txt', 'a.txt']
`
---
$3
Sorts an array in place using a reverse numerical comparison algorithm
(sorts numbers from highest to lowest) and returns the array.
Returns: Array - The array this method was called on.
Example
`js
var a = [10, 0, 2, 1];
a.rnumsort();
console.log(a);
// -> [3, 2, 1, 0]
`
---
$3
Returns an array that is the union
of the array and the input array(s).
| Param | Type | Description |
| --- | --- | --- |
| arrays | ...Array | A variable number of arrays. |
Returns: Array - The new array containing every distinct element found in the arrays.
Example
`js
[1, 2, 3].union([2, 3, 4, 5]);
// -> [1, 2, 3, 4, 5]
[1, 2].union([4, 2], [2, 1]);
// -> [1, 2, 4]
`
---
$3
Alias of unique.
See: unique
---
$3
Returns a duplicate-free clone of the array.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [isSorted] | boolean | false | If the array's contents are sorted and this is set to true, a faster algorithm will be used to create the unique array. |
Returns: Array - The new, duplicate-free array.
Example
`js
// Unsorted
[4, 2, 3, 2, 1, 4].unique();
// -> [4, 2, 3, 1]
// Sorted
[1, 2, 2, 3, 4, 4].unique();
// -> [1, 2, 3, 4]
[1, 2, 2, 3, 4, 4].unique(true);
// -> [1, 2, 3, 4] (but faster than the previous example)
`
---
$3
Returns a copy of the array without any elements from the input parameters.
| Param | Type | Description |
| --- | --- | --- |
| items | ...\* | Items to leave out of the returned array. |
Returns: Array - The new array of filtered values.
Example
`js
[1, 2, 3, 4].without(2, 4);
// -> [1, 3]
[1, 1].without(1);
// -> []
`
---
$3
Finds the symmetric difference
of the array and the input array(s).
| Param | Type | Description |
| --- | --- | --- |
| arrays | ...Array | A variable number of arrays. |
Returns: Array - The new array of values.
Example
`js
[1, 2].xor([4, 2]);
// -> [1, 4]
[1, 2, 5].xor([2, 3, 5], [3, 4, 5]);
// -> [1, 4, 5]
// Explanation:
// [1, 2, 5] ⊕ [2, 3, 5] ⊕ [3, 4, 5] = [1, 4, 5]
`
---
Extending
Array.prototype
ProArray uses Object.defineProperties()` to safely extend the native Array prototype such that the added properties are not enumerable. This keeps native arrays clean and prevents potential abnormalities when working with arrays.