Additional array extensions that can be used standalone or integrated with extended
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
test
.gitignore
.jshintrc
.npmignore
.travis.yml
Gruntfile.js
LICENSE
README.md
array-extended.min.js
index.js
package.json

README.md

Build Status

browser support

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-extended

Or 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.

  • forEach
  • map
  • filter
  • reduce
  • reduceRight
  • some
  • every
  • indexOf
  • lastIndexOf

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(); //6

avg

Finds the average of an array of numbers.

array.avg([1,2,3]); //2

array([1,2,3]).avg().value(); //2

sort

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