Skip to content package
pro-array v1.2.0 Extends the functionality of Arrays with useful methods of unparalleled performance
node any 1 deps cjs open source
overview readme
license MIT
deps 1
unpacked Unknown
files Unknown
node any $ npm install pro-array@1.2.0n npmREADME GitHub-flavored package documentation.
downloads Across all versions.
Download trend unavailable.
compatibility Runtime metadata.
keywords Tagged topics.
ProArray Array prototype pro clone natsort unique util
versions Latest published Apr 23, 2016
maintainers Registry package owners.
contents ProArray
Extends Arrays (safely ) with useful methods of unparalleled performance
install size Estimated unpacked size across 2 packages.
9.9 kB
Includes dependencies.
dependencies 1 direct · 1 outdated
Installation npm install pro-array --save copy
Usage require ( 'pro-array' ); copy
API Reference
Array
array.bsearch(value, [compareFunction]) ⇒ number Finds 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] functionThe 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.
[ '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 copy
array.chunk([size]) ⇒ Array 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] number1The length of each chunk.
Returns : Array - An array containing the chunks.
Throws :
RangeError Throws when size is a negative number.
[ 1 , 2 , 3 , 4 ]. chunk ( 2 );
// -> [[1, 2], [3, 4]]
[ 1 , 2 , 3 , 4 ]. chunk ( 3 );
// -> [[1, 2, 3], [4]] copy
Removes all elements from the array.
Returns : Array - The array this method was called on.
var array = [ 1 , 2 , 3 ];
array. clear ();
console. log (array);
// -> [] copy
Creates a shallow copy of the array.
Returns : Array - A clone of the array.
var a = [ 1 , 2 , 3 ];
var b = a. clone ();
console. log (b, b === a);
// -> [1, 2, 3] false copy
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.
[ 0 , 1 , false , 2 , '' , 3 ]. compact ();
// -> [1, 2, 3] copy
array.diff()
array.difference(...arrays) ⇒ Array 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.
[ 1 , 2 , 3 , 4 , 5 ]. difference ([ 5 , 2 , 10 ]);
// -> [1, 3, 4] copy
array.each(callback, [safeIteration]) ⇒ Array Invokes 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).
Returning false in the callback will cancel the iteration (similar to a break statement).
The array is returned to allow for function chaining.
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] booleanfalseWhen 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.
[ '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] copy
each~eachCallback : function Param Type Description value *The current element being processed. index numberThe index of the current element being processed. array Array The array .each() was called on.
array.equals(array) ⇒ boolean 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.
var array = [ 1 , 2 , 3 ];
array. equals (array);
// -> true
array. equals ([ 1 , 2 , 3 ]);
// -> true
array. equals ([ 3 , 2 , 1 ]);
// -> false copy
Flattens a nested array a single level.
Returns : Array - The new flattened array.
[ 1 , [ 2 , 3 , [ 4 ]], 5 ]. flatten ();
// -> [1, 2, 3, [4], 5] copy
array.flattenDeep([noCallStack]) ⇒ Array Recursively flattens a nested array.
Param Type Default Description [noCallStack] booleanfalseSpecifies 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.
[ 1 , [ 2 , 3 , [ 4 ]], 5 ]. flattenDeep ();
// -> [1, 2, 3, 4, 5] copy
array.get(index) ⇒ * Retrieve an element in the array.
Param Type Description index numberA zero-based integer indicating which element to retrieve.
Returns : * - The element at the specified index.
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 copy
array.intersect(...arrays) ⇒ Array 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.
[ 1 , 2 , 3 ]. intersect ([ 2 , 3 , 4 ]);
// -> [2, 3]
[ 1 , 2 , 3 ]. intersect ([ 101 , 2 , 50 , 1 ], [ 2 , 1 ]);
// -> [1, 2] copy
array.natsort([caseInsensitive]) ⇒ Array Sorts an array in place using a natural order string comparison algorithm.
Param Type Default Description [caseInsensitive] booleanfalseSet this to true to ignore letter casing when sorting.
Returns : Array - The array this method was called on.
var files = [ 'a.txt' , 'a10.txt' , 'a2.txt' , 'a1.txt' ];
files. natsort ();
console. log (files);
// -> ['a.txt', 'a1.txt', 'a2.txt', 'a10.txt'] copy
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.
var a = [ 10 , 0 , 2 , 1 ];
a. numsort ();
console. log (a);
// -> [0, 1, 2, 3] copy
array.pull()
array.remove(...items) ⇒ Array 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.
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] copy
array.rnatsort([caseInsensitive]) ⇒ Array 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] booleanfalseSet this to true to ignore letter casing when sorting.
Returns : Array - The array this method was called on.
var files = [ 'a.txt' , 'a10.txt' , 'a2.txt' , 'a1.txt' ];
files. rnatsort ();
console. log (files);
// -> ['a10.txt', 'a2.txt', 'a1.txt', 'a.txt'] copy
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.
var a = [ 10 , 0 , 2 , 1 ];
a. rnumsort ();
console. log (a);
// -> [3, 2, 1, 0] copy
array.union(...arrays) ⇒ Array 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.
[ 1 , 2 , 3 ]. union ([ 2 , 3 , 4 , 5 ]);
// -> [1, 2, 3, 4, 5]
[ 1 , 2 ]. union ([ 4 , 2 ], [ 2 , 1 ]);
// -> [1, 2, 4] copy
array.uniq()
array.unique([isSorted]) ⇒ Array Returns a duplicate-free clone of the array.
Param Type Default Description [isSorted] booleanfalseIf 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.
// 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) copy
array.without(...items) ⇒ Array 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.
[ 1 , 2 , 3 , 4 ]. without ( 2 , 4 );
// -> [1, 3]
[ 1 , 1 ]. without ( 1 );
// -> [] copy
array.xor(...arrays) ⇒ Array Param Type Description arrays ...Array A variable number of arrays.
Returns : Array - The new array of values.
[ 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] copy
Extending Array.prototype
Worried about naming collisions? It is extremely unlikely that the name of any method that ProArray adds to the Array prototype will be used in a future ECMAScript standard, but if you're still worried and want to be extra safe, try using the alias methods (like .pull() and .uniq() ).