It has been 1485 days since the last update, the content of the article may be outdated.

Array Functions

Note: All array functions will also work on the arguments object. However, Underscore functions are not designed to work on “sparse” arrays.

first

_.first(array, [n]) Aliases: head, take
Returns the first element of an array. Passing n will return the first n elements of the array.

plaintext
_.first([5, 4, 3, 2, 1]);
=> 5

initial

_.initial(array, [n])
Returns everything but the last entry of the array. Especially useful on the arguments object. Pass n to exclude the last n elements from the result.

plaintext
_.initial([5, 4, 3, 2, 1]);
=> [5, 4, 3, 2]

last

_.last(array, [n])
Returns the last element of an array. Passing n will return the last n elements of the array.

plaintext
_.last([5, 4, 3, 2, 1]);
=> 1

rest

_.rest(array, [index]) Aliases: tail, drop
Returns the rest of the elements in an array. Pass an index to return the values of the array from that index onward.

plaintext
_.rest([5, 4, 3, 2, 1]);
=> [4, 3, 2, 1]

compact

_.compact(array)
Returns a copy of the array with all falsy values removed. In JavaScript, false, null, 0, “”, undefined and NaN are all falsy.

plaintext
_.compact([0, 1, false, 2, '', 3]);
=> [1, 2, 3]

flatten

_.flatten(array, [shallow])
Flattens a nested array (the nesting can be to any depth). If you pass shallow, the array will only be flattened a single level.

plaintext
_.flatten([1, [2], [3, [[4]]]]);
=> [1, 2, 3, 4];

_.flatten([1, [2], [3, [[4]]]], true);
=> [1, 2, 3, [[4]]];

without

_.without(array, *values)
Returns a copy of the array with all instances of the values removed.

plaintext
_.without([1, 2, 1, 0, 3, 1, 4], 0, 1);
=> [2, 3, 4]

union

plaintext
_.union(*arrays)

Computes the union of the passed-in arrays: the list of unique items, in order, that are present in one or more of the arrays.

plaintext
_.union([1, 2, 3], [101, 2, 1, 10], [2, 1]);
=> [1, 2, 3, 101, 10]

intersection

plaintext
_.intersection(*arrays)

Computes the list of values that are the intersection of all the arrays. Each value in the result is present in each of the arrays.

plaintext
_.intersection([1, 2, 3], [101, 2, 1, 10], [2, 1]);
=> [1, 2]

difference

plaintext
_.difference(array, *others)

Similar to without, but returns the values from array that are not present in the other arrays.

plaintext
_.difference([1, 2, 3, 4, 5], [5, 2, 10]);
=> [1, 3, 4]

uniq

plaintext
_.uniq(array, [isSorted], [iteratee]) Alias: unique

Produces a duplicate-free version of the array, using === to test object equality. In particular only the first occurence of each value is kept. If you know in advance that the array is sorted, passing true for isSorted will run a much faster algorithm. If you want to compute unique items based on a transformation, pass an iteratee function.

plaintext
_.uniq([1, 2, 1, 4, 1, 3]);
=> [1, 2, 4, 3]

zip

plaintext
_.zip(*arrays)

Merges together the values of each of the arrays with the values at the corresponding position. Useful when you have separate data sources that are coordinated through matching array indexes. Use with apply to pass in an array of arrays. If you’re working with a matrix of nested arrays, this can be used to transpose the matrix.

plaintext
_.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
=> [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]

unzip

plaintext
_.unzip(array)

The opposite of zip. Given an array of arrays, returns a series of new arrays, the first of which contains all of the first elements in the input arrays, the second of which contains all of the second elements, and so on.

plaintext
_.unzip([["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]);
=> [['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]]

object

plaintext
_.object(list, [values])

Converts arrays into objects. Pass either a single list of [key, value] pairs, or a list of keys, and a list of values. If duplicate keys exist, the last value wins.

plaintext
_.object(['moe', 'larry', 'curly'], [30, 40, 50]);
=> {moe: 30, larry: 40, curly: 50}

_.object([['moe', 30], ['larry', 40], ['curly', 50]]);
=> {moe: 30, larry: 40, curly: 50}

indexOf

plaintext
_.indexOf(array, value, [isSorted])

Returns the index at which value can be found in the array, or -1 if value is not present in the array. If you’re working with a large array, and you know that the array is already sorted, pass true for isSorted to use a faster binary search … or, pass a number as the third argument in order to look for the first matching value in the array after the given index.

plaintext
_.indexOf([1, 2, 3], 2);
=> 1

lastIndexOf

plaintext
_.lastIndexOf(array, value, [fromIndex])

Returns the index of the last occurrence of value in the array, or -1 if value is not present. Pass fromIndex to start your search at a given index.

plaintext
_.lastIndexOf([1, 2, 3, 1, 2, 3], 2);
=> 4

sortedIndex

plaintext
_.sortedIndex(list, value, [iteratee], [context])

Uses a binary search to determine the index at which the value should be inserted into the list in order to maintain the list’s sorted order. If an iteratee function is provided, it will be used to compute the sort ranking of each value, including the value you pass. The iteratee may also be the string name of the property to sort by (eg. length).

plaintext
_.sortedIndex([10, 20, 30, 40, 50], 35);
=> 3

var stooges = [{name: 'moe', age: 40}, {name: 'curly', age: 60}];
_.sortedIndex(stooges, {name: 'larry', age: 50}, 'age');
=> 1

findIndex

plaintext
_.findIndex(array, predicate, [context])

Similar to _.indexOf, returns the first index where the predicate truth test passes; otherwise returns -1.

plaintext
_.findIndex([4, 6, 8, 12], isPrime);
=> -1 // not found
_.findIndex([4, 6, 7, 12], isPrime);
=> 2

findLastIndex

plaintext
_.findLastIndex(array, predicate, [context])

Like _.findIndex but iterates the array in reverse, returning the index closest to the end where the predicate truth test passes.

plaintext
var users = [{'id': 1, 'name': 'Bob', 'last': 'Brown'},
             {'id': 2, 'name': 'Ted', 'last': 'White'},
             {'id': 3, 'name': 'Frank', 'last': 'James'},
             {'id': 4, 'name': 'Ted', 'last': 'Jones'}];
_.findLastIndex(users, {
  name: 'Ted'
});
=> 3

range

plaintext
_.range([start], stop, [step])

A function to create flexibly-numbered lists of integers, handy for each and map loops. start, if omitted, defaults to 0; step defaults to 1. Returns a list of integers from start (inclusive) to stop (exclusive), incremented (or decremented) by step, exclusive. Note that ranges that stop before they start are considered to be zero-length instead of negative — if you’d like a negative range, use a negative step.

plaintext
_.range(10);
=> [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
_.range(1, 11);
=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
_.range(0, 30, 5);
=> [0, 5, 10, 15, 20, 25]
_.range(0, -10, -1);
=> [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
_.range(0);
=> []