Function methods

These methods create, constrain, or schedule functions: partial application, currying, throttling and debouncing, memoization, and composition. Wrapped functions preserve the this binding and arguments of the function you pass in unless the method documents otherwise.

_.after(n, func)

Available since v0.1.0.

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

Returns Function — Returns the new restricted function.

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

Available since v3.0.0.

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

Returns Function — Returns the new capped function.

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

_.before(n, func)

Available since v3.0.0.

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.

Returns Function — Returns the new restricted function.

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

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

Available since v0.1.0.

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.

Returns Function — Returns the new bound function.

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

Available since v0.10.0.

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.

Returns Function — Returns the new bound function.

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

Available since v2.0.0.

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.

Returns Function — Returns the new curried function.

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

Available since v3.0.0.

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.

Returns Function — Returns the new curried function.

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={}])

Available since v0.1.0.

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.

Returns Function — Returns the new debounced function.

// 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])

Available since v0.1.0.

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

Returns number — Returns the timer id.

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

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

Available since v0.1.0.

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

Returns number — Returns the timer id.

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

_.flip(func)

Available since v4.0.0.

Creates a function that invokes func with arguments reversed.

Returns Function — Returns the new flipped function.

var flipped = _.flip(function() {
  return _.toArray(arguments);
});

flipped('a', 'b', 'c', 'd');
// => ['d', 'c', 'b', 'a']

_.memoize(func, [resolver])

Available since v0.1.0.

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.

Returns Function — Returns the new memoized function.

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)

Available since v3.0.0.

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.

Returns Function — Returns the new negated function.

function isEven(n) {
  return n % 2 == 0;
}

_.filter([1, 2, 3, 4, 5, 6], _.negate(isEven));
// => [1, 3, 5]

_.once(func)

Available since v0.1.0.

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.

Returns Function — Returns the new restricted function.

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

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

Available since v4.0.0.

Creates a function that invokes func with its arguments transformed.

Returns Function — Returns the new function.

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

Available since v0.2.0.

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.

Returns Function — Returns the new partially applied function.

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

Available since v1.0.0.

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.

Returns Function — Returns the new partially applied function.

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)

Available since v3.0.0.

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.

Returns Function — Returns the new function.

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

Available since v4.0.0.

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.

Returns Function — Returns the new function.

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

Available since v3.2.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.

Returns Function — Returns the new function.

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={}])

Available since v0.1.0.

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.

Returns Function — Returns the new throttled function.

// 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)

Available since v4.0.0.

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

Returns Function — Returns the new capped function.

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

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

Available since v0.1.0.

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.

Returns Function — Returns the new function.

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

p('fred, barney, & pebbles');
// => '<p>fred, barney, &amp; pebbles</p>'