pro-array

ProArray

Extends Arrays (safely) with useful methods of unparalleled performance

Installation

npm install pro-array --save

Usage

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]) ⇒ number
  • .chunk([size]) ⇒ Array
  • .clear() ⇒ Array
  • .clone() ⇒ Array
  • .compact() ⇒ Array
  • .diff()
  • .difference(...arrays) ⇒ Array
  • .each(callback, [safeIteration]) ⇒ Array
    • ~eachCallback : function
  • .equals(array) ⇒ boolean
  • .flatten() ⇒ Array
  • .flattenDeep([noCallStack]) ⇒ Array
  • .get(index) ⇒ *
  • .intersect(...arrays) ⇒ Array
  • .natsort([caseInsensitive]) ⇒ Array
  • .numsort() ⇒ Array
  • .pull()
  • .remove(...items) ⇒ Array
  • .rnatsort([caseInsensitive]) ⇒ Array
  • .rnumsort() ⇒ Array
  • .union(...arrays) ⇒ Array
  • .uniq()
  • .unique([isSorted]) ⇒ Array
  • .without(...items) ⇒ Array
  • .xor(...arrays) ⇒ 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]	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-compare

---

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]	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]]

---

array.clear() ⇒ Array

Removes 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);
// -> []

---

array.clone() ⇒ Array

Creates 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] false

---

array.compact() ⇒ Array

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

[0, 1, false, 2, '', 3].compact();
// -> [1, 2, 3]

---

array.diff()

Alias of difference.

See: difference

---

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.

Example

[1, 2, 3, 4, 5].difference([5, 2, 10]);
// -> [1, 3, 4]

---

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:

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

['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.

---

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.

Example

var array = [1, 2, 3];

array.equals(array);
// -> true

array.equals([1, 2, 3]);
// -> true

array.equals([3, 2, 1]);
// -> false

---

array.flatten() ⇒ Array

Flattens a nested array a single level.

Returns: Array - The new flattened array.

Example

[1, [2, 3, [4]], 5].flatten();
// -> [1, 2, 3, [4], 5]

---

array.flattenDeep([noCallStack]) ⇒ Array

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

[1, [2, 3, [4]], 5].flattenDeep();
// -> [1, 2, 3, 4, 5]

---

array.get(index) ⇒ *

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);
// -> undefined

---

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.

Example

[1, 2, 3].intersect([2, 3, 4]);
// -> [2, 3]

[1, 2, 3].intersect([101, 2, 50, 1], [2, 1]);
// -> [1, 2]

---

array.natsort([caseInsensitive]) ⇒ Array

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

var files = ['a.txt', 'a10.txt', 'a2.txt', 'a1.txt'];
files.natsort();
console.log(files);
// -> ['a.txt', 'a1.txt', 'a2.txt', 'a10.txt']

---

array.numsort() ⇒ Array

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

var a = [10, 0, 2, 1];
a.numsort();
console.log(a);
// -> [0, 1, 2, 3]

---

array.pull()

Alias of remove.

See: remove

---

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.

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]

---

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]	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']

---

array.rnumsort() ⇒ Array

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

var a = [10, 0, 2, 1];
a.rnumsort();
console.log(a);
// -> [3, 2, 1, 0]

---

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.

Example

[1, 2, 3].union([2, 3, 4, 5]);
// -> [1, 2, 3, 4, 5]

[1, 2].union([4, 2], [2, 1]);
// -> [1, 2, 4]

---

array.uniq()

Alias of unique.

See: unique

---

array.unique([isSorted]) ⇒ Array

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

// 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)

---

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.

Example

[1, 2, 3, 4].without(2, 4);
// -> [1, 3]

[1, 1].without(1);
// -> []

---

array.xor(...arrays) ⇒ Array

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

[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.

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()).