_.after(n, func)

The opposite of _.before; this method creates a function that invokes func once it’s called n or more times.

Since

0.1.0

Arguments

1. n (number): The number of calls before func is invoked.
2. func (Function): The function to restrict.

Returns

(Function): Returns the new restricted function.

Example

var saves = ['profile', 'settings'];
var done = _.after(saves.length, function() {
  console.log('done saving!');
});
_.forEach(saves, function(type) {
  asyncSave({ 'type': type, 'complete': done });
});
// => Logs 'done saving!' after the two async saves have completed.

_.ary(func, [n=func.length])

Creates a function that invokes func, with up to n arguments, ignoring any additional arguments.

Since

3.0.0

Arguments

1. func (Function): The function to cap arguments for.
2. [n=func.length] (number): The arity cap.

Returns

(Function): Returns the new capped function.

Example

_.map(['6', '8', '10'], _.ary(parseInt, 1));
// => [6, 8, 10]

_.before(n, func)

Creates a function that invokes func, with the this binding and arguments of the created function, while it’s called less than n times. Subsequent calls to the created function return the result of the last func invocation.

Since

3.0.0

Arguments

1. n (number): The number of calls at which func is no longer invoked.
2. func (Function): The function to restrict.

Returns

(Function): Returns the new restricted function.

Example

jQuery(element).on('click', _.before(5, addContactToList));
// => Allows adding up to 4 contacts to the list.

_.bind(func, thisArg, [partials])

Creates a function that invokes func with the this binding of thisArg and partials prepended to the arguments it receives.

The _.bind.placeholder value, which defaults to _ in monolithic builds, may be used as a placeholder for partially applied arguments.

Note: Unlike native Function#bind, this method doesn’t set the “length” property of bound functions.

Since

0.1.0

Arguments

1. func (Function): The function to bind.
2. thisArg (*): The this binding of func.
3. [partials] (…*): The arguments to be partially applied.

Returns

(Function): Returns the new bound function.

Example

function greet(greeting, punctuation) {
  return greeting + ' ' + this.user + punctuation;
}
var object = { 'user': 'fred' };
var bound = _.bind(greet, object, 'hi');
bound('!');
// => 'hi fred!'
// Bound with placeholders.
var bound = _.bind(greet, object, _, '!');
bound('hi');
// => 'hi fred!'

_.bindKey(object, key, [partials])

Creates a function that invokes the method at object[key] with partials prepended to the arguments it receives.

This method differs from _.bind by allowing bound functions to reference methods that may be redefined or don’t yet exist. See Peter Michaux’s article for more details.

The _.bindKey.placeholder value, which defaults to _ in monolithic builds, may be used as a placeholder for partially applied arguments.

Since

0.10.0

Arguments

1. object (Object): The object to invoke the method on.
2. key (string): The key of the method.
3. [partials] (…*): The arguments to be partially applied.

Returns

(Function): Returns the new bound function.

Example

var object = {
  'user': 'fred',
  'greet': function(greeting, punctuation) {
    return greeting + ' ' + this.user + punctuation;
  }
};
var bound = _.bindKey(object, 'greet', 'hi');
bound('!');
// => 'hi fred!'
object.greet = function(greeting, punctuation) {
  return greeting + 'ya ' + this.user + punctuation;
};
bound('!');
// => 'hiya fred!'
// Bound with placeholders.
var bound = _.bindKey(object, 'greet', _, '!');
bound('hi');
// => 'hiya fred!'

_.curry(func, [arity=func.length])

Creates a function that accepts arguments of func and either invokes func returning its result, if at least arity number of arguments have been provided, or returns a function that accepts the remaining func arguments, and so on. The arity of func may be specified if func.length is not sufficient.

The _.curry.placeholder value, which defaults to _ in monolithic builds, may be used as a placeholder for provided arguments.

Note: This method doesn’t set the “length” property of curried functions.

Since

2.0.0

Arguments

1. func (Function): The function to curry.
2. [arity=func.length] (number): The arity of func.

Returns

(Function): Returns the new curried function.

Example

