0.0.11 • Published 12 years ago
array-extended v0.0.11
array-extended
array-extended is a Javascript library that can be used standalone or incorporated into extended
var array = require("array-extended");Or
var myextended = require("extended")
.register(require("array-extended"));Installation
npm install array-extendedOr download the source (minified)
Usage
array-extended includes many useful methods that for array. All of the functions can be chained together using array-exteded as a function or you can use the functions directly as shown in the examples.
The following native ES5 methods are included for completeness.
forEachmapfilterreducereduceRightsomeeveryindexOflastIndexOf
Note forEach returns the original array for chaining purposes.
sum
Sums the values of an array.
array.sum([1,2,3]); //6
array([1,2,3]).sum().value(); //6avg
Finds the average of an array of numbers.
array.avg([1,2,3]); //2
array([1,2,3]).avg().value(); //2sort
Sorts an array based on a property, by natural ordering, or by a custom comparator.
Note this does not change the original array.
array.sort([{a: 1},{a: 2},{a: -2}], "a"); //[{a: -2},{a: 1},{a: 2}];
array([{a: 1},{a: 2},{a: -2}]).sort("a"); //[{a: -2},{a: 1},{a: 2}];min
Finds the minimum value in an array based on a property, by natural ordering, or by a custom comparator.
array.min([ 3, -3, -2, -1, 1, 2]); //-3
array.min([{a: 1},{a: 2},{a: -2}], "a"); //{a : -2}
array([ 3, -3, -2, -1, 1, 2]).min(); //-3
array([{a: 1},{a: 2},{a: -2}]).min("a"); //{a : -2}max
Finds the maximum value in an array based on a property, by natural ordering, or by a custom comparator.
array.max([ 3, -3, -2, -1, 1, 2]); //2
array.max([{a: 1},{a: 2},{a: -2}], "a"); //{a : 2}
array([ 3, -3, -2, -1, 1, 2]).max(); //2
array([{a: 1},{a: 2},{a: -2}]).max("a"); //{a : 2}difference
Finds the difference between two arrays.
array.difference([1, 2, 3], [2]); //[1, 3]
array.difference([true, false], [false]); //[true]
array.difference(["a", "b", 3], [3]); //["a", "b"]
var a = , b = , c = ;
array.difference([{a: 1}, {a: 2}, {a: 3}], [{a: 2}, {a: 3}]); //[{a: 1}]
array([true, false]).difference([false]).value()// [true]
array([1, 2, 3]).difference([2]).value()// [1, 3]
array([1, 2, 3]).difference([2], [3]).value(); //[1]
array(["a", "b", 3]).difference([3]).value(); ["a", "b"]
array([{a: 1}, {a: 2}, {a: 3}]).difference([{a: 2}, {a: 3}]).value(); [{a: 1}]unique
Removed duplicate values from an array.
array.unique([1, 2, 2, 3, 3, 3, 4, 4, 4]); //[1, 2, 3, 4]
array([1, 2, 2, 3, 3, 3, 4, 4, 4]).unique().value(); //[1, 2, 3, 4]
array(["a", "b", "b"]).unique().value(); //["a", "b"]
array.unique(["a", "b", "b"]); //["a", "b"]rotate
Rotates an array by the number of places for 1 position by default.
var arr = array(["a", "b", "c", "d"])
arr.rotate().value(); //["b", "c", "d", "a"]
arr.rotate(2).value(); //["c", "d", "a", "b"]
arr.rotate(3).value(); //["d", "a", "b", "c"]
arr.rotate(4).value(); //["a", "b", "c", "d"]
arr.rotate(-1).value(); //["d", "a", "b", "c"]
arr.rotate(-2).value(); //["c", "d", "a", "b"]
arr.rotate(-3).value(); //["b", "c", "d", "a"]
arr.rotate(-4).value(); //["a", "b", "c", "d"]
var arr = ["a", "b", "c", "d"];
array.rotate(arr); //["b", "c", "d", "a"]
array.rotate(arr, 2); //["c", "d", "a", "b"]
array.rotate(arr, 3); //["d", "a", "b", "c"]
array.rotate(arr, 4); //["a", "b", "c", "d"]
array.rotate(arr, -1) //["d", "a", "b", "c"]
array.rotate(arr, -2); //["c", "d", "a", "b"]
array.rotate(arr, -3); //["b", "c", "d", "a"]
array.rotate(arr, -4); //["a", "b", "c", "d"]permutations
Finds all permutations of an array.
array([1, 2, 3]).permutations(); //[
// [ 1, 2, 3 ],
// [ 1, 3, 2 ],
// [ 2, 3, 1 ],
// [ 2, 1, 3 ],
// [ 3, 1, 2 ],
// [ 3, 2, 1 ]
//]
array([1, 2, 3]).permutations(2);//[
// [ 1, 2],
// [ 1, 3],
// [ 2, 3],
// [ 2, 1],
// [ 3, 1],
// [ 3, 2]
//]
array.permutations([1, 2, 3]); //[
// [ 1, 2, 3 ],
// [ 1, 3, 2 ],
// [ 2, 3, 1 ],
// [ 2, 1, 3 ],
// [ 3, 1, 2 ],
// [ 3, 2, 1 ]
//]
array.permutations(([1, 2, 3], 2);//[
// [ 1, 2],
// [ 1, 3],
// [ 2, 3],
// [ 2, 1],
// [ 3, 1],
// [ 3, 2]
//]zip
Zips the values of multiple arrays into a single array.
array([1]).zip([2], [3]).value(); //[
// [ 1, 2, 3 ]
//];
array([1, 2]).zip([2], [3]).value(); //[
// [ 1, 2, 3 ],
// [2, null, null]
//]
array([1, 2, 3]).zip([ 4, 5, 6 ], b).value(); //[
// [1, 4, 7],
// [2, 5, 8],
// [3, 6, 9]
//]
array([1, 2]).zip([ 4, 5, 6 ], [7, 8, 9 ]).value(); //[
// [1, 4, 7],
// [2, 5, 8]
//]
array([ 4, 5, 6 ]).zip([1, 2], [8]).value(), //[
// [4, 1, 8],
// [5, 2, null],
// [6, null, null]
//]
array.zip([1], [2], [3]); //[
// [ 1, 2, 3 ]
//]
array.zip([1, 2], [2], [3]); //[
// [ 1, 2, 3 ],
// [2, null, null]
//]
array.zip([1, 2, 3], [4,5,6], [7, 8, 9 ]); //[
// [1, 4, 7],
// [2, 5, 8],
// [3, 6, 9]
//]
array.zip([1, 2], [4,5,6], [7, 8, 9 ]); //[
// [1, 4, 7],
// [2, 5, 8]
//]
array.zip([ 4, 5, 6 ], [1, 2], [8]); //[
// [4, 1, 8],
// [5, 2, null],
// [6, null, null]
//]transpose
Transpose a multi dimensional array.
array([[1, 2, 3],[4, 5, 6]]).transpose().value(); //[ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
array([[1, 2],[3, 4],[5, 6]]).transpose().value(); //[ [ 1, 3, 5 ], [ 2, 4, 6 ] ]
array([[1],[3, 4],[5, 6]]).transpose().value(); //[ [1] ]
array.transpose([[1, 2, 3],[4, 5, 6]]); //[ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
array.transpose([[1, 2],[3, 4],[5, 6]]); //[ [ 1, 3, 5 ], [ 2, 4, 6 ] ]
array.transpose([[1],[3, 4],[5, 6]]); //[ [1] ]valuesAt
Gathers values and the specified indexes.
var arr = array(["a", "b", "c", "d"]);
arr.valuesAt(1, 2, 3).value(); //["b", "c", "d"]
arr.valuesAt(1, 2, 3, 4).value(); //["b", "c", "d", null]
arr.valuesAt(0, 3).value(); //["a", "d"]
arr = ["a", "b", "c", "d"];
array.valuesAt(arr, 1, 2, 3); //["b", "c", "d"]
array.valuesAt(arr, 1, 2, 3, 4); //["b", "c", "d", null]
array.valuesAt(arr, 0, 3); //["a", "d"]union
Finds the union of two arrays.
array(["a", "b", "c"]).union(["b", "c", "d"]).value(); //["a", "b", "c", "d"]);
array(["a"]).union(["b"], ["c"], ["d"], ["c"]).value(); //["a", "b", "c", "d"]);
array.union(["a", "b", "c"], ["b", "c", "d"]); //["a", "b", "c", "d"]);
array.union(["a"], ["b"], ["c"], ["d"], ["c"]); //["a", "b", "c", "d"]);intersect
Finds the intersection of two arrays.
array([1, 2]).intersect([2, 3], [2, 3, 5]).value(); //[2]);
array([1, 2, 3]).intersect([2, 3, 4, 5], [2, 3, 5]).value(); //[2, 3]);
array([1, 2, 3, 4]).intersect([2, 3, 4, 5], [2, 3, 4, 5]).value(); //[2, 3, 4]);
array([1, 2, 3, 4, 5]).intersect([1, 2, 3, 4, 5], [1, 2, 3]).value(); //[1, 2, 3]);
array([[1, 2, 3, 4, 5],[1, 2, 3, 4, 5],[1, 2, 3]]).intersect().value(); //[1, 2, 3]);
array.intersect([1, 2], [2, 3], [2, 3, 5]); //[2]
array.intersect([1, 2, 3], [2, 3, 4, 5], [2, 3, 5]); //[2, 3]
array.intersect([1, 2, 3, 4], [2, 3, 4, 5], [2, 3, 4, 5]); //[2, 3, 4]
array.intersect([1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3]); //[1, 2, 3]);
array.intersect([[1, 2, 3, 4, 5],[1, 2, 3, 4, 5], [1, 2, 3]]); //[1, 2, 3]);powerSet
Finds the powerset of a given array.
array([1, 2, 3]).powerSet().value();
array.powerSet([1, 2, 3]);
//[
// [],
// [ 1 ],
// [ 2 ],
// [ 1, 2 ],
// [ 3 ],
// [ 1, 3 ],
// [ 2, 3 ],
// [ 1, 2, 3 ]
//]cartesian
Finds the cartesian product of arrays.
array([1, 2]).cartesian([2, 3]).value();
array.cartesian([1, 2], [2, 3]);
//[
// [1, 2],
// [1, 3],
// [2, 2],
// [2, 3]
//]compact
Compacts the values of an array.
array([1, null, null, x, 2]).compact().value(); //[1, 2]
array([1, 2]).compact().value(); //[1, 2]
array.compact([1, null, null, x, 2]); //[1, 2]
array.compact([1, 2]); //[1, 2]multiply
Repoduces the values in an array the given number of times.
array([1, 2]).multiply(2).value(); //[1, 2, 1, 2, 1, 2]
array.multiply([1, 2, 3], 2); //[1, 2, 3, 1, 2, 3]flatten
Flatten multiple arrays into a single array.
array([ [1], [2], [3] ]).flatten().value(); //[1, 2, 3]
array.flatten([1, 2], [2, 3], [3, 4]); //[1, 2, 2, 3, 3, 4]pluck
Pluck properties from values in an array.
var arr = [
{name: {first: "Fred", last: "Jones"}, age: 50, roles: ["a", "b", "c"]},
{name: {first: "Bob", last: "Yukon"}, age: 40, roles: ["b", "c"]},
{name: {first: "Alice", last: "Palace"}, age: 35, roles: ["c"]},
{name: {first: "Johnny", last: "P."}, age: 56, roles: []}
];
array.pluck(arr, "name.first"); //["Fred", "Bob", "Alice", "Johnny"]
array(arr).pluck("age"); //[50, 40, 35, 56]invoke
Invokes the specified method on each value in an array.
function person(name, age) {
return {
getName: function () {
return name;
},
getOlder: function () {
age++;
return this;
},
getAge: function () {
return age;
}
};
};
var arr = [person("Bob", 40), person("Alice", 35), person("Fred", 50), person("Johnny", 56)];
array.invoke(arr, "getName"); //["Bob", "Alice", "Fred", "Johnny"];
array(arr).invoke("getName").value(); //["Bob", "Alice", "Fred", "Johnny"];
array(arr).invoke("getOlder").invoke("getAge").value(); //[41, 36, 51, 57];