Underscore OOP Wrapper, all Underscore functions that take an object as the first parameter can be invoked through this function.
By default, Underscore uses ERB-style template delimiters, change the following template settings to use alternative delimiters.
Creates a version of the function that will only be run after first being called count times. Useful for grouping asynchronous responses, where you want to be sure that all the async calls have finished, before proceeding.
Number of times to be called before actually executing.
Function
Copy of fn
that will not execute until it is invoked count
times.
boolean
boolean
boolean
boolean
Bind a function to an object, meaning that whenever the function is called, the value of this will be the object. Optionally, bind arguments to the function to pre-fill them, also known as partial application.
The function to bind this
to object
.
The this
pointer whenever fn
is called.
Additional arguments to pass to fn
when called.
() => any
fn
with this
bound to object
.
Binds a number of methods on the object, specified by methodNames, to be run in the context of that object whenever they are invoked. Very handy for binding functions that are going to be used as event handlers, which would otherwise be invoked with a fairly useless this. If no methodNames are provided, all of the object's function properties will be bound to it.
The object to bind the methods methodName
to.
The methods to bind to object
, optional and if not provided all of object
's
methods are bound.
any
Returns a wrapped object. Calling methods on this object will continue to return wrapped objects until value() is used.
Object to chain.
Wrapped obj
.
Create a shallow-copied clone of the object. Any nested objects or arrays will be copied by reference, not duplicated.
Object to clone.
T
Copy of object
.
Array<TResult>
Array<TResult>
Returns a copy of the array with all falsy values removed. In JavaScript, false, null, 0, "", undefined and NaN are all falsy.
Array to compact.
Array<T>
Copy of array
without false values.
Returns the composition of a list of functions, where each function consumes the return value of the function that follows. In math terms, composing the functions f(), g(), and h() produces f(g(h())).
List of functions to compose.
Function
Composition of functions
.
Creates a function that returns the same value that is used as the argument of _.constant
Identity of this object.
() => T
Function that return value.
Returns true if the value is present in the list. Uses indexOf internally, if list is an Array.
Checks each element to see if value
is present.
The value to check for within list
.
boolean
True if value
is present in list
, otherwise false.
boolean
Sorts a list into groups and returns a count for the number of objects in each group. Similar to groupBy, but instead of returning a list of values, returns a count for the number of values in that group.
Group elements in this list and then count the number of elements in each group.
Group iterator for each element within list
, return the key to group the element by.
this
object in iterator
, optional.
An object with the group names as properties where each property contains the number of elements in that group.
Function name
Creates and returns a new debounced version of the passed function that will postpone its execution until after wait milliseconds have elapsed since the last time it was invoked. Useful for implementing behavior that should only happen after the input has stopped arriving. For example: rendering a preview of a Markdown comment, recalculating a layout after the window has stopped being resized, and so on.
Pass true for the immediate parameter to cause debounce to trigger the function on the leading instead of the trailing edge of the wait interval. Useful in circumstances like preventing accidental double -clicks on a "submit" button from firing a second time.
Function to debounce waitMS
ms.
The number of milliseconds to wait before fn
can be invoked again.
True if fn
should be invoked on the leading edge of waitMS
instead of the trailing edge.
Function
Debounced version of fn
that waits wait
ms when invoked.
Fill in null and undefined properties in object with values from the defaults objects, and return the object. As soon as the property is filled, further defaults will have no effect.
Fill this object with default values.
The default values to add to object
.
any
object
with added defaults
values.
Defers invoking the function until the current call stack has cleared, similar to using setTimeout with a delay of 0. Useful for performing expensive computations or HTML rendering in chunks without blocking the UI thread from updating. If you pass the optional arguments, they will be forwarded on to the function when it is invoked.
The function to defer.
Additional arguments to pass to fn
.
Much like setTimeout, invokes function after wait milliseconds. If you pass the optional arguments, they will be forwarded on to the function when it is invoked.
Function to delay waitMS
amount of ms.
The amount of milliseconds to delay fn
.
any
any
T
T
Similar to without, but returns the values from array that are not present in the other arrays.
Keeps values that are within others
.
The values to keep within array
.
Array<T>
Copy of array
with only others
values.
Array<T>
Iterates over a list of elements, yielding each in turn to an iterator function. The iterator is bound to the context object, if one is passed. Each invocation of iterator is called with three arguments: (element, index, list). If list is a JavaScript object, iterator's arguments will be (value, key, object). Delegates to the native forEach function if it exists.
Iterates over this list of elements.
Iterator function for each element list
.
'this' object in iterator
, optional.
Iterates over properties of this object.
Iterator function for each property on object
.
'this' object in iterator
, optional.
Escapes a string for insertion into HTML, replacing &, <, >, ", ', and / characters.
Raw string to escape.
string
str
HTML escaped.
Returns true if all of the values in the list pass the iterator truth test. Delegates to the native method every, if present.
Truth test against all elements within this list.
Trust test iterator function for each element in list
.
this
object in iterator
, optional.
boolean
True if all elements passed the truth test, otherwise false.
boolean
Copy all of the properties in the source objects over to the destination object, and return the destination object. It's in-order, so the last source will override properties of the same name in previous arguments.
Object to extend all the properties from sources
.
Extends destination
with all properties from these source objects.
any
destination
extended with all the properties from the sources
objects.
Looks through each value in the list, returning an array of all the values that pass a truth test (iterator). Delegates to the native filter method, if it exists.
Filter elements out of this list.
Filter iterator function for each element in list
.
this
object in iterator
, optional.
Array<T>
The filtered list of elements.
Array<T>
Looks through each value in the list, returning the first one that passes a truth test (iterator). The function returns as soon as it finds an acceptable element, and doesn't traverse the entire list.
Searches for a value in this list.
Search iterator function for each element in list
.
this
object in iterator
, optional.
T
The first acceptable found element in list
, if nothing is found undefined/null is returned.
T
Looks through the list and returns the first value that matches all of the key-value pairs listed in properties.
Search through this list's elements for the first object with all properties
.
Properties to look for on the elements within list
.
T
The first element in list
that has all properties
.
Returns the first element of an array. Passing n will return the first n elements of the array.
Retrieves the first element of this array.
T
Returns the first element of array
.
Return more than one element from array
.
Array<T>
Flattens a nested array (the nesting can be to any depth). If you pass shallow, the array will only be flattened a single level.
The array to flatten.
If true then only flatten one level, optional, default = false.
Array<any>
array
flattened.
TResult
TResult
Returns a sorted list of the names of every method in an object - that is to say, the name of every function property of the object.
Object to pluck all function property names from.
Array<string>
List of all the function names on object
.
Splits a collection into sets, grouped by the result of running each value through iterator. If iterator is a string instead of a function, groups by the property named by iterator on each of the values.
Groups this list.
Group iterator for each element within list
, return the key to group the element by.
this
object in iterator
, optional.
An object with the group names as properties where each property contains the grouped elements from list
.
Property on each object to group them by.
Does the object contain the given key? Identical to object.hasOwnProperty(key), but uses a safe reference to the hasOwnProperty function, in case it's been overridden accidentally.
Object to check for key
.
The key to check for on object
.
boolean
True if key
is a property on object
, otherwise false.
T
Array<T>
Returns the same value that is used as the argument. In math: f(x) = x This function looks useless, but is used throughout Underscore as a default iterator.
Identity of this object.
T
value
.
boolean
boolean
Given a list
, and an iterator
function that returns a key for each element in the list (or a property name),
returns an object with an index of each item. Just like _.groupBy, but for when you know your keys are unique.
Property on each object to index them by.
Returns the index at which value can be found in the array, or -1 if value is not present in the array. Uses the native indexOf function unless it's missing. 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.
The array to search for the index of value
.
The value to search for within array
.
True if the array is already sorted, optional, default = false.
number
The index of value
within array
.
number
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.
Retrieve all elements except the last n
.
Leaves this many elements behind, optional.
Array<T>
Returns everything but the last n
elements of array
.
TResult
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.
Array of arrays to compute the intersection of.
Array<T>
The intersection of elements within arrays
.
Returns a copy of the object where the keys have become the values and the values the keys. For this to work, all of your object's values should be unique and string serializable.
Object to invert key/value pairs.
any
An inverted key/value paired version of object
.
Calls the method named by methodName on each value in the list. Any extra arguments passed to invoke will be forwarded on to the method invocation.
The element's in this list will each have the method methodName
invoked.
The method's name to call on each element within list
.
Additional arguments to pass to the method methodName
.
any
Returns true if object is an Arguments object.
Check if this object is an Arguments object.
boolean
True if object
is an Arguments object, otherwise false.
Returns true if object is an Array.
Check if this object is an Array.
boolean
True if object
is an Array, otherwise false.
Returns true if object is either true or false.
Check if this object is a bool.
boolean
True if object
is a bool, otherwise false.
Returns true if object is a Date.
Check if this object is a Date.
boolean
True if object
is a Date, otherwise false.
Returns true if object is a DOM element.
Check if this object is a DOM element.
boolean
True if object
is a DOM element, otherwise false.
Returns true if object contains no values.
Check if this object has no properties or values.
boolean
True if object
is empty.
Performs an optimized deep comparison between the two objects, to determine if they should be considered equal.
Compare to other
.
Compare to object
.
boolean
True if object
is equal to other
.
Returns true if object is a finite Number.
Check if this object is a finite Number.
boolean
True if object
is a finite Number.
Returns true if object is a Function.
Check if this object is a Function.
boolean
True if object
is a Function, otherwise false.
Returns true if object is NaN. Note: this is not the same as the native isNaN function, which will also return true if the variable is undefined.
Check if this object is NaN.
boolean
True if object
is NaN, otherwise false.
Returns true if the value of object is null.
Check if this object is null.
boolean
True if object
is null, otherwise false.
Returns true if object is a Number (including NaN).
Check if this object is a Number.
boolean
True if object
is a Number, otherwise false.
Returns true if value is an Object. Note that JavaScript arrays and functions are objects, while (normal) strings and numbers are not.
Check if this object is an Object.
boolean
True of object
is an Object, otherwise false.
Returns true if object is a RegExp.
Check if this object is a RegExp.
boolean
True if object
is a RegExp, otherwise false.
Returns true if object is a String.
Check if this object is a String.
boolean
True if object
is a String, otherwise false.
Returns true if value is undefined.
boolean
True if object
is undefined, otherwise false.
Retrieve all the names of the object's properties.
Retrieve the key or property names from this object.
Array<string>
List of all the property names on object
.
Returns the last element of an array. Passing n will return the last n elements of the array.
Retrieves the last element of this array.
T
Returns the last element of array
.
Return more than one element from array
.
Array<T>
Returns the index of the last occurrence of value in the array, or -1 if value is not present. Uses the native lastIndexOf function if possible. Pass fromIndex to start your search at a given index.
The array to search for the last index of value
.
The value to search for within array
.
The starting index for the search, optional.
number
The index of the last occurrence of value
within array
.
Produces a new array of values by mapping each value in list through a transformation function (iterator). If the native map method exists, it will be used instead. If list is a JavaScript object, iterator's arguments will be (value, key, object).
Maps the elements of this array.
Map iterator function for each element in list
.
this
object in iterator
, optional.
Array<TResult>
The mapped array result.
Maps the properties of this object.
Map iterator function for each property on object
.
this
object in iterator
, optional.
Array<TResult>
The mapped object result.
Returns a predicate function that will tell you if a passed in object contains all of the key/value properties present in attrs.
Object with key values pair
Predicate function
Returns the maximum value in list.
Finds the maximum value in this list.
number
Maximum value in list
.
Returns the maximum value in list. If iterator is passed, it will be used on each value to generate the criterion by which the value is ranked.
Finds the maximum value in this list.
Compares each element in list
to find the maximum value.
this
object in iterator
, optional.
T
The maximum element within list
.
Memoizes a given function by caching the computed result. Useful for speeding up slow-running computations. If passed an optional hashFunction, it will be used to compute the hash key for storing the result, based on the arguments to the original function. The default hashFunction just uses the first argument to the memoized function as the key.
Computationally expensive function that will now memoized results.
Hash function for storing the result of fn
.
Function
Memoized version of fn
.
Array<string>
Returns the minimum value in list.
Finds the minimum value in this list.
number
Minimum value in list
.
Returns the minimum value in list. If iterator is passed, it will be used on each value to generate the criterion by which the value is ranked.
Finds the minimum value in this list.
Compares each element in list
to find the minimum value.
this
object in iterator
, optional.
T
The minimum element within list
.
Allows you to extend Underscore with your own utility functions. Pass a hash of {name: function} definitions to have your functions added to the Underscore object, as well as the OOP wrapper.
Mixin object containing key/function pairs to add to the Underscore object.
Give control of the "_" variable back to its previous owner. Returns a reference to the Underscore object.
any
Underscore object reference.
Returns an integer timestamp for the current time, using the fastest method available in the runtime. Useful for implementing timing/animation functions.
number
Converts arrays into objects. Pass either a single list of [key, value] pairs, or a list of keys, and a list of values.
TResult
An object containing the keys
as properties and values
as the property values.
Converts arrays into objects. Pass either a single list of [key, value] pairs, or a list of keys, and a list of values.
Array of [key, value] pairs.
TResult
An object containing the keys
as properties and values
as the property values.
TResult
Return a copy of the object, filtered to omit the blacklisted keys (or array of keys).
Object to strip unwanted key/value pairs.
The key/value pairs to remove on object
.
any
Copy of object
without the keys
properties.
any
Creates a version of the function that can only be called one time. Repeated calls to the modified function will have no effect, returning the value from the original call. Useful for initialization functions, instead of having to set a boolean flag and then check it later.
Function to only execute once.
Function
Copy of fn
that can only be invoked once.
Convert an object into a list of [key, value] pairs.
Convert this object to a list of [key, value] pairs.
Array<any[]>
List of [key, value] pairs on object
.
Partially apply a function by filling in any number of its arguments, without changing its dynamic this value. A close cousin of bind. You may pass _ in your list of arguments to specify an argument that should not be pre-filled, but left open to supply at call-time.
Function to partially fill in arguments.
The partial arguments.
Function
fn
with partially filled in arguments.
Split array into two arrays: one whose elements all satisfy predicate and one whose elements all do not satisfy predicate.
Array to split in two.
Filter iterator function for each element in array
.
this
object in iterator
, optional.
Array<T[]>
Array where Array[0] are the elements in array
that satisfies the predicate, and Array[1] the elements that did not.
Return a copy of the object, filtered to only have values for the whitelisted keys (or array of valid keys).
Object to strip unwanted key/value pairs.
any
Copy of object
with only the keys
properties.
A convenient version of what is perhaps the most common use-case for map: extracting a list of property values.
The list to pluck elements out of that have the property propertyName
.
The property to look for on each element within list
.
Array<any>
The list of elements within list
that have the property propertyName
.
Returns a function that will itself return the key property of any passed-in object.
Property of the object.
(object: Object) => any
Function which accept an object an returns the value of key in that object.
Returns a random integer between min and max, inclusive. If you only pass one argument, it will return a number between 0 and that number.
The maximum random number.
number
A random number between 0 and max
.
The minimum random number.
number
A random number between min
and max
.
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 to stop, incremented (or decremented) by step, exclusive.
Start here.
Stop here.
The number to count up by each iteration, optional, default = 1.
Array<number>
Array of numbers from start
to stop
with increments of step
.
Stop here.
Array<number>
Array of numbers from 0 to stop
with increments of 1.
Also known as inject and foldl, reduce boils down a list of values into a single value. Memo is the initial state of the reduction, and each successive step of it should be returned by iterator. The iterator is passed four arguments: the memo, then the value and index (or key) of the iteration, and finally a reference to the entire list.
Reduces the elements of this array.
Reduce iterator function for each element in list
.
Initial reduce state.
this
object in iterator
, optional.
TResult
Reduced object result.
The right-associative version of reduce. Delegates to the JavaScript 1.8 version of
reduceRight, if it exists. foldr
is not as useful in JavaScript as it would be in a
language with lazy evaluation.
Reduces the elements of this array.
Reduce iterator function for each element in list
.
Initial reduce state.
this
object in iterator
, optional.
TResult
Reduced object result.
Returns the values in list without the elements that the truth test (iterator) passes. The opposite of filter. Return all the elements for which a truth test fails.
Reject elements within this list.
Reject iterator function for each element in list
.
this
object in iterator
, optional.
Array<T>
The rejected list of elements.
Array<T>
Returns the rest of the elements in an array. Pass an index to return the values of the array from that index onward.
The array to retrieve all but the first index
elements.
The index to start retrieving elements forward from, optional, default = 1.
Array<T>
Returns the elements of array
from index
to the end of array
.
If the value of the named property is a function then invoke it; otherwise, return it.
Object to maybe invoke function property
on.
The function by name to invoke on object
.
any
The result of invoking the function property
on `object.
Produce a random sample from the list
. Pass a number to return n
random elements from the list. Otherwise a single random item will be returned.
List to sample.
Array<T>
Random sample of n
elements in list
.
T
Array<T>
Array<T>
Returns a shuffled copy of the list, using a version of the Fisher-Yates shuffle.
List to shuffle.
Array<T>
Shuffled copy of list
.
Return the number of values in the list.
Count the number of values/elements in this list.
number
Number of values in list
.
Returns true if any of the values in the list pass the iterator truth test. Short-circuits and stops traversing the list if a true element is found. Delegates to the native method some, if present.
Truth test against all elements within this list.
Trust test iterator function for each element in list
.
this
object in iterator
, optional.
boolean
True if any elements passed the truth test, otherwise false.
boolean
Returns a sorted copy of list, ranked in ascending order by the results of running each value through iterator. Iterator may also be the string name of the property to sort by (eg. length).
Sorts this list.
Sort iterator for each element within list
.
this
object in iterator
, optional.
Array<T>
A sorted copy of list
.
Sort iterator for each element within list
.
Array<T>
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 iterator is passed, it will be used to compute the sort ranking of each value, including the value you pass.
The sorted list.
The value to determine its index within list
.
Iterator to compute the sort ranking of each value, optional.
number
The index where value
should be inserted into list
.
Array<T>
T
Array<T>
Invokes interceptor with the object, and then returns object. The primary purpose of this method is to "tap into" a method chain, in order to perform operations on intermediate results within the chain.
Argument to interceptor
.
The function to modify object
before continuing the method chain.
T
Modified object
.
Compiles JavaScript templates into functions that can be evaluated for rendering. Useful for rendering complicated bits of HTML from JSON data sources. Template functions can both interpolate variables, using <%= ... %>, as well as execute arbitrary JavaScript code, with <% ... %>. If you wish to interpolate a value, and have it be HTML-escaped, use <%- ... %> When you evaluate a template function, pass in a data object that has properties corresponding to the template's free variables. If you're writing a one-off, you can pass the data object as the second parameter to template in order to render immediately instead of returning a template function. The settings argument should be a hash containing any _.templateSettings that should be overridden.
Underscore HTML template.
Data to use when compiling templateString
.
Settings to use while compiling.
(...data: any[]) => string
Returns the compiled Underscore HTML template.
Creates and returns a new, throttled version of the passed function, that, when invoked repeatedly, will only actually call the original function at most once per every wait milliseconds. Useful for rate-limiting events that occur faster than you can keep up with. By default, throttle will execute the function as soon as you call it for the first time, and, if you call it again any number of times during the wait period, as soon as that period is over. If you'd like to disable the leading-edge call, pass {leading: false}, and if you'd like to disable the execution on the trailing-edge, pass {trailing: false}.
Function to throttle waitMS
ms.
The number of milliseconds to wait before fn
can be invoked again.
Allows for disabling execution of the throttled function on either the leading or trailing edge.
Function
fn
with a throttle of wait
.
Invokes the given iterator function n times. Each invocation of iterator is called with an index argument
Number of times to invoke iterator
.
Function iterator to invoke n
times.
this
object in iterator
, optional.
Array<TResult>
Converts the list (anything that can be iterated over), into a real Array. Useful for transmuting the arguments object.
object to transform into an array.
Array<T>
list
as an array.
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.
Array of arrays to compute the union of.
Array<T>
The union of elements within arrays
.
Produces a duplicate-free version of the array, using === to test object equality. 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 iterator function.
Array to remove duplicates from.
True if array
is already sorted, optional, default = false.
Transform the elements of array
before comparisons for uniqueness.
'this' object in iterator
, optional.
Array<T>
Copy of array
where all elements are unique.
Array<T>
Array<T>
Array<T>
Generate a globally-unique id for client-side models or DOM elements that need one. If prefix is passed, the id will be appended to it. Without prefix, returns an integer.
A prefix string to start the unique ID with.
string
Unique string ID beginning with prefix
.
number
Extracts the value of a wrapped object.
Wrapped object to extract the value from.
TResult
Value of obj
.
Return all of the values of the object's properties.
Retrieve the values of all the properties on this object.
Array<any>
List of all the values on object
.
Looks through each value in the list, returning an array of all the values that contain all of the key-value pairs listed in properties.
List to match elements again properties
.
The properties to check for on each element within list
.
Array<T>
The elements within list
that contain the required properties
.
Returns a copy of the array with all instances of the values removed.
The array to remove values
from.
The values to remove from array
.
Array<T>
Copy of array
without values
.
Wraps the first function inside of the wrapper function, passing it as the first argument. This allows the wrapper to execute code before and after the function runs, adjust the arguments, and execute it conditionally.
Function to wrap.
The function that will wrap fn
.
Function
Wrapped version of `fn.
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. If you're working with a matrix of nested arrays, zip.apply can transpose the matrix in a similar fashion.
The arrays to merge/zip.
Array<any[]>
Zipped version of arrays
.
Array<any>