var abc = function(a, b, c) {
  return [a, b, c];
};
var curried = _.curry(abc);
curried(1)(2)(3);
// => [1, 2, 3]
curried(1, 2)(3);
// => [1, 2, 3]
curried(1, 2, 3);
// => [1, 2, 3]
// Curried with placeholders.
curried(1)(_, 3)(2);
// => [1, 2, 3]

_.curryRight(func, [arity=func.length])

This method is like _.curry except that arguments are applied to func in the manner of _.partialRight instead of _.partial.

The _.curryRight.placeholder value, which defaults to _ in monolithic builds, may be used as a placeholder for provided arguments.

Note: This method doesn’t set the “length” property of curried functions.

Since

3.0.0

Arguments

1. func (Function): The function to curry.
2. [arity=func.length] (number): The arity of func.

Returns

(Function): Returns the new curried function.

Example

var abc = function(a, b, c) {
  return [a, b, c];
};
var curried = _.curryRight(abc);
curried(3)(2)(1);
// => [1, 2, 3]
curried(2, 3)(1);
// => [1, 2, 3]
curried(1, 2, 3);
// => [1, 2, 3]
// Curried with placeholders.
curried(3)(1, _)(2);
// => [1, 2, 3]

_.debounce(func, [wait=0], [options={}])

Creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked. The debounced function comes with a cancel method to cancel delayed func invocations and a flush method to immediately invoke them. Provide options to indicate whether func should be invoked on the leading and/or trailing edge of the wait timeout. The func is invoked with the last arguments provided to the debounced function. Subsequent calls to the debounced function return the result of the last func invocation.

Note: If leading and trailing options are true, func is invoked on the trailing edge of the timeout only if the debounced function is invoked more than once during the wait timeout.

If wait is 0 and leading is false, func invocation is deferred until to the next tick, similar to setTimeout with a timeout of 0.

See David Corbacho’s article for details over the differences between _.debounce and _.throttle.

Since

0.1.0

Arguments

1. func (Function): The function to debounce.
2. [wait=0] (number): The number of milliseconds to delay.
3. [options={}] (Object): The options object.
4. [options.leading=false] (boolean): Specify invoking on the leading edge of the timeout.
5. [options.maxWait] (number): The maximum time func is allowed to be delayed before it’s invoked.
6. [options.trailing=true] (boolean): Specify invoking on the trailing edge of the timeout.

Returns

(Function): Returns the new debounced function.

Example

// Avoid costly calculations while the window size is in flux.
jQuery(window).on('resize', _.debounce(calculateLayout, 150));
// Invoke `sendMail` when clicked, debouncing subsequent calls.
jQuery(element).on('click', _.debounce(sendMail, 300, {
  'leading': true,
  'trailing': false
}));
// Ensure `batchLog` is invoked once after 1 second of debounced calls.
var debounced = _.debounce(batchLog, 250, { 'maxWait': 1000 });
var source = new EventSource('/stream');
jQuery(source).on('message', debounced);
// Cancel the trailing debounced invocation.
jQuery(window).on('popstate', debounced.cancel);

_.defer(func, [args])

Defers invoking the func until the current call stack has cleared. Any additional arguments are provided to func when it’s invoked.

Since

0.1.0

Arguments

1. func (Function): The function to defer.
2. [args] (…*): The arguments to invoke func with.

Returns

(number): Returns the timer id.

Example

_.defer(function(text) {
  console.log(text);
}, 'deferred');
// => Logs 'deferred' after one millisecond.

_.delay(func, wait, [args])

Invokes func after wait milliseconds. Any additional arguments are provided to func when it’s invoked.

Since

0.1.0

Arguments

1. func (Function): The function to delay.
2. wait (number): The number of milliseconds to delay invocation.
3. [args] (…*): The arguments to invoke func with.

Returns

(number): Returns the timer id.

Example

_.delay(function(text) {
  console.log(text);
}, 1000, 'later');
// => Logs 'later' after one second.

_.flip(func)

Creates a function that invokes func with arguments reversed.

Since

4.0.0

Arguments

1. func (Function): The function to flip arguments for.

Returns

(Function): Returns the new flipped function.

Example

var flipped = _.flip(function() {
  return _.toArray(arguments);
});
flipped('a', 'b', 'c', 'd');
// => ['d', 'c', 'b', 'a']

_.memoize(func, [resolver])

