Underscore.js
- +- Underscore is a + Underscore is a utility-belt library for JavaScript that provides a lot of the functional programming support that you would expect in - Prototype.js - (or Ruby), - but without extending any of the built-in JavaScript objects. It's the + Prototype.js + (or Ruby), + but without extending any of the built-in JavaScript objects. It's the tie to go along with jQuery's tux.
- +- Underscore provides 45-odd functions that support both the usual - functional suspects: map, select, invoke — - as well as more specialized helpers: function binding, javascript - templating, deep equality testing, and so on. It delegates to built-in - functions, if present, so - JavaScript 1.6 - compliant browsers will use the - native implementations of forEach, map, filter, + Underscore provides 45-odd functions that support both the usual + functional suspects: map, select, invoke — + as well as more specialized helpers: function binding, javascript + templating, deep equality testing, and so on. It delegates to built-in + functions, if present, so + JavaScript 1.6 + compliant browsers will use the + native implementations of forEach, map, filter, every, some and indexOf.
- +Underscore includes a complete Test & Benchmark Suite for your perusal.
- +- The unabridged source code is + The unabridged source code is available on GitHub.
- +Downloads (Right-click, and use "Save As")
- +
Object-Oriented and Functional Styles
- +- You can use Underscore in either an object-oriented or a functional style, - depending on your preference. The following two lines of code are + You can use Underscore in either an object-oriented or a functional style, + depending on your preference. The following two lines of code are identical ways to double a list of numbers.
- +
_.map([1, 2, 3], function(n){ return n * 2; });
_([1, 2, 3]).map(function(n){ return n * 2; });
Using the object-oriented style allows you to chain together methods. Calling - chain on a wrapped object will cause all future method calls to - return wrapped objects as well. When you've finished the computation, + chain on a wrapped object will cause all future method calls to + return wrapped objects as well. When you've finished the computation, use get to retrieve the final value. Here's an example of chaining - together a map/flatten/reduce, in order to get the word count of + together a map/flatten/reduce, in order to get the word count of every word in a song.
- +
var lyrics = [
{line : 1, words : "I'm a lumberjack and I'm okay"},
@@ -149,73 +149,73 @@ var lyrics = [
_(lyrics).chain()
.map(function(line) { return line.words.split(' '); })
.flatten()
- .reduce({}, function(counts, word) {
+ .reduce({}, function(counts, word) {
counts[word] = (counts[word] || 0) + 1;
return counts;
}).get();
=> {lumberjack : 2, all : 4, night : 2 ... }
-
+
Table of Contents
- +
Collections
-
- each, map,
- reduce, reduceRight,
- detect, select,
- reject, all,
- any, include,
- invoke, pluck,
- max, min,
- sortBy, sortedIndex,
+
+ each, map,
+ reduce, reduceRight,
+ detect, select,
+ reject, all,
+ any, include,
+ invoke, pluck,
+ max, min,
+ sortBy, sortedIndex,
toArray, size
Arrays
- first, last,
- compact, flatten, without, uniq,
+ first, last,
+ compact, flatten, without, uniq,
intersect, zip, indexOf,
lastIndexOf
Functions
- bind, bindAll, delay,
+ bind, bindAll, delay,
defer, wrap, compose
Objects
- keys, values,
- extend, clone,
- isEqual, isEmpty, isElement,
+ keys, values,
+ extend, clone,
+ isEqual, isEmpty, isElement,
isArray, isFunction, isUndefined
Utility
noConflict,
- identity, uniqueId,
- template
+ identity, breakLoop,
+ uniqueId, template
Collection Functions (Arrays or Objects)
- +
each_.each(list, iterator, [context])
Alias: forEach
@@ -224,19 +224,19 @@ _(lyrics).chain()
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, list). If the list has an each
- method of its own, it will be used instead. Delegates to the native
+ arguments will be (value, key, list). If the list has an each
+ method of its own, it will be used instead. Delegates to the native
forEach function if it exists.
_.each([1, 2, 3], function(num){ alert(num); });
=> alerts each number in turn...
-
+
map_.map(list, iterator, [context])
- Produces a new array of values by mapping each value in list
- through a transformation function (iterator). If the native
+ 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.
@@ -247,7 +247,7 @@ _.map([1, 2, 3], function(num){ return num * 3 });
reduce_.reduce(list, memo, iterator, [context])
Aliases: inject, foldl
- Also known as inject and foldl, reduce boils down a
+ 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.
@@ -261,7 +261,7 @@ var sum = _.reduce([1, 2, 3], 0, function(memo, num){ return memo + num });
reduceRight_.reduceRight(list, memo, iterator, [context])
Alias: foldr
- The right-associative version of reduce. Delegates to the
+ 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.
@@ -275,8 +275,8 @@ var flat = _.reduceRight(list, [], function(a, b) { return a.concat(b); });
detect_.detect(list, iterator, [context])
- Looks through each value in the list, returning the first one that
- passes a truth test (iterator). The function returns as
+ 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.
@@ -314,7 +314,7 @@ var odds = _.reject([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
Alias: every
Returns true if all of the values in the list pass the iterator
- truth test. If an iterator is not provided, the truthy value of
+ truth test. If an iterator is not provided, the truthy value of
the element will be used instead. Delegates to the native method every, if
present.
@@ -364,7 +364,7 @@ _.invoke([[5, 1, 7], [3, 2, 1]], 'sort');
pluck_.pluck(list, propertyName)
- An convenient version of what is perhaps the most common use-case for
+ An convenient version of what is perhaps the most common use-case for
map: extracting a list of property values.
@@ -443,9 +443,9 @@ _.sortedIndex([10, 20, 30, 40, 50], 35);
_.size({one : 1, two : 2, three : 3});
=> 3
-
+
Array Functions
-
+
first_.first(array)
@@ -469,8 +469,8 @@ _.last([3, 2, 1]);
compact_.compact(array)
- Returns a copy of the array with all falsy values removed.
- In JavaScript, false, null, 0, "",
+ Returns a copy of the array with all falsy values removed.
+ In JavaScript, false, null, 0, "",
undefined and NaN are all falsy.
@@ -537,7 +537,7 @@ _.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
indexOf_.indexOf(array, value)
- Returns the index at which value can be found in the array,
+ 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.
@@ -549,8 +549,8 @@ _.indexOf([1, 2, 3], 2);
lastIndexOf_.lastIndexOf(array, value)
- Returns the index of the last occurrence of value in the array,
- or -1 if value is not present. Uses the native lastIndexOf
+ 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.
@@ -566,7 +566,7 @@ _.lastIndexOf([1, 2, 3, 1, 2, 3], 2);
Bind a function to a context object, meaning that whenever
the function is called, the value of this will be the context.
Optionally, bind arguments to the function to pre-fill them,
- also known as currying.
+ also known as currying.
var func = function(greeting){ return greeting + ': ' + this.name };
@@ -578,15 +578,15 @@ func();
bindAll_.bindAll(*methodNames, context)
- Binds a number of methods on the context object, specified by
+ Binds a number of methods on the context 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
+ as event handlers, which would otherwise be invoked with a fairly useless
this.
var buttonView = {
- label : 'underscore',
+ label : 'underscore',
onClick : function(){ alert('clicked: ' + this.label); },
onHover : function(){ console.log('hovering: ' + this.label); }
};
@@ -624,8 +624,8 @@ _.defer(function(){ alert('deferred'); });
wrap_.wrap(function, wrapper)
- Wraps the first function inside of the wrapper function,
- passing it as the first argument. This allows the wrapper to
+ 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.
@@ -641,7 +641,7 @@ hello();
compose_.compose(*functions)
- Returns the composition of a list of functions, where each function
+ 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())).
@@ -679,7 +679,7 @@ _.values({one : 1, two : 2, three : 3});
extend_.extend(destination, source)
- Copy all of the properties in the source object over to the
+ Copy all of the properties in the source object over to the
destination object.
@@ -768,7 +768,7 @@ _.isUndefined(window.missingVariable);
Utility Functions
-
+
noConflict_.noConflict()
@@ -781,20 +781,34 @@ var underscore = _.noConflict();
identity_.identity(value)
- Returns the same value that is used as the argument. In math:
+ 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
+ This function looks useless, but is used throughout Underscore as
a default iterator.
var moe = {name : 'moe'};
moe === _.identity(moe);
-=> true
+=> true
+
+
+ breakLoop_.breakLoop()
+
+ Breaks out of the current loop iteration. Similar to the break
+ keyword in regular "for" loop, but works within an iterator function.
+
+
+var result = null;
+_.each([1, 2, 3], function(num) {
+ if ((result = num) == 2) _.breakLoop();
+});
+result;
+=> 2
uniqueId_.uniqueId([prefix])
- Generate a globally-unique id for client-side models or DOM elements
+ 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.
@@ -819,7 +833,7 @@ _.functions();
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
+ <%= … %>, as well as execute arbitrary JavaScript code, with
<% … %>. When you evaluate a template function, pass in a
context object that has properties corresponding to the template's free
variables. If you're writing a one-off, you can pass the context
@@ -834,10 +848,10 @@ compiled({name : 'moe'});
var list = "<% _.each(people, function(name) { %> <li><%= name %></li> <% }); %>";
_.template(list, {people : ['moe', 'curly', 'larry']});
=> "<li>moe</li><li>curly</li><li>larry</li>"
-
+
Chaining
-
+
chain_(obj).chain()
@@ -861,30 +875,30 @@ _([1, 2, 3]).get();
Change Log
-
+
0.4.0
- All Underscore functions can now be called in an object-oriented style,
+ All Underscore functions can now be called in an object-oriented style,
like so: _([1, 2, 3]).map(...);. Original patch provided by
- Marc-André Cournoyer.
+ Marc-André Cournoyer.
Wrapped objects can be chained through multiple
- method invocations. A functions method
+ method invocations. A functions method
was added, providing a sorted list of all the functions in Underscore.
-
+
0.3.3
Added the JavaScript 1.8 function reduceRight. Aliased it
as foldr, and aliased reduce as foldl.
-
+
0.3.2
- Now runs on stock Rhino
+ Now runs on stock Rhino
interpreters with: load("underscore.js").
Added identity as a utility function.
-
+
0.3.1
All iterators are now passed in the original collection as their third
@@ -892,29 +906,29 @@ _([1, 2, 3]).get();
objects is now called with (value, key, collection), for details
see _.each.
-
+
0.3.0
- Added Dmitry Baranovskiy's
- comprehensive optimizations, merged in
- Kris Kowal's patches to make Underscore
- CommonJS and
+ Added Dmitry Baranovskiy's
+ comprehensive optimizations, merged in
+ Kris Kowal's patches to make Underscore
+ CommonJS and
Narwhal compliant.
-
+
0.2.0
Added compose and lastIndexOf, renamed inject to
- reduce, added aliases for inject, filter,
+ reduce, added aliases for inject, filter,
every, some, and forEach.
-
+
0.1.1
- Added noConflict, so that the "Underscore" object can be assigned to
+ Added noConflict, so that the "Underscore" object can be assigned to
other variables.
-
+
0.1.0
Initial release of Underscore.js.
@@ -925,9 +939,9 @@ _([1, 2, 3]).get();
-
+