Util methods

Util methods are general-purpose helpers that do not fit another category: iteratee shorthands, function generators (constant, property, matches), identifiers, and no-op placeholders used in custom builds.

_.attempt(func, [args])

Available since v3.0.0.

Attempts to invoke func, returning either the result or the caught error object. Any additional arguments are provided to func when it's invoked.

Returns any — Returns the func result or error object.

// Avoid throwing errors for invalid selectors.
var elements = _.attempt(function(selector) {
  return document.querySelectorAll(selector);
}, '>_>');

if (_.isError(elements)) {
  elements = [];
}

_.bindAll(object, methodNames)

Available since v0.1.0.

Binds methods of an object to the object itself, overwriting the existing method.

Note: This method doesn't set the "length" property of bound functions.

Returns Object — Returns object.

var view = {
  'label': 'docs',
  'click': function() {
    console.log('clicked ' + this.label);
  }
};

_.bindAll(view, ['click']);
jQuery(element).on('click', view.click);
// => Logs 'clicked docs' when clicked.

_.cond(pairs)

Available since v4.0.0.

Creates a function that iterates over pairs and invokes the corresponding function of the first predicate to return truthy. The predicate-function pairs are invoked with the this binding and arguments of the created function.

Returns Function — Returns the new composite function.

var func = _.cond([
  [_.matches({ 'a': 1 }),           _.constant('matches A')],
  [_.conforms({ 'b': _.isNumber }), _.constant('matches B')],
  [_.stubTrue,                      _.constant('no match')]
]);

func({ 'a': 1, 'b': 2 });
// => 'matches A'

func({ 'a': 0, 'b': 1 });
// => 'matches B'

func({ 'a': '1', 'b': '2' });
// => 'no match'

_.conforms(source)

Available since v4.0.0.

Creates a function that invokes the predicate properties of source with the corresponding property values of a given object, returning true if all predicates return truthy, else false.

Note: The created function is equivalent to _.conformsTo with source partially applied.

Returns Function — Returns the new spec function.

var objects = [
  { 'a': 2, 'b': 1 },
  { 'a': 1, 'b': 2 }
];

_.filter(objects, _.conforms({ 'b': function(n) { return n > 1; } }));
// => [{ 'a': 1, 'b': 2 }]

_.constant(value)

Available since v2.4.0.

Creates a function that returns value.

Returns Function — Returns the new constant function.

var objects = _.times(2, _.constant({ 'a': 1 }));

console.log(objects);
// => [{ 'a': 1 }, { 'a': 1 }]

console.log(objects[0] === objects[1]);
// => true

_.defaultTo(value, defaultValue)

Available since v4.14.0.

Checks value to determine whether a default value should be returned in its place. The defaultValue is returned if value is NaN, null, or undefined.

Returns any — Returns the resolved value.

_.defaultTo(1, 10);
// => 1

_.defaultTo(undefined, 10);
// => 10

_.flow([funcs])

Available since v3.0.0.

Creates a function that returns the result of invoking the given functions with the this binding of the created function, where each successive invocation is supplied the return value of the previous.

Returns Function — Returns the new composite function.

function square(n) {
  return n * n;
}

var addSquare = _.flow([_.add, square]);
addSquare(1, 2);
// => 9

_.flowRight([funcs])

Available since v3.0.0.

This method is like _.flow except that it creates a function that invokes the given functions from right to left.

Returns Function — Returns the new composite function.

function square(n) {
  return n * n;
}

var addSquare = _.flowRight([square, _.add]);
addSquare(1, 2);
// => 9

_.identity(value)

Available since v0.1.0.

This method returns the first argument it receives.

Returns any — Returns value.

var object = { 'a': 1 };

console.log(_.identity(object) === object);
// => true

_.iteratee([func=identity])

Available since v4.0.0.