Creates a function that memoizes the result of func. If resolver is provided, it determines the cache key for storing the result based on the arguments provided to the memoized function. By default, the first argument provided to the memoized function is used as the map cache key. The func is invoked with the this binding of the memoized function.

Note: The cache is exposed as the cache property on the memoized function. Its creation may be customized by replacing the _.memoize.Cache constructor with one whose instances implement the Map method interface of clear, delete, get, has, and set.

Since

0.1.0

Arguments

1. func (Function): The function to have its output memoized.
2. [resolver] (Function): The function to resolve the cache key.

Returns

(Function): Returns the new memoized function.

Example

var object = { 'a': 1, 'b': 2 };
var other = { 'c': 3, 'd': 4 };
var values = _.memoize(_.values);
values(object);
// => [1, 2]
values(other);
// => [3, 4]
object.a = 2;
values(object);
// => [1, 2]
// Modify the result cache.
values.cache.set(object, ['a', 'b']);
values(object);
// => ['a', 'b']
// Replace `_.memoize.Cache`.
_.memoize.Cache = WeakMap;

_.negate(predicate)

Creates a function that negates the result of the predicate func. The func predicate is invoked with the this binding and arguments of the created function.

Since

3.0.0

Arguments

1. predicate (Function): The predicate to negate.

Returns

(Function): Returns the new negated function.

Example

function isEven(n) {
  return n % 2 == 0;
}
_.filter([1, 2, 3, 4, 5, 6], _.negate(isEven));
// => [1, 3, 5]

_.once(func)

Creates a function that is restricted to invoking func once. Repeat calls to the function return the value of the first invocation. The func is invoked with the this binding and arguments of the created function.

Since

0.1.0

Arguments

1. func (Function): The function to restrict.

Returns

(Function): Returns the new restricted function.

Example

var initialize = _.once(createApplication);
initialize();
initialize();
// => `createApplication` is invoked once

_.overArgs(func, [transforms=[_.identity]])

Creates a function that invokes func with its arguments transformed.

Since

4.0.0

Arguments

1. func (Function): The function to wrap.
2. [transforms=[_.identity]] (…(Function|Function[])): The argument transforms.

Returns

(Function): Returns the new function.

Example

function doubled(n) {
  return n * 2;
}
function square(n) {
  return n * n;
}
var func = _.overArgs(function(x, y) {
  return [x, y];
}, [square, doubled]);
func(9, 3);
// => [81, 6]
func(10, 5);
// => [100, 10]

_.partial(func, [partials])

Creates a function that invokes func with partials prepended to the arguments it receives. This method is like _.bind except it does not alter the this binding.

The _.partial.placeholder value, which defaults to _ in monolithic builds, may be used as a placeholder for partially applied arguments.

Note: This method doesn’t set the “length” property of partially applied functions.

Since

0.2.0

Arguments

1. func (Function): The function to partially apply arguments to.
2. [partials] (…*): The arguments to be partially applied.

Returns

(Function): Returns the new partially applied function.

Example

function greet(greeting, name) {
  return greeting + ' ' + name;
}
var sayHelloTo = _.partial(greet, 'hello');
sayHelloTo('fred');
// => 'hello fred'
// Partially applied with placeholders.
var greetFred = _.partial(greet, _, 'fred');
greetFred('hi');
// => 'hi fred'

_.partialRight(func, [partials])

This method is like _.partial except that partially applied arguments are appended to the arguments it receives.

The _.partialRight.placeholder value, which defaults to _ in monolithic builds, may be used as a placeholder for partially applied arguments.

Note: This method doesn’t set the “length” property of partially applied functions.

Since

1.0.0

Arguments

1. func (Function): The function to partially apply arguments to.
2. [partials] (…*): The arguments to be partially applied.

Returns

(Function): Returns the new partially applied function.

Example

function greet(greeting, name) {
  return greeting + ' ' + name;
}
var greetFred = _.partialRight(greet, 'fred');
greetFred('hi');
// => 'hi fred'
// Partially applied with placeholders.
var sayHelloTo = _.partialRight(greet, 'hello', _);
sayHelloTo('fred');
// => 'hello fred'

_.rearg(func, indexes)

