A lot of what i do with JavaScript involves manipulating arrays. I wrote this library, to make my life easier by extending the JavaScript Array prototype. It worked! Use with creativity, and it will serve you well ... Holla, if you think of something that should be there. I'd be quite willing to add to and remove functions. I hope ArraysJS makes your life easier too.
To use, download a copy of the Arrays.js file, and reference in your web page. Have fun using ArraysJSs.
I have tried as much as possible to free ArraysJS of dependencies on third-party javascript javascript libraries. ArraysJS has no dependencies, and runs entirely on pure javascript.
Give examples
Add a script reference to the Arrays.js file
<script src="js/arrays.js"></script>
item: The object, array or literal to be added to the array.
This is very similar to Array.prototype.push, however it returns the resultant array, so that you can chain other prototype functions.
var arr = [1,2,3];
arr.add(4).add(5).add(6);
console.log(arr); //should print out [1,2,3,4,5,6]
item: The object, array or literal to be added to (if not exists) the array.
[property_name]: A string, specifying the property name of the array's children objects to check.
Adds an item into the array, if the array does not already have a child with the same value, or a child whose property (with key property_name) has the same value as item[property_name]. The argument, [property_name] is optional.
var arr = [1,2,3]
arr.addif(4); //[1,2,3,4]
arr.addif(4); //[1,2,3,4]
arr.addif(5); //[1,2,3,4,5]
When dealing with Array of objects,
var arr = [{
id: 1,
name: "john doe"
},
{
id: 2,
name: "alfred pete"
}];
arr.addif({
id: 1,
name: "john doe"
}, 'id') //does not add this object to the array, because an item with the same key already exists
item: The object, array or literal to be added to (if not exists) or removed from (if exists) the array.
[property_name]: A string, specifying the property name of the array's children objects to check.
var arr = [1,2,3];
arr.toggle(1); //[2,3]
arr.toggle(1); //[2,3,1]
arr = [{
id: 1,
name: "john doe"
},
{
id: 2,
name: "alfred pete"
}];
arr.toggle({
id: 1,
name: "john doe"
}, 'id') //removes the object from array arr where id is 1
arr.toggle({
id: 1,
name: "john doe"
}, 'id') //pushes the object unto the array arr
arrs: An array of objects, which will each be inserted into the calling Array
var arr = [1,2,3];
arr.addRange([4,5,6]) //[1,2,3,4,5,6]
Returns a sub-array containing items from the specified index to the end of the parent-array
index: An integer, which determines which point to start counting from
var arr = [1,2,3,4,5,6]
arr.from(2) //[3,4,5,6]
[count]: An optional parameter; If not set, this function returns the first item in the array, or if the array is empty, it returns an empty object {} instead. If set to an integer, it returns the first [count] children of the array.=
var arr = [1,2,3]
arr.first() // 1
arr.first(2) // [1,2]
arr.first(1) // [1]
Similar to Array.prototype.first, this starts from the end of the array rather than from the first item when counting.
[count]: An optional parameter; If not set, returns the last item in the array. If set, the [count] last items in the array are returned in positional order as a sub-array
var arr = [1,2,3]
arr.last() // 3
arr.last(2) // [2,3]
arr.first(1) // [3]
Gets a sub-array with items whose specified property match a specified value
val: The value that the properties have to match to be valid prop: The key of the properties in question. It has to be a literal object. E.g. A string, Number, or even a boolean
var arr = [{
id: 1,
level: 3,
name: "john doe"
},
{
id: 2,
level: 4,
name: "alfred pete"
},
{
id: 3,
level: 3,
name: "elton john"
}];
arr.where('level', 3) //returns the objects containing names 'john doe' and 'elton john'
I know there is a native implementation of Array.prototype.sort, but i guess i was feeling a bit like superman when i wrote this. Anyway, the real kicker on this one is its ability to sort (using bubble sort) in ascending or descending order
[type]: An optional parameter; If not set or if set to 'asc', the array is sorted in ascending order. If set to 'desc' or anything besides 'asc', the array is sorted in descending order
var arr = [3,2,1,3,5,4,6]
arr.sort(); // [1,2,3,3,4,5,6]
Insertion sort. Very useful for large arrays
[type]: An optional parameter; If not set or if set to 'asc', the array is sorted in ascending order. If set to 'desc' or anything besides 'asc', the array is sorted in descending order
var arr = [3,2,1,3,5,4,6]
arr.isort(); // [1,2,3,3,4,5,6]
Performs binary search on a sorted array for the item specified in the argument. THe index of the item is returned. If not found, -1 is returned. Useful for when dealing with very large arrays
item: The literal object to be found
var arr = [3,2,1,3,4,5,6]
arr.bsearch(1) // 2
arr.bsearch(7) // -1
Sorts the array in ascending or descending order by its children's properties with key (prop)
[prop]: The property key by which the array is to be sorted. If not specified, Array.prototype.sort is executed instead [type]: Specifies whether the array should be sorted in ascending or descending order. value 'asc' translates to ascending order, while 'desc' translates to 'descending' order
var arr = [{
id: 1,
level: 3,
name: "john doe"
},
{
id: 2,
level: 4,
name: "alfred pete"
},
{
id: 3,
level: 3,
name: "elton john"
}];
arr.sortBy('level') //sorts array arr by level in ascending order
arr.sortBy('level', 'desc') //sorts array arr by level in descending order
Performs a sort on the Array based on a function that compares the potential current and next items in the array.
fn: A function that takes in item1 and item2 as parameters. If not specified, or if set to a value that is not a function, it takes the default value
function (val1, val2) { return val1 > val2 } //which makes sure the array is sorted in ascending order
var arr = [3,2,1,3,4,5,6]
arr.sortfn(function (val1, val2) { return val1 < val2 }) //[6, 5, 4, 3, 3, 2, 1] sorts in descending order.
Returns a boolean indicating whether the array is sorted or not
[type]: Indicates the sorted type to check for. 'asc' translates to ascending. 'desc' translates to descending
var arr = [1,2,3,4,5,6];
arr.isSorted() //true
arr.isSorted('asc') //true
arr.isSorted('desc') //false
Inserts an item into an index in the array, while the items at the right of the index are shifted to the right
item: The object to be inserted index: The integer index, in which the object item should be inserted
var arr = [1,2,3,4,5,6];
arr.insert(7, 2); //[1,2,7,3,4,5,6]
Empties an array
var arr = [1,2,3,4,5,6];
arr.clear() // []
Returns the length of the array ... Redundant, huh? :D
var arr = [1,2,3,4,5,6];
arr.count(); // 6
Returns the index of the first instance of an object, in the array's items or among the array's items' properties specified by key [prop]
item: The object to be found index: The integer index, in which the object item should be inserted
var arr = [{id: 1},{id: 2},{id: 3},{id: 4}];
arr.indexOfProp(3, 'id') // 2
Returns a boolean value indicating whether the array contains the object item, or checks the values in key [prop] of the array's items
item: The object to be found [prop]: The key to be searched. If specified, it compares object item with child_object[prop]
var arr = [{id: 1},{id: 2},{id: 3},{id: 4}];
arr.contains(3, 'id') // true
arr.contains(7, 'id') // false
arr.contains(7, 'prop') // false
arr.contains(3) // false
Results distinct elements in the array or uses a key if specified
[prop]: if specified, makes the array distinct by its elements[prop] value
var arr = [1,1,4,2,3,2,3,4,5,4,4,2,2,1];
arr.distinct() //[1,4,2,3,5]
Removes all instances of an item from the array
item: The item to be removed [prop]: if specified, finds the item whose item[prop] value matches item, and removes it
var arr = [1,1,4,2,3,2,3,4,5,4,4,2,2,1];
arr.remove(1); //[4,2,3,2,3,4,5,4,4,2,2]
arr = [{age: 2},{age: 2},{age: 2},{age: 3}]
arr.remove(2, 'age') // [{age: 3}]
Removes an item at an index from the array
index: The integer index of the item to be removed
var arr = [1,2,3,4];
arr.removeAt(1); //[1,3,4]
arr = [{age: 2},{age: 2},{age: 2},{age: 3}]
arr.removeAt(0) // [{age: 2},{age: 2},{age: 3}]
rearranges an array randomly
arr.shuffle(); //scatters its elements
Returns an array with numbers ranging from [start] to [end]
var arr = [1,1,4,2,3,2,3,4,5,4,4,2,2,1];
arr.remove(1); //[4,2,3,2,3,4,5,4,4,2,2]
arr = [{age: 2},{age: 2},{age: 2},{age: 3}]
arr.remove(2, 'age') // [{age: 3}]
Returns an array whose
var arr = [{age: 2},{age: 2},{age: 2},{age: 3}]
arr.select('age') // [2,2,3]
Returns a boolean indicating
var arr = [];
arr.isEmpty(); // true
arr.add(1).isEmpty() //false
Works like Array.prototype.forEach, pass in a function to manipulate the array's elements. In defence, i didn't know about Array.prototype.forEach when i wrote this function. One major difference is this gives you access to the loop index.
var arr = [1,2,3];
arr.each((i) => {
i *= 2;
console.log(arr.index);
}); //[1,4,9]
//console output
/*
0
1
2
*/
Converts an array containing arrays as elements, into an array of objects, by listing out the child arrays as objects
var arr = [
[1,2,3],
[4,5,6],
[7,8,9]
];
arr.flatten(); //[1,2,3,4,5,6,7,8,9]
Groups the array elements, in groups of [maxsize] lengths
maxsize: the maximum size of the sub-groups before a new sub-group is created
var arr = [1,2,3,4,5,6,7,8,9];
arr.paginate(3);
/*
[
[1,2,3],
[4,5,6],
[7,8,9]
]
*/
returns the minimum element in the array
var arr = [1,2,3,4,5,6,7,8,9];
arr.min(); // 1
returns the maximum element in the array
var arr = [1,2,3,4,5,6,7,8,9];
arr.max(); // 9
returns the average element in an array of numbers
var arr = [1,2,3,4,5,6,7,8,9];
arr.average(); // 5
returns the sum of the elements in an array of numbers
var arr = [1,2,3,4,5,6,7,8,9];
arr.sum(); // 45
Copies elements from second_array into an array if such an element does not exist
var arr = [1,2,3,4,5,6,7,8,9];
var arr2 = [3,7,4,12,0]
arr.sync(arr2); // [1,2,3,4,5,6,7,8,9,12,0]
var arr = [1,2,3,4,5,6,7,8,9];
arr.random() //returns a random item from arr
arr.random(2) //returns two random items from arr
Returns a boolean that indicates whether or not all elements in the array satisfy a condition specified by the function argument (fn)
var arr = [1,2,3,4,5,6,7,8,9];
arr.all((i) => i > 0) //return true
arr.all((i) => i >= 3) //return false
arr.all(function (i) { return i >= 5; }) //return false
Counts the occurences of instances of object value in the array, or in the property prop values.
var arr = [1,2,1,3,2,2,1,4,5,3,4,5,6,7,8,9];
arr.frequency(1); // 2
arr.frequency(2); // 3
remove all falsy (null, undefined, 0, etc) elements from the array.
var arr = [1,2,3, undefined, null, 0];
arr.trim(); // [1,2,3]
- Pure Javascript
Not yet
I haven't gotten around to reading about versioning on git
Ikechi Michael
This project is licensed under the MIT License
- Hat tip to Life and Science
- etc