Creates a function that invokes func with the arguments of the created function. If func is a property name, the created function returns the property value for a given element. If func is an array or object, the created function returns true for elements that contain the equivalent source properties, otherwise it returns false.

Returns Function — Returns the callback.

var users = [
  { 'user': 'barney', 'age': 36, 'active': true },
  { 'user': 'fred',   'age': 40, 'active': false }
];

// The `_.matches` iteratee shorthand.
_.filter(users, _.iteratee({ 'user': 'barney', 'active': true }));
// => [{ 'user': 'barney', 'age': 36, 'active': true }]

// The `_.matchesProperty` iteratee shorthand.
_.filter(users, _.iteratee(['user', 'fred']));
// => [{ 'user': 'fred', 'age': 40 }]

// The `_.property` iteratee shorthand.
_.map(users, _.iteratee('user'));
// => ['barney', 'fred']

// Create custom iteratee shorthands.
_.iteratee = _.wrap(_.iteratee, function(iteratee, func) {
  return !_.isRegExp(func) ? iteratee(func) : function(string) {
    return func.test(string);
  };
});

_.filter(['abc', 'def'], /ef/);
// => ['def']

_.matches(source)

Available since v3.0.0.

Creates a function that performs a partial deep comparison between a given object and source, returning true if the given object has equivalent property values, else false.

Note: The created function is equivalent to _.isMatch with source partially applied.

Partial comparisons will match empty array and empty object source values against any array or object value, respectively. See _.isEqual for a list of supported value comparisons.

Note: Multiple values can be checked by combining several matchers using _.overSome

Returns Function — Returns the new spec function.

var objects = [
  { 'a': 1, 'b': 2, 'c': 3 },
  { 'a': 4, 'b': 5, 'c': 6 }
];

_.filter(objects, _.matches({ 'a': 4, 'c': 6 }));
// => [{ 'a': 4, 'b': 5, 'c': 6 }]

// Checking for several possible values
_.filter(objects, _.overSome([_.matches({ 'a': 1 }), _.matches({ 'a': 4 })]));
// => [{ 'a': 1, 'b': 2, 'c': 3 }, { 'a': 4, 'b': 5, 'c': 6 }]

_.matchesProperty(path, srcValue)

Available since v3.2.0.

Creates a function that performs a partial deep comparison between the value at path of a given object to srcValue, returning true if the object value is equivalent, else false.

Note: Partial comparisons will match empty array and empty object srcValue values against any array or object value, respectively. See _.isEqual for a list of supported value comparisons.

Note: Multiple values can be checked by combining several matchers using _.overSome

Returns Function — Returns the new spec function.

var objects = [
  { 'a': 1, 'b': 2, 'c': 3 },
  { 'a': 4, 'b': 5, 'c': 6 }
];

_.find(objects, _.matchesProperty('a', 4));
// => { 'a': 4, 'b': 5, 'c': 6 }

// Checking for several possible values
_.filter(objects, _.overSome([_.matchesProperty('a', 1), _.matchesProperty('a', 4)]));
// => [{ 'a': 1, 'b': 2, 'c': 3 }, { 'a': 4, 'b': 5, 'c': 6 }]

_.method(path, [args])

Available since v3.7.0.

Creates a function that invokes the method at path of a given object. Any additional arguments are provided to the invoked method.

Returns Function — Returns the new invoker function.

var objects = [
  { 'a': { 'b': _.constant(2) } },
  { 'a': { 'b': _.constant(1) } }
];

_.map(objects, _.method('a.b'));
// => [2, 1]

_.map(objects, _.method(['a', 'b']));
// => [2, 1]

_.methodOf(object, [args])

Available since v3.7.0.

The opposite of _.method; this method creates a function that invokes the method at a given path of object. Any additional arguments are provided to the invoked method.

Returns Function — Returns the new invoker function.

var array = _.times(3, _.constant),
    object = { 'a': array, 'b': array, 'c': array };

_.map(['a[2]', 'c[0]'], _.methodOf(object));
// => [2, 0]

