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
- .pluck(arrayOfObjects, ...property) ⇒
Array - .pick(arrayOfObjects, ...property) ⇒
Array.<object> - .arrayify(input) ⇒
Array - .exists(array, value) ⇒
boolean - .where(arrayOfObjects, query) ⇒
Array - .findWhere(arrayOfObjects, query) ⇒
object - .without(input, 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 - .sortBy(arrayOfObject, ...columns) ⇒
array
- .pluck(arrayOfObjects, ...property) ⇒
a.pluck(arrayOfObjects, ...property) ⇒ Array
Plucks the value of the specified property from each object in the input array
| 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
| 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.arrayify(input) ⇒ 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
| Param | Type | Description |
|---|---|---|
| input | * | 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
| 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.where(arrayOfObjects, query) ⇒ Array
returns an array containing items from arrayOfObjects where key/value pairs
from query are matched identically
| Param | Type | Description |
|---|---|---|
| arrayOfObjects | Array | 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
| Param | Type | Description |
|---|---|---|
| arrayOfObjects | Array | 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.findWhere(dudes, { age: 8})
{ name: 'Jim', age: 8 }a.without(input, toRemove) ⇒ Array
Returns the input minus the specified values.
| Param | Type | Description |
|---|---|---|
| input | 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
| 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
| 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
reduces an array to unique values
| 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
| 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.
| 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
Since: 1.4.0
Todo
- document
Example
> numbers = [ 1, 2, [ 3, 4 ], 5 ]
> a.flatten(numbers)
[ 1, 2, 3, 4, 5 ]a.sortBy(arrayOfObject, ...columns) ⇒ array
Sort an array of objects by one or more fields
| Param | Type | Description |
|---|---|---|
| arrayOfObject | array | input array |
| ...columns | string | column names to sort by |
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