Creates a function that invokes func with arguments arranged according to the specified indexes where the argument value at the first index is provided as the first argument, the argument value at the second index is provided as the second argument, and so on.

Since

3.0.0

Arguments

1. func (Function): The function to rearrange arguments for.
2. indexes (…(number|number[])): The arranged argument indexes.

Returns

(Function): Returns the new function.

Example

var rearged = _.rearg(function(a, b, c) {
  return [a, b, c];
}, [2, 0, 1]);
rearged('b', 'c', 'a')
// => ['a', 'b', 'c']

_.rest(func, [start=func.length-1])

Creates a function that invokes func with the this binding of the created function and arguments from start and beyond provided as an array.

Note: This method is based on the rest parameter.

Since

4.0.0

Arguments

1. func (Function): The function to apply a rest parameter to.
2. [start=func.length-1] (number): The start position of the rest parameter.

Returns

(Function): Returns the new function.

Example

var say = _.rest(function(what, names) {
  return what + ' ' + _.initial(names).join(', ') +
    (_.size(names) > 1 ? ', & ' : '') + _.last(names);
});
say('hello', 'fred', 'barney', 'pebbles');
// => 'hello fred, barney, & pebbles'

_.spread(func, [start=0])

Creates a function that invokes func with the this binding of the create function and an array of arguments much like Function#apply.

Note: This method is based on the spread operator.

Since

3.2.0

Arguments

1. func (Function): The function to spread arguments over.
2. [start=0] (number): The start position of the spread.

Returns

(Function): Returns the new function.

Example

var say = _.spread(function(who, what) {
  return who + ' says ' + what;
});
say(['fred', 'hello']);
// => 'fred says hello'
var numbers = Promise.all([
  Promise.resolve(40),
  Promise.resolve(36)
]);
numbers.then(_.spread(function(x, y) {
  return x + y;
}));
// => a Promise of 76

_.throttle(func, [wait=0], [options={}])

Creates a throttled function that only invokes func at most once per every wait milliseconds. The throttled function comes with a cancel method to cancel delayed func invocations and a flush method to immediately invoke them. Provide options to indicate whether func should be invoked on the leading and/or trailing edge of the wait timeout. The func is invoked with the last arguments provided to the throttled function. Subsequent calls to the throttled function return the result of the last func invocation.

Note: If leading and trailing options are true, func is invoked on the trailing edge of the timeout only if the throttled function is invoked more than once during the wait timeout.

If wait is 0 and leading is false, func invocation is deferred until to the next tick, similar to setTimeout with a timeout of 0.

See David Corbacho’s article for details over the differences between _.throttle and _.debounce.

Since

0.1.0

Arguments

1. func (Function): The function to throttle.
2. [wait=0] (number): The number of milliseconds to throttle invocations to.
3. [options={}] (Object): The options object.
4. [options.leading=true] (boolean): Specify invoking on the leading edge of the timeout.
5. [options.trailing=true] (boolean): Specify invoking on the trailing edge of the timeout.

Returns

(Function): Returns the new throttled function.

Example

// Avoid excessively updating the position while scrolling.
jQuery(window).on('scroll', _.throttle(updatePosition, 100));
// Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.
var throttled = _.throttle(renewToken, 300000, { 'trailing': false });
jQuery(element).on('click', throttled);
// Cancel the trailing throttled invocation.
jQuery(window).on('popstate', throttled.cancel);

_.unary(func)

Creates a function that accepts up to one argument, ignoring any additional arguments.

Since

4.0.0

Arguments

1. func (Function): The function to cap arguments for.

Returns

(Function): Returns the new capped function.

Example

_.map(['6', '8', '10'], _.unary(parseInt));
// => [6, 8, 10]

_.wrap(value, [wrapper=identity])

Creates a function that provides value to wrapper as its first argument. Any additional arguments provided to the function are appended to those provided to the wrapper. The wrapper is invoked with the this binding of the created function.

Since

0.1.0

Arguments

1. value (*): The value to wrap.
2. [wrapper=identity] (Function): The wrapper function.

Returns

(Function): Returns the new function.

Example

var p = _.wrap(_.escape, function(func, text) {
  return '<p>' + func(text) + '</p>';
});
p('fred, barney, & pebbles');
// => '<p>fred, barney, &amp; pebbles</p>'