array-tools

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

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"},
... ];
undefined
> 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 null or undefined to 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); }
undefined
> 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 })
true

a.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 ];
undefined
> a.union(array1, array2)
[ 1, 2, 3 ]
> var array1 = [ { id: 1 }, { id: 2 } ], array2 = [ { id: 2 }, { id: 3 } ];
undefined
> a.union(array1, array2)
[ { id: 1 }, { id: 2 }, { id: 3 } ]
> var array2 = [ { id: 2, blah: true }, { id: 3 } ]
undefined
> 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 ]
[ 1,
  2,
  [ 3, 4 ],
  5 ]
> a.flatten(numbers)
[ 1, 2, 3, 4, 5 ]

documented by jsdoc-to-markdown.

© 2015 Lloyd Brookes [e-mail]