Package Exports
- array-tools
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (array-tools) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
array-tools
Useful functions for working with arrays
Example
var a = require("array-tools");- array-tools
- General
- .arrayify(any) ⇒
Array - .exists(array, value) ⇒
boolean - .without(array, toRemove) ⇒
Array - .union(array1, array2, idKey) ⇒
Array - .commonSequence(a, b) ⇒
Array - .unique(array) ⇒
Array - .spliceWhile(array, index, test, ...elementN) ⇒
Array - .extract(array, query) ⇒
Array - .flatten() ⇒
Array
- .arrayify(any) ⇒
- Record sets
- .pluck(arrayOfObjects, ...property) ⇒
Array - .pick(arrayOfObjects, ...property) ⇒
Array.<object> - .where(arrayOfObjects, query) ⇒
Array - .findWhere(arrayOfObjects, query) ⇒
object - .sortBy(arrayOfObjects, columns, customOrder) ⇒
Array
- .pluck(arrayOfObjects, ...property) ⇒
- General
a.arrayify(any) ⇒ Array
Takes input and guarantees an array back. Result can be one of three things:
- puts a single scalar in an array
- converts array-like object (e.g.
arguments) to a real array - converts
nullorundefinedto an empty array
Category: General
| Param | Type | Description |
|---|---|---|
| any | * | the input value to convert to an array |
Example
> a.arrayify(null)
[]
> a.arrayify(0)
[ 0 ]
> a.arrayify([ 1, 2 ])
[ 1, 2 ]
> function f(){ return a.arrayify(arguments); }
> f(1,2,3)
[ 1, 2, 3 ]a.exists(array, value) ⇒ boolean
returns true if a value, or nested object value exists in an array
Category: General
| Param | Type | Description |
|---|---|---|
| array | Array | the array to search |
| value | * | the value to search for |
Example
> a.exists([ 1, 2, 3 ], 2)
true
> a.exists([ { result: false }, { result: false } ], { result: true })
false
> a.exists([ { result: true }, { result: false } ], { result: true })
true
> a.exists([ { result: true }, { result: true } ], { result: true })
truea.without(array, toRemove) ⇒ Array
Returns the input minus the specified values.
Category: General
| Param | Type | Description |
|---|---|---|
| array | Array | the input array |
| toRemove | * | a single, or array of values to omit |
Example
> a.without([ 1, 2, 3 ], 2)
[ 1, 3 ]
> a.without([ 1, 2, 3 ], [ 2, 3 ])
[ 1 ]a.union(array1, array2, idKey) ⇒ Array
merge two arrays into a single array of unique values
Category: General
| Param | Type | Description |
|---|---|---|
| array1 | Array | First array |
| array2 | Array | Second array |
| idKey | string | the unique ID property name |
Example
> var array1 = [ 1, 2 ], array2 = [ 2, 3 ];
> a.union(array1, array2)
[ 1, 2, 3 ]
> var array1 = [ { id: 1 }, { id: 2 } ], array2 = [ { id: 2 }, { id: 3 } ];
> a.union(array1, array2)
[ { id: 1 }, { id: 2 }, { id: 3 } ]
> var array2 = [ { id: 2, blah: true }, { id: 3 } ]
> a.union(array1, array2)
[ { id: 1 },
{ id: 2 },
{ id: 2, blah: true },
{ id: 3 } ]
> a.union(array1, array2, "id")
[ { id: 1 }, { id: 2 }, { id: 3 } ]a.commonSequence(a, b) ⇒ Array
Returns the initial elements which both input arrays have in common
Category: General
| Param | Type | Description |
|---|---|---|
| a | Array | first array to compare |
| b | Array | second array to compare |
Example
> a.commonSequence([1,2,3], [1,2,4])
[ 1, 2 ]a.unique(array) ⇒ Array
returns an array of unique values
Category: General
| Param | Type | Description |
|---|---|---|
| array | Array | input array |
Example
> n = [1,6,6,7,1]
[ 1, 6, 6, 7, 1 ]
> a.unique(n)
[ 1, 6, 7 ]a.spliceWhile(array, index, test, ...elementN) ⇒ Array
splice from index until test fails
Category: General
| Param | Type | Description |
|---|---|---|
| array | Array | the input array |
| index | number | the position to begin splicing from |
| test | RegExp | the test to continue splicing while true |
| ...elementN | * | the elements to add to the array |
Example
> letters = ["a", "a", "b"]
[ 'a', 'a', 'b' ]
> a.spliceWhile(letters, 0, /a/, "x")
[ 'a', 'a' ]
> letters
[ 'x', 'b' ]a.extract(array, query) ⇒ Array
Removes items from array which satisfy the query. Modifies the input array, returns the extracted.
Returns: Array - the extracted items.
Category: General
| Param | Type | Description |
|---|---|---|
| array | Array | the input array, modified directly |
| query | function | object | Per item in the array, if either the function returns truthy or the exists query is satisfied, the item is extracted |
a.flatten() ⇒ Array
flatten an array of arrays into a single array
Category: General
Since: 1.4.0
Todo
- document
Example
> numbers = [ 1, 2, [ 3, 4 ], 5 ]
> a.flatten(numbers)
[ 1, 2, 3, 4, 5 ]a.pluck(arrayOfObjects, ...property) ⇒ Array
Plucks the value of the specified property from each object in the input array
Category: Record sets
| Param | Type | Description |
|---|---|---|
| arrayOfObjects | Array.<object> | the input array of objects |
| ...property | string | the property(s) to pluck |
Example
> var data = [
{one: 1, two: 2},
{two: "two"},
{one: "one", two: "zwei"},
];
> a.pluck(data, "one");
[ 1, 'one' ]
> a.pluck(data, "two");
[ 2, 'two', 'zwei' ]
> a.pluck(data, "one", "two");
[ 1, 'two', 'one' ]a.pick(arrayOfObjects, ...property) ⇒ Array.<object>
return a copy of the input arrayOfObjects containing objects having only the cherry-picked properties
Category: Record sets
| Param | Type | Description |
|---|---|---|
| arrayOfObjects | Array.<object> | the input |
| ...property | string | the properties to include in the result |
Example
> data = [
{ one: "un", two: "deux", three: "trois" },
{ two: "two", one: "one" },
{ four: "quattro" },
{ two: "zwei" }
]
> a.pick(data, "two")
[ { two: 'deux' },
{ two: 'two' },
{ two: 'zwei' } ]a.where(arrayOfObjects, query) ⇒ Array
returns an array containing items from arrayOfObjects where key/value pairs
from query are matched identically
Category: Record sets
| Param | Type | Description |
|---|---|---|
| arrayOfObjects | Array.<object> | the array to search |
| query | query | an object containing the key/value pairs you want to match |
Example
> dudes = [{ name: "Jim", age: 8}, { name: "Clive", age: 8}, { name: "Hater", age: 9}]
[ { name: 'Jim', age: 8 },
{ name: 'Clive', age: 8 },
{ name: 'Hater', age: 9 } ]
> a.where(dudes, { age: 8})
[ { name: 'Jim', age: 8 },
{ name: 'Clive', age: 8 } ]a.findWhere(arrayOfObjects, query) ⇒ object
returns the first item from arrayOfObjects where key/value pairs
from query are matched identically
Category: Record sets
| Param | Type | Description |
|---|---|---|
| arrayOfObjects | Array.<object> | the array to search |
| query | object | an object containing the key/value pairs you want to match |
Example
> dudes = [{ name: "Jim", age: 8}, { name: "Clive", age: 8}, { name: "Hater", age: 9}]
[ { name: 'Jim', age: 8 },
{ name: 'Clive', age: 8 },
{ name: 'Hater', age: 9 } ]
> a.findWhere(dudes, { age: 8})
{ name: 'Jim', age: 8 }a.sortBy(arrayOfObjects, columns, customOrder) ⇒ Array
Sort an array of objects by one or more fields
Category: Record sets
Since: 1.5.0
| Param | Type | Description |
|---|---|---|
| arrayOfObjects | Array.<object> | input array |
| columns | string | Array.<string> | column name(s) to sort by |
| customOrder | object | specific sort orders, per columns |
Example
> var fixture = [
{ a: 4, b: 1, c: 1},
{ a: 4, b: 3, c: 1},
{ a: 2, b: 2, c: 3},
{ a: 2, b: 2, c: 2},
{ a: 1, b: 3, c: 4},
{ a: 1, b: 1, c: 4},
{ a: 1, b: 2, c: 4},
{ a: 3, b: 3, c: 3},
{ a: 4, b: 3, c: 1}
];
> a.sortBy(fixture, ["a", "b", "c"])
[ { a: 1, b: 1, c: 4 },
{ a: 1, b: 2, c: 4 },
{ a: 1, b: 3, c: 4 },
{ a: 2, b: 2, c: 2 },
{ a: 2, b: 2, c: 3 },
{ a: 3, b: 3, c: 3 },
{ a: 4, b: 1, c: 1 },
{ a: 4, b: 3, c: 1 },
{ a: 4, b: 3, c: 1 } ]--
documented by jsdoc-to-markdown.
© 2015 Lloyd Brookes 75pound@gmail.com