_.map([['a', '2'], ['c', '0']], _.methodOf(object));
// => [2, 0]

_.mixin([object=lodash], source, [options={}])

Available since v0.1.0.

Adds all own enumerable string keyed function properties of a source object to the destination object. If object is a function, then methods are added to its prototype as well.

Note: Use _.runInContext to create a pristine lodash function to avoid conflicts caused by modifying the original.

Returns any — Returns object.

function vowels(string) {
  return _.filter(string, function(v) {
    return /[aeiou]/i.test(v);
  });
}

_.mixin({ 'vowels': vowels });
_.vowels('fred');
// => ['e']

_('fred').vowels().value();
// => ['e']

_.mixin({ 'vowels': vowels }, { 'chain': false });
_('fred').vowels();
// => ['e']

_.noConflict()

Available since v0.1.0.

Reverts the _ variable to its previous value and returns a reference to the lodash function.

Returns Function — Returns the lodash function.

var lodash = _.noConflict();

_.noop()

Available since v2.3.0.

This method returns undefined.

_.times(2, _.noop);
// => [undefined, undefined]

_.nthArg([n=0])

Available since v4.0.0.

Creates a function that gets the argument at index n. If n is negative, the nth argument from the end is returned.

Returns Function — Returns the new pass-thru function.

var func = _.nthArg(1);
func('a', 'b', 'c', 'd');
// => 'b'

var func = _.nthArg(-2);
func('a', 'b', 'c', 'd');
// => 'c'

_.over([iteratees=[identity]])

Available since v4.0.0.

Creates a function that invokes iteratees with the arguments it receives and returns their results.

Returns Function — Returns the new function.

var func = _.over([Math.max, Math.min]);

func(1, 2, 3, 4);
// => [4, 1]

_.overEvery([predicates=[identity]])

Available since v4.0.0.

Creates a function that checks if all of the predicates return truthy when invoked with the arguments it receives.

Following shorthands are possible for providing predicates. Pass an Object and it will be used as an parameter for _.matches to create the predicate. Pass an Array of parameters for matchesProperty and the predicate will be created using them.

Returns Function — Returns the new function.

var func = _.overEvery([Boolean, isFinite]);

func('1');
// => true

func(null);
// => false

func(NaN);
// => false

_.overSome([predicates=[identity]])

Available since v4.0.0.

Creates a function that checks if any of the predicates return truthy when invoked with the arguments it receives.

Following shorthands are possible for providing predicates. Pass an Object and it will be used as an parameter for _.matches to create the predicate. Pass an Array of parameters for matchesProperty and the predicate will be created using them.

Returns Function — Returns the new function.

var func = _.overSome([Boolean, isFinite]);

func('1');
// => true

func(null);
// => true

func(NaN);
// => false

var matchesFunc = _.overSome([{ 'a': 1 }, { 'a': 2 }])
var matchesPropertyFunc = _.overSome([['a', 1], ['a', 2]])

_.property(path)

Available since v2.4.0.

Creates a function that returns the value at path of a given object.

Returns Function — Returns the new accessor function.

var objects = [
  { 'a': { 'b': 2 } },
  { 'a': { 'b': 1 } }
];

_.map(objects, _.property('a.b'));
// => [2, 1]

_.map(_.sortBy(objects, _.property(['a', 'b'])), 'a.b');
// => [1, 2]

_.propertyOf(object)

Available since v3.0.0.

The opposite of _.property; this method creates a function that returns the value at a given path of object.

Returns Function — Returns the new accessor function.

var array = [0, 1, 2],
    object = { 'a': array, 'b': array, 'c': array };

_.map(['a[2]', 'c[0]'], _.propertyOf(object));
// => [2, 0]

_.map([['a', '2'], ['c', '0']], _.propertyOf(object));
// => [2, 0]

_.range([start=0], end, [step=1])

Available since v0.1.0.

