Mirrors/lodash
1
0
Fork 0
mirror of https://github.com/whoisclebs/lodash.git synced 2026-01-29 06:27:49 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
90e34e1a74490863c34a8b68183d0ed700b1e316
lodash/index.html
Jeremy Ashkenas 90e34e1a74 comment edits
2009-10-27 14:45:05 -04:00

692 lines
23 KiB
HTML
Raw Blame History

<!DOCTYPE HTML>
<html>
<head>
<title>Underscore.js</title>
<style>
body {
font-size: 16px;
line-height: 24px;
background: #f0f0e5;
color: #252519;
font-family: "Palatino Linotype", "Book Antiqua", Palatino, FreeSerif, serif;
}
div.container {
width: 720px;
margin: 50px 0 50px 50px;
}
p {
width: 550px;
}
#documentation p {
margin-bottom: 4px;
}
a, a:visited {
padding: 0 2px;
text-decoration: none;
background: #dadaba;
color: #252519;
}
a:active, a:hover {
color: #000;
background: #f0c095;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 40px;
}
b.method_name {
font-size: 18px;
}
table, tr, td {
margin: 0; padding: 0;
}
td {
padding: 2px 12px 2px 0;
}
code, pre, tt {
font-family: Monaco, Consolas, "Lucida Console", monospace;
font-size: 12px;
line-height: 18px;
color: #555529;
}
code {
margin-left: 20px;
}
pre {
font-size: 12px;
padding: 2px 0 2px 12px;
border-left: 6px solid #aaaa99;
margin: 0px 0 30px;
}
</style>
</head>
<body>
<div class="container">
<h1>Underscore.js</h1>
<p>
<a href="http://github.com/documentcloud/underscore/">Underscore</a> is a
utility-belt library for Javascript that provides a lot of the
functional programming support that you would expect in
<a href="http://prototypejs.org/api">Prototype.js</a>
(or <a href="http://www.ruby-doc.org/core/classes/Enumerable.html">Ruby</a>),
but without extending any of the built-in Javascript objects. It's the
tie to go along with <a href="http://docs.jquery.com">jQuery</a>'s tux.
</p>
<p>
Underscore provides 43-odd functions that support both the usual
functional suspects: <b>map</b>, <b>select</b>, <b>invoke</b> &mdash;
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
<a href="https://developer.mozilla.org/en/New_in_JavaScript_1.6">Javascript 1.6</a>
compliant browsers will use the
native implementations of <b>forEach</b>, <b>map</b>, <b>filter</b>,
<b>every</b>, <b>some</b> and <b>indexOf</b>.
</p>
<p>
Underscore includes a complete <a href="test/test.html">Test &amp; Benchmark Suite</a>
for your perusal.
</p>
<h2>Downloads</h2>
<p>
<table>
<tr>
<td><a href="underscore.js">Development Version</a></td>
<td><i>(16kb, Uncompressed Code)</i></td>
</tr>
<tr>
<td><a href="underscore-min.js">Production Version</a></td>
<td><i>(4kb, Packed and Gzipped)</i></td>
</tr>
</table>
</p>
<h2>Table of Contents</h2>
<p>
<b>Collections</b>
<br />
<span class="methods"><a href="#each">each</a>, <a href="#map">map</a>,
<a href="#inject">inject</a>, <a href="#detect">detect</a>, <a href="#select">select</a>, <a href="#reject">reject</a>, <a href="#all">all</a>,
<a href="#any">any</a>, <a href="#include">include</a>, <a href="#invoke">invoke</a>, <a href="#pluck">pluck</a>, <a href="#max">max</a>,
<a href="#min">min</a>, <a href="#sortBy">sortBy</a>, <a href="#sortedIndex">sortedIndex</a>, <a href="#toArray">toArray</a>,
<a href="#size">size</a></span>
</p>
<p>
<b>Arrays</b>
<br />
<span class="methods"><a href="#first">first</a>, <a href="#last">last</a>,
<a href="#compact">compact</a>, <a href="#flatten">flatten</a>, <a href="#without">without</a>, <a href="#uniq">uniq</a>,
<a href="#intersect">intersect</a>, <a href="#zip">zip</a>, <a href="#indexOf">indexOf</a></span>
</p>
<p>
<b>Functions</b>
<br />
<span class="methods"><a href="#bind">bind</a>, <a href="#bindAll">bindAll</a>, <a href="#delay">delay</a>,
<a href="#defer">defer</a>, <a href="#wrap">wrap</a></span>
</p>
<p>
<b>Objects</b>
<br />
<span class="methods"><a href="#keys">keys</a>, <a href="#values">values</a>,
<a href="#extend">extend</a>, <a href="#clone">clone</a>, <a href="#isEqual">isEqual</a>, <a href="#isElement">isElement</a>,
<a href="#isArray">isArray</a>, <a href="#isFunction">isFunction</a>, <a href="#isUndefined">isUndefined</a>
</span>
</p>
<p>
<b>Utility</b>
<br />
<span class="methods"><a href="#uniqueId">uniqueId</a>, <a href="#template">template</a></span>
</p>
<div id="documentation">
<h2>Collection Functions (Arrays or Objects)</h2>
<p id="each">
<b class="method_name">each</b><code>_.each(list, iterator, [context])</code>
<br />
Iterates over a <b>list</b> of elements, yielding each in turn to an <b>iterator</b>
function. The <b>iterator</b> is bound to the <b>context</b> object, if one is
passed. If <b>list</b> is a Javascript object, a pair with <b>key</b>
and <b>value</b> properties will be yielded. If the list has an <b>each</b>
method of its own, it will be used instead. Delegates to the native
<b>forEach</b> function if it exists.
</p>
<pre>
_.each([1, 2, 3], function(num){ alert(num); });
=&gt; alerts each number in turn...</pre>
<p id="map">
<b class="method_name">map</b><code>_.map(list, iterator, [context])</code>
<br />
Produces a new array of values by mapping each value in <b>list</b>
through a transformation function (<b>iterator</b>). If the native
<b>map</b> method exists, it will be used instead.
</p>
<pre>
_.map([1, 2, 3], function(num){ return num * 3 });
=&gt; [3, 6, 9]</pre>
<p id="inject">
<b class="method_name">inject</b><code>_.inject(list, memo, iterator, [context])</code>
<br />
Also known as <b>reduce</b> and <b>foldl</b>, <b>inject</b> reduces a
<b>list</b> of values into a single value. <b>Memo</b> is the initial state
of the reduction, and each successive step of it should be returned by
<b>iterator</b>.
</p>
<pre>
var sum = _.inject([1, 2, 3], 0, function(memo, num){ return memo + num });
=&gt; 6
</pre>
<p id="detect">
<b class="method_name">detect</b><code>_.detect(list, iterator, [context])</code>
<br />
Looks through each value in the <b>list</b>, returning the first one that
passes a truth test (<b>iterator</b>). The function returns as
soon as it finds the first acceptable element, and doesn't continue to
traverse the list.
</p>
<pre>
var even = _.detect([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
=&gt; 2
</pre>
<p id="select">
<b class="method_name">select</b><code>_.select(list, iterator, [context])</code>
<br />
Looks through each value in the <b>list</b>, returning an array of all
the values that pass a truth test (<b>iterator</b>). Delegates to the
native <b>filter</b> method, if it exists.
</p>
<pre>
var evens = _.select([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
=&gt; [2, 4, 6]
</pre>
<p id="reject">
<b class="method_name">reject</b><code>_.reject(list, iterator, [context])</code>
<br />
Returns the values in <b>list</b> without the elements that the truth
test (<b>iterator</b>) passes. The opposite of <b>select</b>.
</p>
<pre>
var odds = _.reject([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
=&gt; [1, 3, 5]
</pre>
<p id="all">
<b class="method_name">all</b><code>_.all(list, [iterator], [context])</code>
<br />
Returns <i>true</i> if all of the values in the <b>list</b> pass the <b>iterator</b>
truth test. If an <b>iterator</b> is not provided, the truthy value of
the element will be used instead. Delegates to the native method <b>every</b>, if
present.
</p>
<pre>
_.all([true, 1, null, 'yes']);
=&gt; false
</pre>
<p id="any">
<b class="method_name">any</b><code>_.any(list, [iterator], [context])</code>
<br />
Returns <i>true</i> if any of the values in the <b>list</b> pass the
<b>iterator</b> truth test. Short-circuits and stops traversing the list
if a true element is found. Delegates to the native method <b>some</b>,
if present.
</p>
<pre>
_.any([null, 0, 'yes', false]);
=&gt; true
</pre>
<p id="include">
<b class="method_name">include</b><code>_.include(list, value)</code>
<br />
Returns <i>true</i> if the <b>value</b> is present in the <b>list</b>, using
<i>===</i> to test equality. Uses <b>indexOf</b> internally, if <b>list</b>
is an Array.
</p>
<pre>
_.include([1, 2, 3], 3);
=&gt; true
</pre>
<p id="invoke">
<b class="method_name">invoke</b><code>_.invoke(list, methodName, [*arguments])</code>
<br />
Calls the method named by <b>methodName</b> on each value in the <b>list</b>.
Any extra arguments passed to <b>invoke</b> will be forwarded on to the
method invocation.
</p>
<pre>
_.invoke([[5, 1, 7], [3, 2, 1]], 'sort');
=&gt; [[1, 5, 7], [1, 2, 3]]
</pre>
<p id="pluck">
<b class="method_name">pluck</b><code>_.pluck(list, propertyName)</code>
<br />
An optimized version of what is perhaps the most common use-case for
<b>map</b>: returning a list of property values.
</p>
<pre>
var stooges = [{name : 'moe', age : 40}, {name : 'larry', age : 50}, {name : 'curly', age : 60}];
_.pluck(stooges, 'name');
=&gt; ["moe", "larry", "curly"]
</pre>
<p id="max">
<b class="method_name">max</b><code>_.max(list, [iterator], [context])</code>
<br />
Returns the maximum value in <b>list</b>. If <b>iterator</b> is passed,
it will be used on each value to generate the criterion by which the
value is ranked.
</p>
<pre>
var stooges = [{name : 'moe', age : 40}, {name : 'larry', age : 50}, {name : 'curly', age : 60}];
_.max(stooges, function(stooge){ return stooge.age; });
=&gt; {name : 'curly', age : 60};
</pre>
<p id="min">
<b class="method_name">min</b><code>_.min(list, [iterator], [context])</code>
<br />
Returns the minimum value in <b>list</b>. If <b>iterator</b> is passed,
it will be used on each value to generate the criterion by which the
value is ranked.
</p>
<pre>
var numbers = [10, 5, 100, 2, 1000];
_.min(numbers);
=&gt; 2
</pre>
<p id="sortBy">
<b class="method_name">sortBy</b><code>_.sortBy(list, iterator, [context])</code>
<br />
Returns a sorted <b>list</b>, ranked by the results of running each
value through <b>iterator</b>.
</p>
<pre>
_.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); });
=&gt; [5, 4, 6, 3, 1, 2]
</pre>
<p id="sortedIndex">
<b class="method_name">sortedIndex</b><code>_.sortedIndex(list, value, [iterator])</code>
<br />
Uses a binary search to determine the index at which the <b>value</b>
should be inserted into the <b>list</b> in order to maintain the <b>list</b>'s
sorted order. If an <b>iterator</b> is passed, it will be used to compute
the sort ranking of each value.
</p>
<pre>
_.sortedIndex([10, 20, 30, 40, 50], 35);
=&gt; 3
</pre>
<p id="toArray">
<b class="method_name">toArray</b><code>_.toArray(list)</code>
<br />
Converts the <b>list</b> (anything that can be iterated over), into a
real Array. Useful for transmuting the <b>arguments</b> object.
</p>
<pre>
(function(){ return _.toArray(arguments).slice(0); })(1, 2, 3);
=&gt; [1, 2, 3]
</pre>
<p id="size">
<b class="method_name">size</b><code>_.size(list)</code>
<br />
Return the number of values in the <b>list</b>.
</p>
<pre>
_.size({one : 1, two : 2, three : 3});
=&gt; 3
</pre>
<h2>Array Functions</h2>
<p id="first">
<b class="method_name">first</b><code>_.first(array)</code>
<br />
Convenience to return the first element of an <b>array</b> (identical to <tt>array[0]</tt>).
</p>
<pre>
_.first([3, 2, 1]);
=&gt; 3
</pre>
<p id="last">
<b class="method_name">last</b><code>_.last(array)</code>
<br />
Returns the last element of an <b>array</b>.
</p>
<pre>
_.last([3, 2, 1]);
=&gt; 1
</pre>
<p id="compact">
<b class="method_name">compact</b><code>_.compact(array)</code>
<br />
Returns a copy of the <b>array</b> with all falsy values removed.
In Javascript, <i>false</i>, <i>null</i>, <i>0</i>, <i>""</i>,
<i>undefined</i> and <i>NaN</i> are all falsy.
</p>
<pre>
_.compact([0, 1, false, 2, '', 3]);
=&gt; [1, 2, 3]
</pre>
<p id="flatten">
<b class="method_name">flatten</b><code>_.flatten(array)</code>
<br />
Flattens a nested <b>array</b> (the nesting can be to any depth).
</p>
<pre>
_.flatten([1, [2], [3, [[[4]]]]]);
=&gt; [1, 2, 3, 4];
</pre>
<p id="without">
<b class="method_name">without</b><code>_.without(array, [*values])</code>
<br />
Returns a copy of the <b>array</b> with all instances of the <b>values</b>
removed. <i>===</i> is used for the equality test.
</p>
<pre>
_.without([1, 2, 1, 0, 3, 1, 4], 0, 1);
=&gt; [2, 3, 4]
</pre>
<p id="uniq">
<b class="method_name">uniq</b><code>_.uniq(array, [isSorted])</code>
<br />
Produces a duplicate-free version of the <b>array</b>, using <i>===</i> to test
object equality. If you know in advance that the <b>array</b> is sorted,
passing <i>true</i> for <b>isSorted</b> will run a much faster algorithm.
</p>
<pre>
_.uniq([1, 2, 1, 3, 1, 4]);
=&gt; [1, 2, 3, 4]
</pre>
<p id="intersect">
<b class="method_name">intersect</b><code>_.intersect(*arrays)</code>
<br />
Computes the list of values that are the intersection of all the <b>arrays</b>.
Each value in the result is present in each of the <b>arrays</b>.
</p>
<pre>
_.intersect([1, 2, 3], [101, 2, 1, 10], [2, 1]);
=&gt; [1, 2]
</pre>
<p id="zip">
<b class="method_name">zip</b><code>_.zip(*arrays)</code>
<br />
Merges together the values of each of the <b>arrays</b> with the
values at the corresponding position. Useful when you have separate
data sources that are coordinated through matching array indexes.
</p>
<pre>
_.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
=&gt; [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]
</pre>
<p id="indexOf">
<b class="method_name">indexOf</b><code>_.indexOf(array, value)</code>
<br />
Returns the index at which <b>value</b> can be found in the <b>array</b>,
or <i>-1</i> if value is not present in the <b>array</b>. Uses the native
<b>indexOf</b> function unless it's missing.
</p>
<pre>
_.indexOf([1, 2, 3], 2);
=&gt; 1
</pre>
<h2>Function (uh, ahem) Functions</h2>
<p id="bind">
<b class="method_name">bind</b><code>_.bind(function, context, [*arguments])</code>
<br />
Bind a <b>function</b> to a <b>context</b> object, meaning that whenever
the function is called, the value of <i>this</i> will be the <b>context</b>.
Optionally, bind <b>arguments</b> to the <b>function</b> to pre-fill them,
also known as <b>currying</b>.
</p>
<pre>
var func = function(greeting){ return greeting + ': ' + this.name };
func = _.bind(func, {name : 'moe'}, 'hi');
func();
=&gt; 'hi: moe'
</pre>
<p id="bindAll">
<b class="method_name">bindAll</b><code>_.bindAll(*methodNames, context)</code>
<br />
Binds a number of methods on the <b>context</b> object, specified by
<b>methodNames</b>, 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
<i>this</i>.
</p>
<pre>
var buttonView = {
label : 'underscore',
onClick : function(){ alert('clicked: ' + this.label); },
onHover : function(){ console.log('hovering: ' + this.label); }
};
_.bindAll('onClick', 'onHover', buttonView);
jQuery('#underscore_button').bind('click', buttonView.onClick);
=&gt; When the button is clicked, this.label will have the correct value...
</pre>
<p id="delay">
<b class="method_name">delay</b><code>_.delay(function, wait, [*arguments])</code>
<br />
Much like <b>setTimeout</b>, invokes <b>function</b> after <b>wait</b>
milliseconds. If you pass the optional <b>arguments</b>, they will be
forwarded on to the <b>function</b> when it is invoked.
</p>
<pre>
var log = _.bind(console.log, console);
_.delay(log, 1000, 'logged later');
=&gt; 'logged later' // Appears after one second.
</pre>
<p id="defer">
<b class="method_name">defer</b><code>_.defer(function)</code>
<br />
Defers invoking the <b>function</b> until the current call stack has cleared,
similar to using <b>setTimeout</b> with a delay of 0. Useful for performing
expensive computations or HTML rendering in chunks without blocking the UI thread
from updating.
</p>
<pre>
_.defer(function(){ alert('deferred'); });
// Returns from the function before the alert runs.
</pre>
<p id="wrap">
<b class="method_name">wrap</b><code>_.wrap(function, wrapper)</code>
<br />
Wraps the first <b>function</b> inside of the <b>wrapper</b> function,
passing it as the first argument. This allows the <b>wrapper</b> to
execute code before and after the <b>function</b> runs, adjust the arguments,
and execute it conditionally.
</p>
<pre>
var hello = function(name) { return "hello: " + name; };
hello = _.wrap(hello, function(func) {
return "before, " + func("moe") + ", after";
});
hello();
=&gt; before, hello: moe, after
</pre>
<h2>Object Functions</h2>
<p id="keys">
<b class="method_name">keys</b><code>_.keys(object)</code>
<br />
Retrieve all the names of the <b>object</b>'s properties.
</p>
<pre>
_.keys({one : 1, two : 2, three : 3});
=&gt; ["one", "two", "three"]
</pre>
<p id="values">
<b class="method_name">values</b><code>_.values(object)</code>
<br />
Return all of the values of the <b>object</b>'s properties.
</p>
<pre>
_.values({one : 1, two : 2, three : 3});
=&gt; [1, 2, 3]
</pre>
<p id="extend">
<b class="method_name">extend</b><code>_.extend(destination, source)</code>
<br />
Copy all of the properties in the <b>source</b> object over to the
<b>destination</b> object.
</p>
<pre>
_.extend({name : 'moe'}, {age : 50});
=&gt; {name : 'moe', age : 50}
</pre>
<p id="clone">
<b class="method_name">clone</b><code>_.clone(object)</code>
<br />
Create a shallow-copied clone of the <b>object</b>. Any nested objects
or arrays will be copied by reference, not duplicated.
</p>
<pre>
_.clone({name : 'moe'});
=&gt; {name : 'moe'};
</pre>
<p id="isEqual">
<b class="method_name">isEqual</b><code>_.isEqual(object, other)</code>
<br />
Performs an optimized deep comparison between the two objects, to determine
if they should be considered equal.
</p>
<pre>
var moe = {name : 'moe', luckyNumbers : [13, 27, 34]};
var clone = {name : 'moe', luckyNumbers : [13, 27, 34]};
moe == clone;
=&gt; false
_.isEqual(moe, clone);
=&gt; true
</pre>
<p id="isElement">
<b class="method_name">isElement</b><code>_.isElement(object)</code>
<br />
Returns <i>true</i> if <b>object</b> is a DOM element.
</p>
<pre>
_.isElement(jQuery('body')[0]);
=&gt; true
</pre>
<p id="isArray">
<b class="method_name">isArray</b><code>_.isArray(object)</code>
<br />
Returns <i>true</i> if <b>object</b> is an Array.
</p>
<pre>
(function(){ return _.isArray(arguments); })();
=&gt; false
_.isArray([1,2,3]);
=&gt; true
</pre>
<p id="isFunction">
<b class="method_name">isFunction</b><code>_.isFunction(object)</code>
<br />
Returns <i>true</i> if <b>object</b> is a Function.
</p>
<pre>
_.isFunction(alert);
=&gt; true
</pre>
<p id="isUndefined">
<b class="method_name">isUndefined</b><code>_.isUndefined(variable)</code>
<br />
Returns <i>true</i> if <b>variable</b> is <i>undefined</i>.
</p>
<pre>
_.isUndefined(window.missingVariable);
=&gt; true
</pre>
<h2>Utility Functions</h2>
<p id="uniqueId">
<b class="method_name">uniqueId</b><code>_.uniqueId([prefix])</code>
<br />
Generate a globally-unique id for client-side models or DOM elements
that need one. If <b>prefix</b> is passed, the id will be appended to it.
</p>
<pre>
_.uniqueId('contact_');
=&gt; 'contact_104'
</pre>
<p id="template">
<b class="method_name">template</b><code>_.template(templateString, [context])</code>
<br />
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<br />
<i>&lt;%= &hellip; %&gt;</i>, as well as execute arbitrary Javascript code, with
<i>&lt;% &hellip; %&gt;</i>. When you evaluate a template function, pass in a
<b>context</b> object that has properties corresponding to the template's free
variables. If you're writing a one-off, you can pass the <b>context</b>
object as the second parameter to <b>template</b> in order to render
immediately instead of returning a template function.
</p>
<pre>
var compiled = _.template("hello: &lt;%= name %&gt;");
compiled({name : 'moe'});
=&gt; "hello: moe"
var list = "&lt;% _.each(people, function(name) { %&gt; &lt;li&gt;&lt;%= name %&gt;&lt;/li&gt; &lt;% }); %&gt;";
_.template(list, {people : ['moe', 'curly', 'larry']});
=&gt; "&lt;li&gt;moe&lt;/li&gt;&lt;li&gt;curly&lt;/li&gt;&lt;li&gt;larry&lt;/li&gt;"
</pre>
<p>
<i><b>Underscore</b> is a <a href="http://documentcloud.org/">DocumentCloud</a> production.</i>
</p>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink