_.after(n, func)

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

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

  1. var saves = ['profile', 'settings'];
  3. var done = _.after(saves.length, function() {
  4.   console.log('done saving!');
  5. });
  7. _.forEach(saves, function(type) {
  8.   asyncSave({ 'type': type, 'complete': done });
  9. });
  10. // => logs 'done saving!' after the two async saves have completed

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

Creates a function that accepts up to n arguments ignoring any additional arguments.

Arguments

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

Returns

(Function): Returns the new function.

Example

  1. _.map(['6', '8', '10'], _.ary(parseInt, 1));
  2. // => [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.

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

  1. jQuery('#add').on('click', _.before(5, addContactToList));
  2. // => 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 prepends any additional _.bind arguments to those provided to the bound function.

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 does not set the “length” property of bound functions.

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

  1. var greet = function(greeting, punctuation) {
  2.   return greeting + ' ' + this.user + punctuation;
  3. };
  5. var object = { 'user': 'fred' };
  7. var bound = _.bind(greet, object, 'hi');
  8. bound('!');
  9. // => 'hi fred!'
  11. // using placeholders
  12. var bound = _.bind(greet, object, _, '!');
  13. bound('hi');
  14. // => 'hi fred!'

_.bindAll(object, [methodNames])

Binds methods of an object to the object itself, overwriting the existing method. Method names may be specified as individual arguments or as arrays of method names. If no method names are provided all enumerable function properties, own and inherited, of object are bound.

Note: This method does not set the “length” property of bound functions.

Arguments

  1. object (Object): The object to bind and assign the bound methods to.
  2. [methodNames] (…(string|string[]): The object method names to bind, specified as individual method names or arrays of method names.

Returns

(Object): Returns object.

Example

  1. var view = {
  2.   'label': 'docs',
  3.   'onClick': function() {
  4.     console.log('clicked ' + this.label);
  5.   }
  6. };
  8. _.bindAll(view);
  9. jQuery('#docs').on('click', view.onClick);
  10. // => logs 'clicked docs' when the element is clicked

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

Creates a function that invokes the method at object[key] and prepends any additional _.bindKey arguments to those provided to the bound function.

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.

Arguments

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

Returns

(Function): Returns the new bound function.

Example

  1. var object = {
  2.   'user': 'fred',
  3.   'greet': function(greeting, punctuation) {
  4.     return greeting + ' ' + this.user + punctuation;
  5.   }
  6. };
  8. var bound = _.bindKey(object, 'greet', 'hi');
  9. bound('!');
  10. // => 'hi fred!'
  12. object.greet = function(greeting, punctuation) {
  13.   return greeting + 'ya ' + this.user + punctuation;
  14. };
  16. bound('!');
  17. // => 'hiya fred!'
  19. // using placeholders
  20. var bound = _.bindKey(object, 'greet', _, '!');
  21. bound('hi');
  22. // => 'hiya fred!'

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

Creates a function that accepts one or more arguments of func that when called either invokes func returning its result, if all func arguments have been provided, or returns a function that accepts one or more of 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 does not set the “length” property of curried functions.

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

  1. var abc = function(a, b, c) {
  2.   return [a, b, c];
  3. };
  5. var curried = _.curry(abc);
  7. curried(1)(2)(3);
  8. // => [1, 2, 3]
  10. curried(1, 2)(3);
  11. // => [1, 2, 3]
  13. curried(1, 2, 3);
  14. // => [1, 2, 3]
  16. // using placeholders
  17. curried(1)(_, 3)(2);
  18. // => [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 does not set the “length” property of curried functions.

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

  1. var abc = function(a, b, c) {
  2.   return [a, b, c];
  3. };
  5. var curried = _.curryRight(abc);
  7. curried(3)(2)(1);
  8. // => [1, 2, 3]
  10. curried(2, 3)(1);
  11. // => [1, 2, 3]
  13. curried(1, 2, 3);
  14. // => [1, 2, 3]
  16. // using placeholders
  17. curried(3)(1, _)(2);
  18. // => [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 invocations. Provide an options object to indicate that func should be invoked on the leading and/or trailing edge of the wait timeout. 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 the debounced function is invoked more than once during the wait timeout.

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

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

  1. // avoid costly calculations while the window size is in flux
  2. jQuery(window).on('resize', _.debounce(calculateLayout, 150));
  4. // invoke `sendMail` when the click event is fired, debouncing subsequent calls
  5. jQuery('#postbox').on('click', _.debounce(sendMail, 300, {
  6.   'leading': true,
  7.   'trailing': false
  8. }));
  10. // ensure `batchLog` is invoked once after 1 second of debounced calls
  11. var source = new EventSource('/stream');
  12. jQuery(source).on('message', _.debounce(batchLog, 250, {
  13.   'maxWait': 1000
  14. }));
  16. // cancel a debounced call
  17. var todoChanges = _.debounce(batchLog, 1000);
  18. Object.observe(models.todo, todoChanges);
  20. Object.observe(models, function(changes) {
  21.   if (_.find(changes, { 'user': 'todo', 'type': 'delete'})) {
  22.     todoChanges.cancel();
  23.   }
  24. }, ['delete']);
  26. // ...at some point `models.todo` is changed
  27. models.todo.completed = true;
  29. // ...before 1 second has passed `models.todo` is deleted
  30. // which cancels the debounced `todoChanges` call
  31. delete models.todo;

_.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.

Arguments

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

Returns

(number): Returns the timer id.

Example

  1. _.defer(function(text) {
  2.   console.log(text);
  3. }, 'deferred');
  4. // logs 'deferred' after one or more milliseconds

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

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

Arguments

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

Returns

(number): Returns the timer id.

Example

  1. _.delay(function(text) {
  2.   console.log(text);
  3. }, 1000, 'later');
  4. // => logs 'later' after one second

_.flow([funcs])

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

Arguments

  1. [funcs] (…Function): Functions to invoke.

Returns

(Function): Returns the new function.

Example

  1. function square(n) {
  2.   return n * n;
  3. }
  5. var addSquare = _.flow(_.add, square);
  6. addSquare(1, 2);
  7. // => 9

_.flowRight([funcs])

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

Aliases

.backflow, .compose

Arguments

  1. [funcs] (…Function): Functions to invoke.

Returns

(Function): Returns the new function.

Example

  1. function square(n) {
  2.   return n * n;
  3. }
  5. var addSquare = _.flowRight(square, _.add);
  6. addSquare(1, 2);
  7. // => 9

_.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 coerced to a string and used as the 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 get, has, and set.

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 memoizing function.

Example

  1. var upperCase = _.memoize(function(string) {
  2.   return string.toUpperCase();
  3. });
  5. upperCase('fred');
  6. // => 'FRED'
  8. // modifying the result cache
  9. upperCase.cache.set('fred', 'BARNEY');
  10. upperCase('fred');
  11. // => 'BARNEY'
  13. // replacing `_.memoize.Cache`
  14. var object = { 'user': 'fred' };
  15. var other = { 'user': 'barney' };
  16. var identity = _.memoize(_.identity);
  18. identity(object);
  19. // => { 'user': 'fred' }
  20. identity(other);
  21. // => { 'user': 'fred' }
  23. _.memoize.Cache = WeakMap;
  24. var identity = _.memoize(_.identity);
  26. identity(object);
  27. // => { 'user': 'fred' }
  28. identity(other);
  29. // => { 'user': 'barney' }

_.modArgs(func, [transforms])

Creates a function that runs each argument through a corresponding transform function.

Arguments

  1. func (Function): The function to wrap.
  2. [transforms] (…(Function|Function[]): The functions to transform arguments, specified as individual functions or arrays of functions.

Returns

(Function): Returns the new function.

Example

  1. function doubled(n) {
  2.   return n * 2;
  3. }
  5. function square(n) {
  6.   return n * n;
  7. }
  9. var modded = _.modArgs(function(x, y) {
  10.   return [x, y];
  11. }, square, doubled);
  13. modded(1, 2);
  14. // => [1, 4]
  16. modded(5, 10);
  17. // => [25, 20]

_.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.

Arguments

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

Returns

(Function): Returns the new function.

Example

  1. function isEven(n) {
  2.   return n % 2 == 0;
  3. }
  5. _.filter([1, 2, 3, 4, 5, 6], _.negate(isEven));
  6. // => [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 call. The func is invoked with the this binding and arguments of the created function.

Arguments

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

Returns

(Function): Returns the new restricted function.

Example

  1. var initialize = _.once(createApplication);
  2. initialize();
  3. initialize();
  4. // `initialize` invokes `createApplication` once

_.partial(func, [partials])

Creates a function that invokes func with partial arguments prepended to those provided to the new function. 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 does not set the “length” property of partially applied functions.

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

  1. var greet = function(greeting, name) {
  2.   return greeting + ' ' + name;
  3. };
  5. var sayHelloTo = _.partial(greet, 'hello');
  6. sayHelloTo('fred');
  7. // => 'hello fred'
  9. // using placeholders
  10. var greetFred = _.partial(greet, _, 'fred');
  11. greetFred('hi');
  12. // => 'hi fred'

_.partialRight(func, [partials])

This method is like _.partial except that partially applied arguments are appended to those provided to the new function.

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

Note: This method does not set the “length” property of partially applied functions.

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

  1. var greet = function(greeting, name) {
  2.   return greeting + ' ' + name;
  3. };
  5. var greetFred = _.partialRight(greet, 'fred');
  6. greetFred('hi');
  7. // => 'hi fred'
  9. // using placeholders
  10. var sayHelloTo = _.partialRight(greet, 'hello', _);
  11. sayHelloTo('fred');
  12. // => '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.

Arguments

  1. func (Function): The function to rearrange arguments for.
  2. indexes (…(number|number[]): The arranged argument indexes, specified as individual indexes or arrays of indexes.

Returns

(Function): Returns the new function.

Example

  1. var rearged = _.rearg(function(a, b, c) {
  2.   return [a, b, c];
  3. }, 2, 0, 1);
  5. rearged('b', 'c', 'a')
  6. // => ['a', 'b', 'c']
  8. var map = _.rearg(_.map, [1, 0]);
  9. map(function(n) {
  10.   return n * 3;
  11. }, [1, 2, 3]);
  12. // => [3, 6, 9]

_.restParam(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.

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

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

_.spread(func)

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

Note: This method is based on the spread operator.

Arguments

  1. func (Function): The function to spread arguments over.

Returns

(Function): Returns the new function.

Example

  1. var say = _.spread(function(who, what) {
  2.   return who + ' says ' + what;
  3. });
  5. say(['fred', 'hello']);
  6. // => 'fred says hello'
  8. // with a Promise
  9. var numbers = Promise.all([
  10.   Promise.resolve(40),
  11.   Promise.resolve(36)
  12. ]);
  14. numbers.then(_.spread(function(x, y) {
  15.   return x + y;
  16. }));
  17. // => 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 invocations. Provide an options object to indicate that func should be invoked on the leading and/or trailing edge of the wait timeout. Subsequent calls to the throttled function return the result of the last func call.

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

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

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

  1. // avoid excessively updating the position while scrolling
  2. jQuery(window).on('scroll', _.throttle(updatePosition, 100));
  4. // invoke `renewToken` when the click event is fired, but not more than once every 5 minutes
  5. jQuery('.interactive').on('click', _.throttle(renewToken, 300000, {
  6.   'trailing': false
  7. }));
  9. // cancel a trailing throttled call
  10. jQuery(window).on('popstate', throttled.cancel);

_.wrap(value, wrapper)

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

Arguments

  1. value (*): The value to wrap.
  2. wrapper (Function): The wrapper function.

Returns

(Function): Returns the new function.

Example

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