Creates an array of numbers (positive and/or negative) progressing from start up to, but not including, end. A step of -1 is used if a negative start is specified without an end or step. If end is not specified, it's set to start with start then set to 0.

Note: JavaScript follows the IEEE-754 standard for resolving floating-point values which can produce unexpected results.

Returns Array — Returns the range of numbers.

_.range(4);
// => [0, 1, 2, 3]

_.range(-4);
// => [0, -1, -2, -3]

_.range(1, 5);
// => [1, 2, 3, 4]

_.range(0, 20, 5);
// => [0, 5, 10, 15]

_.range(0, -4, -1);
// => [0, -1, -2, -3]

_.range(1, 4, 0);
// => [1, 1, 1]

_.range(0);
// => []

_.rangeRight([start=0], end, [step=1])

Available since v4.0.0.

This method is like _.range except that it populates values in descending order.

Returns Array — Returns the range of numbers.

_.rangeRight(4);
// => [3, 2, 1, 0]

_.rangeRight(-4);
// => [-3, -2, -1, 0]

_.rangeRight(1, 5);
// => [4, 3, 2, 1]

_.rangeRight(0, 20, 5);
// => [15, 10, 5, 0]

_.rangeRight(0, -4, -1);
// => [-3, -2, -1, 0]

_.rangeRight(1, 4, 0);
// => [1, 1, 1]

_.rangeRight(0);
// => []

_.runInContext([context=root])

Available since v1.1.0.

Create a new pristine lodash function using the context object.

Returns Function — Returns a new lodash function.

_.mixin({ 'foo': _.constant('foo') });

var lodash = _.runInContext();
lodash.mixin({ 'bar': lodash.constant('bar') });

_.isFunction(_.foo);
// => true
_.isFunction(_.bar);
// => false

lodash.isFunction(lodash.foo);
// => false
lodash.isFunction(lodash.bar);
// => true

// Create a suped-up `defer` in Node.js.
var defer = _.runInContext({ 'setTimeout': setImmediate }).defer;

_.stubArray()

Available since v4.13.0.

This method returns a new empty array.

Returns Array — Returns the new empty array.

var arrays = _.times(2, _.stubArray);

console.log(arrays);
// => [[], []]

console.log(arrays[0] === arrays[1]);
// => false

_.stubFalse()

Available since v4.13.0.

This method returns false.

Returns boolean — Returns false.

_.times(2, _.stubFalse);
// => [false, false]

_.stubObject()

Available since v4.13.0.

This method returns a new empty object.

Returns Object — Returns the new empty object.

var objects = _.times(2, _.stubObject);

console.log(objects);
// => [{}, {}]

console.log(objects[0] === objects[1]);
// => false

_.stubString()

Available since v4.13.0.

This method returns an empty string.

Returns string — Returns the empty string.

_.times(2, _.stubString);
// => ['', '']

_.stubTrue()

Available since v4.13.0.

This method returns true.

Returns boolean — Returns true.

_.times(2, _.stubTrue);
// => [true, true]

_.times(n, [iteratee=identity])

Available since v0.1.0.

Invokes the iteratee n times, returning an array of the results of each invocation. The iteratee is invoked with one argument; (index).

Returns Array — Returns the array of results.

_.times(3, String);
// => ['0', '1', '2']

 _.times(4, _.constant(0));
// => [0, 0, 0, 0]

_.toPath(value)

Available since v4.0.0.

Converts value to a property path array.

Returns Array — Returns the new property path array.

_.toPath('a.b.c');
// => ['a', 'b', 'c']

_.toPath('a[0].b.c');
// => ['a', '0', 'b', 'c']

_.uniqueId([prefix=''])

Available since v0.1.0.

Generates a unique ID. If prefix is given, the ID is appended to it.

Returns string — Returns the unique ID.

_.uniqueId('contact_');
// => 'contact_104'

_.uniqueId();
// => '105'