package
Extends Arrays with useful methods of unparalleled performance
npm install pro-arrayGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 2 packages.
9.9 kB
Includes dependencies.
npm install pro-array --saverequire('pro-array');Requires browserify to work in the browser.
The native Array object.
numberArrayArrayArrayArrayArrayArray
functionbooleanArrayArray*ArrayArrayArrayArrayArrayArrayArrayArrayArrayArraynumberFinds the index of a value in a sorted array using a binary search algorithm.
If no compareFunction 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
['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-compareArrayCreates 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
[1, 2, 3, 4].chunk(2);
// -> [[1, 2], [3, 4]]
[1, 2, 3, 4].chunk(3);
// -> [[1, 2, 3], [4]]ArrayRemoves all elements from the array.
Returns: Array - The array this method was called on.
Example
var array = [1, 2, 3];
array.clear();
console.log(array);
// -> []ArrayCreates a shallow copy of the array.
Returns: Array - A clone of the array.
Example
var a = [1, 2, 3];
var b = a.clone();
console.log(b, b === a);
// -> [1, 2, 3] falseArrayReturns 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
[0, 1, false, 2, '', 3].compact();
// -> [1, 2, 3]Alias of difference.
See: difference
ArrayReturns 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
[1, 2, 3, 4, 5].difference([5, 2, 10]);
// -> [1, 3, 4]ArrayInvokes a callback function on each element in the array.
A generic iterator method similar to .forEach() but with the following differences:
this always refers to the current element in the iteration (the value argument to the callback).false in the callback will cancel the iteration (similar to a break statement).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
['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]functionbooleanDetermines 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
var array = [1, 2, 3];
array.equals(array);
// -> true
array.equals([1, 2, 3]);
// -> true
array.equals([3, 2, 1]);
// -> falseArrayFlattens a nested array a single level.
Returns: Array - The new flattened array.
Example
[1, [2, 3, [4]], 5].flatten();
// -> [1, 2, 3, [4], 5]ArrayRecursively 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
[1, [2, 3, [4]], 5].flattenDeep();
// -> [1, 2, 3, 4, 5]*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
var array = [1, 2, 3];
array.get(0);
// -> 1
array.get(1);
// -> 2
array.get(-1);
// -> 3
array.get(-2);
// -> 2
array.get(5);
// -> undefinedArrayReturns 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
[1, 2, 3].intersect([2, 3, 4]);
// -> [2, 3]
[1, 2, 3].intersect([101, 2, 50, 1], [2, 1]);
// -> [1, 2]ArraySorts 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
var files = ['a.txt', 'a10.txt', 'a2.txt', 'a1.txt'];
files.natsort();
console.log(files);
// -> ['a.txt', 'a1.txt', 'a2.txt', 'a10.txt']ArraySorts 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
var a = [10, 0, 2, 1];
a.numsort();
console.log(a);
// -> [0, 1, 2, 3]Alias of remove.
See: remove
ArrayRemoves 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
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]ArraySorts 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
var files = ['a.txt', 'a10.txt', 'a2.txt', 'a1.txt'];
files.rnatsort();
console.log(files);
// -> ['a10.txt', 'a2.txt', 'a1.txt', 'a.txt']ArraySorts 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
var a = [10, 0, 2, 1];
a.rnumsort();
console.log(a);
// -> [3, 2, 1, 0]ArrayReturns 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
[1, 2, 3].union([2, 3, 4, 5]);
// -> [1, 2, 3, 4, 5]
[1, 2].union([4, 2], [2, 1]);
// -> [1, 2, 4]Alias of unique.
See: unique
ArrayReturns 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
// 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)ArrayReturns 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
[1, 2, 3, 4].without(2, 4);
// -> [1, 3]
[1, 1].without(1);
// -> []ArrayFinds 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
[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]Array.prototypeProArray 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.