JSPM

array-tools

Lightweight tool-kit for working with arrays.

> var a = require("array-tools");
> a.exists([ 1, 2, 3 ], 1)
true

You can also chain together operations. Any method from array-tools or Array.prototype which returns an array can be chained. Methods which do not return an arrary (e.g. exists or Array.prototype.join) can not be chained. If the final operation in your chain is one of the chainable methods then you must terminate it with .val() to obtain the value. For example:

> var a = require("array-tools");
> a([ 1, 2, 2, 3 ]).exists(1)
true
> a([ 1, 2, 2, 3 ]).without(1).exists(1)
false
> a([ 1, 2, 2, 3 ]).without(1).unique().val()
[ 2, 3 ]

• array-tools
  • any value in
    • .arrayify(any) ⇒ Array
  • multiple arrays in
    • .union(array1, array2, idKey) ⇒ Array
    • .commonSequence(a, b) ⇒ Array
  • record set in
    • .pluck(arrayOfObjects, ...property) ⇒ Array
    • .pick(arrayOfObjects, ...property) ⇒ Array.<object>
    • .where(arrayOfObjects, query) ⇒ Array
    • .findWhere(arrayOfObjects, query) ⇒ object
    • .sortBy(arrayOfObjects, columns, customOrder) ⇒ Array
  • single array in
    • .exists(array, value) ⇒ boolean
    • .without(array, toRemove) ⇒ Array
    • .unique(array) ⇒ Array
    • .spliceWhile(array, index, test, ...elementN) ⇒ Array
    • .extract(array, query) ⇒ Array
    • .flatten(array) ⇒ Array
    • .last(arr) ⇒ *
    • .remove(arr, toRemove) ⇒ *
    • .contains(arr, value) ⇒

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 null or undefined to an empty array

Kind: static method of array-tools
Category: any value in

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.union(array1, array2, idKey) ⇒ Array

merge two arrays into a single array of unique values

Kind: static method of array-tools
Category: multiple arrays in

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

Kind: static method of array-tools
Category: multiple arrays in

Example

> a.commonSequence([1,2,3], [1,2,4])
[ 1, 2 ]

a.pluck(arrayOfObjects, ...property) ⇒ Array

Plucks the value of the specified property from each object in the input array

Kind: static method of array-tools
Category: record set in

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

Kind: static method of array-tools
Category: record set in

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

Kind: static method of array-tools
Category: record set in

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

Kind: static method of array-tools
Category: record set in

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

Kind: static method of array-tools
Category: record set in
Since: 1.5.0

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

a.exists(array, value) ⇒ boolean

returns true if a value, or nested object value exists in an array

Kind: static method of array-tools
Category: single array in

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.without(array, toRemove) ⇒ Array

Returns the input minus the specified values.

Kind: static method of array-tools
Category: single array in

Example

> a.without([ 1, 2, 3 ], 2)
[ 1, 3 ]
> a.without([ 1, 2, 3 ], [ 2, 3 ])
[ 1 ]

a.unique(array) ⇒ Array

returns an array of unique values

Kind: static method of array-tools
Category: single array in

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

Kind: static method of array-tools
Category: single array in

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.

Kind: static method of array-tools
Returns: Array - the extracted items.
Category: single array in

a.flatten(array) ⇒ Array

flatten an array of arrays into a single array

Kind: static method of array-tools
Category: single array in
Since: 1.4.0

Example

> numbers = [ 1, 2, [ 3, 4 ], 5 ]
> a.flatten(numbers)
[ 1, 2, 3, 4, 5 ]

a.last(arr) ⇒ *

Return the last item in an array.

Kind: static method of array-tools
Category: single array in
Since: 1.7.0

a.remove(arr, toRemove) ⇒ *

Kind: static method of array-tools
Category: single array in
Since: 1.8.0

a.contains(arr, value) ⇒

Kind: static method of array-tools
Returns: boolean
Category: single array in
Since: 1.8.0

© 2015 Lloyd Brookes 75pound@gmail.com. Documented by jsdoc-to-markdown.