Context Navigation

index.html

Last change on this file was 484, checked in by hendrikvanantwerpen, 11 years ago
Commit node_modules, to make checkouts and builds more deterministic.
File size: 87.9 KB

Line
1	<!DOCTYPE HTML>
2	<html>
3	<head>
4	<meta http-equiv="content-type" content="text/html;charset=UTF-8" />
5	<meta http-equiv="X-UA-Compatible" content="chrome=1" />
6	<meta name="viewport" content="width=device-width" />
7	<link rel="canonical" href="http://underscorejs.org" />
8	<link rel="shortcut icon" href="favicon.ico" type="image/x-icon" />
9	<title>Underscore.js</title>
10	<style>
11	body {
12	font-size: 14px;
13	line-height: 22px;
14	background: #f4f4f4 url(docs/images/background.png);
15	color: #000;
16	font-family: Helvetica Neue, Helvetica, Arial;
17	}
18	.interface {
19	font-family: "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, sans-serif !important;
20	}
21	div#sidebar {
22	background: #fff;
23	position: fixed;
24	top: 0; left: 0; bottom: 0;
25	width: 200px;
26	overflow-y: auto;
27	overflow-x: hidden;
28	-webkit-overflow-scrolling: touch;
29	padding: 15px 0 30px 30px;
30	border-right: 1px solid #bbb;
31	box-shadow: 0 0 20px #ccc; -webkit-box-shadow: 0 0 20px #ccc; -moz-box-shadow: 0 0 20px #ccc;
32	}
33	a.toc_title, a.toc_title:visited {
34	display: block;
35	color: black;
36	font-weight: bold;
37	margin-top: 15px;
38	}
39	a.toc_title:hover {
40	text-decoration: underline;
41	}
42	#sidebar .version {
43	font-size: 10px;
44	font-weight: normal;
45	}
46	ul.toc_section {
47	font-size: 11px;
48	line-height: 14px;
49	margin: 5px 0 0 0;
50	padding-left: 0px;
51	list-style-type: none;
52	font-family: Lucida Grande;
53	}
54	.toc_section li {
55	cursor: pointer;
56	margin: 0 0 3px 0;
57	}
58	.toc_section li a {
59	text-decoration: none;
60	color: black;
61	}
62	.toc_section li a:hover {
63	text-decoration: underline;
64	}
65	div.container {
66	width: 550px;
67	margin: 40px 0 50px 260px;
68	}
69	img#logo {
70	width: 396px;
71	height: 69px;
72	}
73	div.warning {
74	margin-top: 15px;
75	font: bold 11px Arial;
76	color: #770000;
77	}
78	p {
79	margin: 20px 0;
80	width: 550px;
81	}
82	a, a:visited {
83	color: #444;
84	}
85	a:active, a:hover {
86	color: #000;
87	}
88	h1, h2, h3, h4, h5, h6 {
89	padding-top: 20px;
90	}
91	h2 {
92	font-size: 20px;
93	}
94	b.header {
95	font-size: 16px;
96	line-height: 30px;
97	}
98	span.alias {
99	font-size: 14px;
100	font-style: italic;
101	margin-left: 20px;
102	}
103	table, tr, td {
104	margin: 0; padding: 0;
105	}
106	td {
107	padding: 2px 12px 2px 0;
108	}
109	table .rule {
110	height: 1px;
111	background: #ccc;
112	margin: 5px 0;
113	}
114	ul {
115	list-style-type: circle;
116	padding: 0 0 0 20px;
117	}
118	li {
119	width: 500px;
120	margin-bottom: 10px;
121	}
122	code, pre, tt {
123	font-family: Monaco, Consolas, "Lucida Console", monospace;
124	font-size: 12px;
125	line-height: 18px;
126	font-style: normal;
127	}
128	tt {
129	padding: 0px 3px;
130	background: #fff;
131	border: 1px solid #ddd;
132	zoom: 1;
133	}
134	code {
135	margin-left: 20px;
136	}
137	pre {
138	font-size: 12px;
139	padding: 2px 0 2px 15px;
140	border-left: 5px solid #bbb;
141	margin: 0px 0 30px;
142	}
143	@media only screen and (-webkit-min-device-pixel-ratio: 1.5) and (max-width: 640px),
144	only screen and (-o-min-device-pixel-ratio: 3/2) and (max-width: 640px),
145	only screen and (min-device-pixel-ratio: 1.5) and (max-width: 640px) {
146	img {
147	max-width: 100%;
148	}
149	div#sidebar {
150	-webkit-overflow-scrolling: initial;
151	position: relative;
152	width: 90%;
153	height: 120px;
154	left: 0;
155	top: -7px;
156	padding: 10px 0 10px 30px;
157	border: 0;
158	}
159	img#logo {
160	width: auto;
161	height: auto;
162	}
163	div.container {
164	margin: 0;
165	width: 100%;
166	}
167	p, div.container ul {
168	max-width: 98%;
169	overflow-x: scroll;
170	}
171	pre {
172	overflow: scroll;
173	}
174	}
175	</style>
176	</head>
177	<body>
178
179	<div id="sidebar" class="interface">
180
181	<a class="toc_title" href="#">
182	Underscore.js <span class="version">(1.4.4)</span>
183	</a>
184	<ul class="toc_section">
185	<li>» <a href="http://github.com/documentcloud/underscore">GitHub Repository</a></li>
186	<li>» <a href="docs/underscore.html">Annotated Source</a></li>
187	</ul>
188
189	<a class="toc_title" href="#">
190	Introduction
191	</a>
192
193	<a class="toc_title" href="#collections">
194	Collections
195	</a>
196	<ul class="toc_section">
197	<li>- <a href="#each">each</a></li>
198	<li>- <a href="#map">map</a></li>
199	<li>- <a href="#reduce">reduce</a></li>
200	<li>- <a href="#reduceRight">reduceRight</a></li>
201	<li>- <a href="#find">find</a></li>
202	<li>- <a href="#filter">filter</a></li>
203	<li>- <a href="#where">where</a></li>
204	<li>- <a href="#findWhere">findWhere</a></li>
205	<li>- <a href="#reject">reject</a></li>
206	<li>- <a href="#every">every</a></li>
207	<li>- <a href="#some">some</a></li>
208	<li>- <a href="#contains">contains</a></li>
209	<li>- <a href="#invoke">invoke</a></li>
210	<li>- <a href="#pluck">pluck</a></li>
211	<li>- <a href="#max">max</a></li>
212	<li>- <a href="#min">min</a></li>
213	<li>- <a href="#sortBy">sortBy</a></li>
214	<li>- <a href="#groupBy">groupBy</a></li>
215	<li>- <a href="#countBy">countBy</a></li>
216	<li>- <a href="#shuffle">shuffle</a></li>
217	<li>- <a href="#toArray">toArray</a></li>
218	<li>- <a href="#size">size</a></li>
219	</ul>
220
221	<a class="toc_title" href="#arrays">
222	Arrays
223	</a>
224	<ul class="toc_section">
225	<li>- <a href="#first">first</a></li>
226	<li>- <a href="#initial">initial</a></li>
227	<li>- <a href="#last">last</a></li>
228	<li>- <a href="#rest">rest</a></li>
229	<li>- <a href="#compact">compact</a></li>
230	<li>- <a href="#flatten">flatten</a></li>
231	<li>- <a href="#without">without</a></li>
232	<li>- <a href="#union">union</a></li>
233	<li>- <a href="#intersection">intersection</a></li>
234	<li>- <a href="#difference">difference</a></li>
235	<li>- <a href="#uniq">uniq</a></li>
236	<li>- <a href="#zip">zip</a></li>
237	<li>- <a href="#object">object</a></li>
238	<li>- <a href="#indexOf">indexOf</a></li>
239	<li>- <a href="#lastIndexOf">lastIndexOf</a></li>
240	<li>- <a href="#sortedIndex">sortedIndex</a></li>
241	<li>- <a href="#range">range</a></li>
242	</ul>
243
244	<a class="toc_title" href="#functions">
245	Functions
246	</a>
247	<ul class="toc_section">
248	<li>- <a href="#bind">bind</a></li>
249	<li>- <a href="#bindAll">bindAll</a></li>
250	<li>- <a href="#partial">partial</a></li>
251	<li>- <a href="#memoize">memoize</a></li>
252	<li>- <a href="#delay">delay</a></li>
253	<li>- <a href="#defer">defer</a></li>
254	<li>- <a href="#throttle">throttle</a></li>
255	<li>- <a href="#debounce">debounce</a></li>
256	<li>- <a href="#once">once</a></li>
257	<li>- <a href="#after">after</a></li>
258	<li>- <a href="#wrap">wrap</a></li>
259	<li>- <a href="#compose">compose</a></li>
260	</ul>
261
262	<a class="toc_title" href="#objects">
263	Objects
264	</a>
265	<ul class="toc_section">
266	<li>- <a href="#keys">keys</a></li>
267	<li>- <a href="#values">values</a></li>
268	<li>- <a href="#pairs">pairs</a></li>
269	<li>- <a href="#invert">invert</a></li>
270	<li>- <a href="#object-functions">functions</a></li>
271	<li>- <a href="#extend">extend</a></li>
272	<li>- <a href="#pick">pick</a></li>
273	<li>- <a href="#omit">omit</a></li>
274	<li>- <a href="#defaults">defaults</a></li>
275	<li>- <a href="#clone">clone</a></li>
276	<li>- <a href="#tap">tap</a></li>
277	<li>- <a href="#has">has</a></li>
278	<li>- <a href="#isEqual">isEqual</a></li>
279	<li>- <a href="#isEmpty">isEmpty</a></li>
280	<li>- <a href="#isElement">isElement</a></li>
281	<li>- <a href="#isArray">isArray</a></li>
282	<li>- <a href="#isObject">isObject</a></li>
283	<li>- <a href="#isArguments">isArguments</a></li>
284	<li>- <a href="#isFunction">isFunction</a></li>
285	<li>- <a href="#isString">isString</a></li>
286	<li>- <a href="#isNumber">isNumber</a></li>
287	<li>- <a href="#isFinite">isFinite</a></li>
288	<li>- <a href="#isBoolean">isBoolean</a></li>
289	<li>- <a href="#isDate">isDate</a></li>
290	<li>- <a href="#isRegExp">isRegExp</a></li>
291	<li>- <a href="#isNaN">isNaN</a></li>
292	<li>- <a href="#isNull">isNull</a></li>
293	<li>- <a href="#isUndefined">isUndefined</a></li>
294	</ul>
295
296	<a class="toc_title" href="#utility">
297	Utility
298	</a>
299	<ul class="toc_section">
300	<li>- <a href="#noConflict">noConflict</a></li>
301	<li>- <a href="#identity">identity</a></li>
302	<li>- <a href="#times">times</a></li>
303	<li>- <a href="#random">random</a></li>
304	<li>- <a href="#mixin">mixin</a></li>
305	<li>- <a href="#uniqueId">uniqueId</a></li>
306	<li>- <a href="#escape">escape</a></li>
307	<li>- <a href="#unescape">unescape</a></li>
308	<li>- <a href="#result">result</a></li>
309	<li>- <a href="#template">template</a></li>
310	</ul>
311
312	<a class="toc_title" href="#chaining">
313	Chaining
314	</a>
315	<ul class="toc_section">
316	<li>- <a href="#chain">chain</a></li>
317	<li>- <a href="#value">value</a></li>
318	</ul>
319
320	<a class="toc_title" href="#links">
321	Links
322	</a>
323
324	<a class="toc_title" href="#changelog">
325	Change Log
326	</a>
327
328	</div>
329
330	<div class="container">
331
332	<p id="introduction">
333	<img id="logo" src="docs/images/underscore.png" alt="Underscore.js" />
334	</p>
335
336	<p>
337	<a href="http://github.com/documentcloud/underscore/">Underscore</a> is a
338	utility-belt library for JavaScript that provides a lot of the
339	functional programming support that you would expect in
340	<a href="http://prototypejs.org/doc/latest/">Prototype.js</a>
341	(or <a href="http://www.ruby-doc.org/core/classes/Enumerable.html">Ruby</a>),
342	but without extending any of the built-in JavaScript objects. It's the
343	tie to go along with <a href="http://docs.jquery.com">jQuery</a>'s tux,
344	and <a href="http://backbonejs.org">Backbone.js</a>'s suspenders.
345	</p>
346
347	<p>
348	Underscore provides 80-odd functions that support both the usual
349	functional suspects: <b>map</b>, <b>select</b>, <b>invoke</b> —
350	as well as more specialized helpers: function binding, javascript
351	templating, deep equality testing, and so on. It delegates to built-in
352	functions, if present, so modern browsers will use the
353	native implementations of <b>forEach</b>, <b>map</b>, <b>reduce</b>,
354	<b>filter</b>, <b>every</b>, <b>some</b> and <b>indexOf</b>.
355	</p>
356
357	<p>
358	A complete <a href="test/">Test & Benchmark Suite</a>
359	is included for your perusal.
360	</p>
361
362	<p>
363	You may also read through the <a href="docs/underscore.html">annotated source code</a>.
364	</p>
365
366	<p>
367	The project is
368	<a href="http://github.com/documentcloud/underscore/">hosted on GitHub</a>.
369	You can report bugs and discuss features on the
370	<a href="http://github.com/documentcloud/underscore/issues">issues page</a>,
371	on Freenode in the <tt>#documentcloud</tt> channel,
372	or send tweets to <a href="http://twitter.com/documentcloud">@documentcloud</a>.
373	</p>
374
375	<p>
376	<i>Underscore is an open-source component of <a href="http://documentcloud.org/">DocumentCloud</a>.</i>
377	</p>
378
379	<h2>Downloads <i style="padding-left: 12px; font-size:12px;">(Right-click, and use "Save As")</i></h2>
380
381	<table>
382	<tr>
383	<td><a href="underscore.js">Development Version (1.4.4)</a></td>
384	<td><i>40kb, Uncompressed with Plentiful Comments</i></td>
385	</tr>
386	<tr>
387	<td><a href="underscore-min.js">Production Version (1.4.4)</a></td>
388	<td><i>4kb, Minified and Gzipped</i></td>
389	</tr>
390	<tr>
391	<td colspan="2"><div class="rule"></div></td>
392	</tr>
393	<tr>
394	<td><a href="https://raw.github.com/documentcloud/underscore/master/underscore.js">Edge Version</a></td>
395	<td><i>Unreleased, current <tt>master</tt>, use at your own risk</i></td>
396	</tr>
397	</table>
398
399	<div id="documentation">
400
401	<h2 id="collections">Collection Functions (Arrays or Objects)</h2>
402
403	<p id="each">
404	<b class="header">each</b><code>_.each(list, iterator, [context])</code>
405	<span class="alias">Alias: <b>forEach</b></span>
406	<br />
407	Iterates over a <b>list</b> of elements, yielding each in turn to an <b>iterator</b>
408	function. The <b>iterator</b> is bound to the <b>context</b> object, if one is
409	passed. Each invocation of <b>iterator</b> is called with three arguments:
410	<tt>(element, index, list)</tt>. If <b>list</b> is a JavaScript object, <b>iterator</b>'s
411	arguments will be <tt>(value, key, list)</tt>. Delegates to the native
412	<b>forEach</b> function if it exists.
413	</p>
414	<pre>
415	_.each([1, 2, 3], alert);
416	=> alerts each number in turn...
417	_.each({one : 1, two : 2, three : 3}, alert);
418	=> alerts each number value in turn...</pre>
419
420	<p id="map">
421	<b class="header">map</b><code>_.map(list, iterator, [context])</code>
422	<span class="alias">Alias: <b>collect</b></span>
423	<br />
424	Produces a new array of values by mapping each value in <b>list</b>
425	through a transformation function (<b>iterator</b>). If the native <b>map</b> method
426	exists, it will be used instead. If <b>list</b> is a JavaScript object,
427	<b>iterator</b>'s arguments will be <tt>(value, key, list)</tt>.
428	</p>
429	<pre>
430	_.map([1, 2, 3], function(num){ return num * 3; });
431	=> [3, 6, 9]
432	_.map({one : 1, two : 2, three : 3}, function(num, key){ return num * 3; });
433	=> [3, 6, 9]</pre>
434
435	<p id="reduce">
436	<b class="header">reduce</b><code>_.reduce(list, iterator, memo, [context])</code>
437	<span class="alias">Aliases: <b>inject, foldl</b></span>
438	<br />
439	Also known as <b>inject</b> and <b>foldl</b>, <b>reduce</b> boils down a
440	<b>list</b> of values into a single value. <b>Memo</b> is the initial state
441	of the reduction, and each successive step of it should be returned by
442	<b>iterator</b>. The iterator is passed four arguments: the <tt>memo</tt>,
443	then the <tt>value</tt> and <tt>index</tt> (or key) of the iteration,
444	and finally a reference to the entire <tt>list</tt>.
445	</p>
446	<pre>
447	var sum = _.reduce([1, 2, 3], function(memo, num){ return memo + num; }, 0);
448	=> 6
449	</pre>
450
451	<p id="reduceRight">
452	<b class="header">reduceRight</b><code>_.reduceRight(list, iterator, memo, [context])</code>
453	<span class="alias">Alias: <b>foldr</b></span>
454	<br />
455	The right-associative version of <b>reduce</b>. Delegates to the
456	JavaScript 1.8 version of <b>reduceRight</b>, if it exists. <b>Foldr</b>
457	is not as useful in JavaScript as it would be in a language with lazy
458	evaluation.
459	</p>
460	<pre>
461	var list = [[0, 1], [2, 3], [4, 5]];
462	var flat = _.reduceRight(list, function(a, b) { return a.concat(b); }, []);
463	=> [4, 5, 2, 3, 0, 1]
464	</pre>
465
466	<p id="find">
467	<b class="header">find</b><code>_.find(list, iterator, [context])</code>
468	<span class="alias">Alias: <b>detect</b></span>
469	<br />
470	Looks through each value in the <b>list</b>, returning the first one that
471	passes a truth test (<b>iterator</b>). The function returns as
472	soon as it finds an acceptable element, and doesn't traverse the
473	entire list.
474	</p>
475	<pre>
476	var even = _.find([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
477	=> 2
478	</pre>
479
480	<p id="filter">
481	<b class="header">filter</b><code>_.filter(list, iterator, [context])</code>
482	<span class="alias">Alias: <b>select</b></span>
483	<br />
484	Looks through each value in the <b>list</b>, returning an array of all
485	the values that pass a truth test (<b>iterator</b>). Delegates to the
486	native <b>filter</b> method, if it exists.
487	</p>
488	<pre>
489	var evens = _.filter([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
490	=> [2, 4, 6]
491	</pre>
492
493	<p id="where">
494	<b class="header">where</b><code>_.where(list, properties)</code>
495	<br />
496	Looks through each value in the <b>list</b>, returning an array of all
497	the values that contain all of the key-value pairs listed in <b>properties</b>.
498	</p>
499	<pre>
500	_.where(listOfPlays, {author: "Shakespeare", year: 1611});
501	=> [{title: "Cymbeline", author: "Shakespeare", year: 1611},
502	{title: "The Tempest", author: "Shakespeare", year: 1611}]
503	</pre>
504
505	<p id="findWhere">
506	<b class="header">findWhere</b><code>_.findWhere(list, properties)</code>
507	<br />
508	Looks through the <b>list</b> and returns the <i>first</i> value that matches
509	all of the key-value pairs listed in <b>properties</b>.
510	</p>
511	<pre>
512	_.findWhere(publicServicePulitzers, {newsroom: "The New York Times"});
513	=> {year: 1918, newsroom: "The New York Times",
514	reason: "For its public service in publishing in full so many official reports,
515	documents and speeches by European statesmen relating to the progress and
516	conduct of the war."}
517	</pre>
518
519	<p id="reject">
520	<b class="header">reject</b><code>_.reject(list, iterator, [context])</code>
521	<br />
522	Returns the values in <b>list</b> without the elements that the truth
523	test (<b>iterator</b>) passes. The opposite of <b>filter</b>.
524	</p>
525	<pre>
526	var odds = _.reject([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
527	=> [1, 3, 5]
528	</pre>
529
530	<p id="every">
531	<b class="header">every</b><code>_.every(list, iterator, [context])</code>
532	<span class="alias">Alias: <b>all</b></span>
533	<br />
534	Returns <i>true</i> if all of the values in the <b>list</b> pass the <b>iterator</b>
535	truth test. Delegates to the native method <b>every</b>, if present.
536	</p>
537	<pre>
538	_.every([true, 1, null, 'yes'], _.identity);
539	=> false
540	</pre>
541
542	<p id="some">
543	<b class="header">some</b><code>_.some(list, [iterator], [context])</code>
544	<span class="alias">Alias: <b>any</b></span>
545	<br />
546	Returns <i>true</i> if any of the values in the <b>list</b> pass the
547	<b>iterator</b> truth test. Short-circuits and stops traversing the list
548	if a true element is found. Delegates to the native method <b>some</b>,
549	if present.
550	</p>
551	<pre>
552	_.some([null, 0, 'yes', false]);
553	=> true
554	</pre>
555
556	<p id="contains">
557	<b class="header">contains</b><code>_.contains(list, value)</code>
558	<span class="alias">Alias: <b>include</b></span>
559	<br />
560	Returns <i>true</i> if the <b>value</b> is present in the <b>list</b>.
561	Uses <b>indexOf</b> internally, if <b>list</b> is an Array.
562	</p>
563	<pre>
564	_.contains([1, 2, 3], 3);
565	=> true
566	</pre>
567
568	<p id="invoke">
569	<b class="header">invoke</b><code>_.invoke(list, methodName, [*arguments])</code>
570	<br />
571	Calls the method named by <b>methodName</b> on each value in the <b>list</b>.
572	Any extra arguments passed to <b>invoke</b> will be forwarded on to the
573	method invocation.
574	</p>
575	<pre>
576	_.invoke([[5, 1, 7], [3, 2, 1]], 'sort');
577	=> [[1, 5, 7], [1, 2, 3]]
578	</pre>
579
580	<p id="pluck">
581	<b class="header">pluck</b><code>_.pluck(list, propertyName)</code>
582	<br />
583	A convenient version of what is perhaps the most common use-case for
584	<b>map</b>: extracting a list of property values.
585	</p>
586	<pre>
587	var stooges = [{name : 'moe', age : 40}, {name : 'larry', age : 50}, {name : 'curly', age : 60}];
588	_.pluck(stooges, 'name');
589	=> ["moe", "larry", "curly"]
590	</pre>
591
592	<p id="max">
593	<b class="header">max</b><code>_.max(list, [iterator], [context])</code>
594	<br />
595	Returns the maximum value in <b>list</b>. If <b>iterator</b> is passed,
596	it will be used on each value to generate the criterion by which the
597	value is ranked.
598	</p>
599	<pre>
600	var stooges = [{name : 'moe', age : 40}, {name : 'larry', age : 50}, {name : 'curly', age : 60}];
601	_.max(stooges, function(stooge){ return stooge.age; });
602	=> {name : 'curly', age : 60};
603	</pre>
604
605	<p id="min">
606	<b class="header">min</b><code>_.min(list, [iterator], [context])</code>
607	<br />
608	Returns the minimum value in <b>list</b>. If <b>iterator</b> is passed,
609	it will be used on each value to generate the criterion by which the
610	value is ranked.
611	</p>
612	<pre>
613	var numbers = [10, 5, 100, 2, 1000];
614	_.min(numbers);
615	=> 2
616	</pre>
617
618	<p id="sortBy">
619	<b class="header">sortBy</b><code>_.sortBy(list, iterator, [context])</code>
620	<br />
621	Returns a sorted copy of <b>list</b>, ranked in ascending order by the
622	results of running each value through <b>iterator</b>. Iterator may
623	also be the string name of the property to sort by (eg. <tt>length</tt>).
624	</p>
625	<pre>
626	_.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); });
627	=> [5, 4, 6, 3, 1, 2]
628	</pre>
629
630	<p id="groupBy">
631	<b class="header">groupBy</b><code>_.groupBy(list, iterator, [context])</code>
632	<br />
633	Splits a collection into sets, grouped by the result of running each
634	value through <b>iterator</b>. If <b>iterator</b> is a string instead of
635	a function, groups by the property named by <b>iterator</b> on each of
636	the values.
637	</p>
638	<pre>
639	_.groupBy([1.3, 2.1, 2.4], function(num){ return Math.floor(num); });
640	=> {1: [1.3], 2: [2.1, 2.4]}
641
642	_.groupBy(['one', 'two', 'three'], 'length');
643	=> {3: ["one", "two"], 5: ["three"]}
644	</pre>
645
646	<p id="countBy">
647	<b class="header">countBy</b><code>_.countBy(list, iterator, [context])</code>
648	<br />
649	Sorts a list into groups and returns a count for the number of objects
650	in each group.
651	Similar to <tt>groupBy</tt>, but instead of returning a list of values,
652	returns a count for the number of values in that group.
653	</p>
654	<pre>
655	_.countBy([1, 2, 3, 4, 5], function(num) {
656	return num % 2 == 0 ? 'even' : 'odd';
657	});
658	=> {odd: 3, even: 2}
659	</pre>
660
661	<p id="shuffle">
662	<b class="header">shuffle</b><code>_.shuffle(list)</code>
663	<br />
664	Returns a shuffled copy of the <b>list</b>, using a version of the
665	<a href="http://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle</a>.
666	</p>
667	<pre>
668	_.shuffle([1, 2, 3, 4, 5, 6]);
669	=> [4, 1, 6, 3, 5, 2]
670	</pre>
671
672	<p id="toArray">
673	<b class="header">toArray</b><code>_.toArray(list)</code>
674	<br />
675	Converts the <b>list</b> (anything that can be iterated over), into a
676	real Array. Useful for transmuting the <b>arguments</b> object.
677	</p>
678	<pre>
679	(function(){ return _.toArray(arguments).slice(1); })(1, 2, 3, 4);
680	=> [2, 3, 4]
681	</pre>
682
683	<p id="size">
684	<b class="header">size</b><code>_.size(list)</code>
685	<br />
686	Return the number of values in the <b>list</b>.
687	</p>
688	<pre>
689	_.size({one : 1, two : 2, three : 3});
690	=> 3
691	</pre>
692
693	<h2 id="arrays">Array Functions</h2>
694
695	<p>
696	<i>
697	Note: All array functions will also work on the <b>arguments</b> object.
698	However, Underscore functions are not designed to work on "sparse" arrays.
699	</i>
700	</p>
701
702	<p id="first">
703	<b class="header">first</b><code>_.first(array, [n])</code>
704	<span class="alias">Alias: <b>head</b>, <b>take</b></span>
705	<br />
706	Returns the first element of an <b>array</b>. Passing <b>n</b> will
707	return the first <b>n</b> elements of the array.
708	</p>
709	<pre>
710	_.first([5, 4, 3, 2, 1]);
711	=> 5
712	</pre>
713
714	<p id="initial">
715	<b class="header">initial</b><code>_.initial(array, [n])</code>
716	<br />
717	Returns everything but the last entry of the array. Especially useful on
718	the arguments object. Pass <b>n</b> to exclude the last <b>n</b> elements
719	from the result.
720	</p>
721	<pre>
722	_.initial([5, 4, 3, 2, 1]);
723	=> [5, 4, 3, 2]
724	</pre>
725
726	<p id="last">
727	<b class="header">last</b><code>_.last(array, [n])</code>
728	<br />
729	Returns the last element of an <b>array</b>. Passing <b>n</b> will return
730	the last <b>n</b> elements of the array.
731	</p>
732	<pre>
733	_.last([5, 4, 3, 2, 1]);
734	=> 1
735	</pre>
736
737	<p id="rest">
738	<b class="header">rest</b><code>_.rest(array, [index])</code>
739	<span class="alias">Alias: <b>tail, drop</b></span>
740	<br />
741	Returns the <b>rest</b> of the elements in an array. Pass an <b>index</b>
742	to return the values of the array from that index onward.
743	</p>
744	<pre>
745	_.rest([5, 4, 3, 2, 1]);
746	=> [4, 3, 2, 1]
747	</pre>
748
749	<p id="compact">
750	<b class="header">compact</b><code>_.compact(array)</code>
751	<br />
752	Returns a copy of the <b>array</b> with all falsy values removed.
753	In JavaScript, <i>false</i>, <i>null</i>, <i>0</i>, <i>""</i>,
754	<i>undefined</i> and <i>NaN</i> are all falsy.
755	</p>
756	<pre>
757	_.compact([0, 1, false, 2, '', 3]);
758	=> [1, 2, 3]
759	</pre>
760
761	<p id="flatten">
762	<b class="header">flatten</b><code>_.flatten(array, [shallow])</code>
763	<br />
764	Flattens a nested <b>array</b> (the nesting can be to any depth). If you
765	pass <b>shallow</b>, the array will only be flattened a single level.
766	</p>
767	<pre>
768	_.flatten([1, [2], [3, [[4]]]]);
769	=> [1, 2, 3, 4];
770
771	_.flatten([1, [2], [3, [[4]]]], true);
772	=> [1, 2, 3, [[4]]];
773	</pre>
774
775	<p id="without">
776	<b class="header">without</b><code>_.without(array, [*values])</code>
777	<br />
778	Returns a copy of the <b>array</b> with all instances of the <b>values</b>
779	removed.
780	</p>
781	<pre>
782	_.without([1, 2, 1, 0, 3, 1, 4], 0, 1);
783	=> [2, 3, 4]
784	</pre>
785
786	<p id="union">
787	<b class="header">union</b><code>_.union(*arrays)</code>
788	<br />
789	Computes the union of the passed-in <b>arrays</b>: the list of unique items,
790	in order, that are present in one or more of the <b>arrays</b>.
791	</p>
792	<pre>
793	_.union([1, 2, 3], [101, 2, 1, 10], [2, 1]);
794	=> [1, 2, 3, 101, 10]
795	</pre>
796
797	<p id="intersection">
798	<b class="header">intersection</b><code>_.intersection(*arrays)</code>
799	<br />
800	Computes the list of values that are the intersection of all the <b>arrays</b>.
801	Each value in the result is present in each of the <b>arrays</b>.
802	</p>
803	<pre>
804	_.intersection([1, 2, 3], [101, 2, 1, 10], [2, 1]);
805	=> [1, 2]
806	</pre>
807
808	<p id="difference">
809	<b class="header">difference</b><code>_.difference(array, *others)</code>
810	<br />
811	Similar to <b>without</b>, but returns the values from <b>array</b> that
812	are not present in the <b>other</b> arrays.
813	</p>
814	<pre>
815	_.difference([1, 2, 3, 4, 5], [5, 2, 10]);
816	=> [1, 3, 4]
817	</pre>
818
819	<p id="uniq">
820	<b class="header">uniq</b><code>_.uniq(array, [isSorted], [iterator])</code>
821	<span class="alias">Alias: <b>unique</b></span>
822	<br />
823	Produces a duplicate-free version of the <b>array</b>, using <i>===</i> to test
824	object equality. If you know in advance that the <b>array</b> is sorted,
825	passing <i>true</i> for <b>isSorted</b> will run a much faster algorithm.
826	If you want to compute unique items based on a transformation, pass an
827	<b>iterator</b> function.
828	</p>
829	<pre>
830	_.uniq([1, 2, 1, 3, 1, 4]);
831	=> [1, 2, 3, 4]
832	</pre>
833
834	<p id="zip">
835	<b class="header">zip</b><code>_.zip(*arrays)</code>
836	<br />
837	Merges together the values of each of the <b>arrays</b> with the
838	values at the corresponding position. Useful when you have separate
839	data sources that are coordinated through matching array indexes.
840	If you're working with a matrix of nested arrays, <b>zip.apply</b>
841	can transpose the matrix in a similar fashion.
842	</p>
843	<pre>
844	_.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
845	=> [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]
846	</pre>
847
848	<p id="object">
849	<b class="header">object</b><code>_.object(list, [values])</code>
850	<br />
851	Converts arrays into objects. Pass either a single list of
852	<tt>[key, value]</tt> pairs, or a list of keys, and a list of values.
853	</p>
854	<pre>
855	_.object(['moe', 'larry', 'curly'], [30, 40, 50]);
856	=> {moe: 30, larry: 40, curly: 50}
857
858	_.object([['moe', 30], ['larry', 40], ['curly', 50]]);
859	=> {moe: 30, larry: 40, curly: 50}
860	</pre>
861
862	<p id="indexOf">
863	<b class="header">indexOf</b><code>_.indexOf(array, value, [isSorted])</code>
864	<br />
865	Returns the index at which <b>value</b> can be found in the <b>array</b>,
866	or <i>-1</i> if value is not present in the <b>array</b>. Uses the native
867	<b>indexOf</b> function unless it's missing. If you're working with a
868	large array, and you know that the array is already sorted, pass <tt>true</tt>
869	for <b>isSorted</b> to use a faster binary search ... or, pass a number as
870	the third argument in order to look for the first matching value in the
871	array after the given index.
872	</p>
873	<pre>
874	_.indexOf([1, 2, 3], 2);
875	=> 1
876	</pre>
877
878	<p id="lastIndexOf">
879	<b class="header">lastIndexOf</b><code>_.lastIndexOf(array, value, [fromIndex])</code>
880	<br />
881	Returns the index of the last occurrence of <b>value</b> in the <b>array</b>,
882	or <i>-1</i> if value is not present. Uses the native <b>lastIndexOf</b>
883	function if possible. Pass <b>fromIndex</b> to start your search at a
884	given index.
885	</p>
886	<pre>
887	_.lastIndexOf([1, 2, 3, 1, 2, 3], 2);
888	=> 4
889	</pre>
890
891	<p id="sortedIndex">
892	<b class="header">sortedIndex</b><code>_.sortedIndex(list, value, [iterator], [context])</code>
893	<br />
894	Uses a binary search to determine the index at which the <b>value</b>
895	<i>should</i> be inserted into the <b>list</b> in order to maintain the <b>list</b>'s
896	sorted order. If an <b>iterator</b> is passed, it will be used to compute
897	the sort ranking of each value, including the <b>value</b> you pass.
898	</p>
899	<pre>
900	_.sortedIndex([10, 20, 30, 40, 50], 35);
901	=> 3
902	</pre>
903
904	<p id="range">
905	<b class="header">range</b><code>_.range([start], stop, [step])</code>
906	<br />
907	A function to create flexibly-numbered lists of integers, handy for
908	<tt>each</tt> and <tt>map</tt> loops. <b>start</b>, if omitted, defaults
909	to <i>0</i>; <b>step</b> defaults to <i>1</i>. Returns a list of integers
910	from <b>start</b> to <b>stop</b>, incremented (or decremented) by <b>step</b>,
911	exclusive.
912	</p>
913	<pre>
914	_.range(10);
915	=> [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
916	_.range(1, 11);
917	=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
918	_.range(0, 30, 5);
919	=> [0, 5, 10, 15, 20, 25]
920	_.range(0, -10, -1);
921	=> [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
922	_.range(0);
923	=> []
924	</pre>
925
926	<h2 id="functions">Function (uh, ahem) Functions</h2>
927
928	<p id="bind">
929	<b class="header">bind</b><code>_.bind(function, object, [*arguments])</code>
930	<br />
931	Bind a <b>function</b> to an <b>object</b>, meaning that whenever
932	the function is called, the value of <i>this</i> will be the <b>object</b>.
933	Optionally, pass <b>arguments</b> to the <b>function</b> to pre-fill them,
934	also known as <b>partial application</b>.
935	</p>
936	<pre>
937	var func = function(greeting){ return greeting + ': ' + this.name };
938	func = _.bind(func, {name : 'moe'}, 'hi');
939	func();
940	=> 'hi: moe'
941	</pre>
942
943	<p id="bindAll">
944	<b class="header">bindAll</b><code>_.bindAll(object, [*methodNames])</code>
945	<br />
946	Binds a number of methods on the <b>object</b>, specified by
947	<b>methodNames</b>, to be run in the context of that object whenever they
948	are invoked. Very handy for binding functions that are going to be used
949	as event handlers, which would otherwise be invoked with a fairly useless
950	<i>this</i>. If no <b>methodNames</b> are provided, all of the object's
951	function properties will be bound to it.
952	</p>
953	<pre>
954	var buttonView = {
955	label : 'underscore',
956	onClick : function(){ alert('clicked: ' + this.label); },
957	onHover : function(){ console.log('hovering: ' + this.label); }
958	};
959	_.bindAll(buttonView);
960	jQuery('#underscore_button').bind('click', buttonView.onClick);
961	=> When the button is clicked, this.label will have the correct value...
962	</pre>
963
964	<p id="partial">
965	<b class="header">partial</b><code>_.partial(function, [*arguments])</code>
966	<br />
967	Partially apply a function by filling in any number of its arguments,
968	<i>without</i> changing its dynamic <tt>this</tt> value. A close cousin
969	of <a href="#bind">bind</a>.
970	</p>
971	<pre>
972	var add = function(a, b) { return a + b; };
973	add5 = _.partial(add, 5);
974	add5(10);
975	=> 15
976	</pre>
977
978	<p id="memoize">
979	<b class="header">memoize</b><code>_.memoize(function, [hashFunction])</code>
980	<br />
981	Memoizes a given <b>function</b> by caching the computed result. Useful
982	for speeding up slow-running computations. If passed an optional
983	<b>hashFunction</b>, it will be used to compute the hash key for storing
984	the result, based on the arguments to the original function. The default
985	<b>hashFunction</b> just uses the first argument to the memoized function
986	as the key.
987	</p>
988	<pre>
989	var fibonacci = _.memoize(function(n) {
990	return n < 2 ? n : fibonacci(n - 1) + fibonacci(n - 2);
991	});
992	</pre>
993
994	<p id="delay">
995	<b class="header">delay</b><code>_.delay(function, wait, [*arguments])</code>
996	<br />
997	Much like <b>setTimeout</b>, invokes <b>function</b> after <b>wait</b>
998	milliseconds. If you pass the optional <b>arguments</b>, they will be
999	forwarded on to the <b>function</b> when it is invoked.
1000	</p>
1001	<pre>
1002	var log = _.bind(console.log, console);
1003	_.delay(log, 1000, 'logged later');
1004	=> 'logged later' // Appears after one second.
1005	</pre>
1006
1007	<p id="defer">
1008	<b class="header">defer</b><code>_.defer(function, [*arguments])</code>
1009	<br />
1010	Defers invoking the <b>function</b> until the current call stack has cleared,
1011	similar to using <b>setTimeout</b> with a delay of 0. Useful for performing
1012	expensive computations or HTML rendering in chunks without blocking the UI thread
1013	from updating. If you pass the optional <b>arguments</b>, they will be
1014	forwarded on to the <b>function</b> when it is invoked.
1015	</p>
1016	<pre>
1017	_.defer(function(){ alert('deferred'); });
1018	// Returns from the function before the alert runs.
1019	</pre>
1020
1021	<p id="throttle">
1022	<b class="header">throttle</b><code>_.throttle(function, wait)</code>
1023	<br />
1024	Creates and returns a new, throttled version of the passed function,
1025	that, when invoked repeatedly, will only actually call the original function
1026	at most once per every <b>wait</b>
1027	milliseconds. Useful for rate-limiting events that occur faster than you
1028	can keep up with.
1029	</p>
1030	<pre>
1031	var throttled = _.throttle(updatePosition, 100);
1032	$(window).scroll(throttled);
1033	</pre>
1034
1035	<p id="debounce">
1036	<b class="header">debounce</b><code>_.debounce(function, wait, [immediate])</code>
1037	<br />
1038	Creates and returns a new debounced version of the passed function that
1039	will postpone its execution until after
1040	<b>wait</b> milliseconds have elapsed since the last time it
1041	was invoked. Useful for implementing behavior that should only happen
1042	<i>after</i> the input has stopped arriving. For example: rendering a
1043	preview of a Markdown comment, recalculating a layout after the window
1044	has stopped being resized, and so on.
1045	</p>
1046
1047	<p>
1048	Pass <tt>true</tt> for the <b>immediate</b> parameter to cause
1049	<b>debounce</b> to trigger the function on the leading instead of the
1050	trailing edge of the <b>wait</b> interval. Useful in circumstances like
1051	preventing accidental double-clicks on a "submit" button from firing a
1052	second time.
1053	</p>
1054
1055	<pre>
1056	var lazyLayout = _.debounce(calculateLayout, 300);
1057	$(window).resize(lazyLayout);
1058	</pre>
1059
1060	<p id="once">
1061	<b class="header">once</b><code>_.once(function)</code>
1062	<br />
1063	Creates a version of the function that can only be called one time.
1064	Repeated calls to the modified function will have no effect, returning
1065	the value from the original call. Useful for initialization functions,
1066	instead of having to set a boolean flag and then check it later.
1067	</p>
1068	<pre>
1069	var initialize = _.once(createApplication);
1070	initialize();
1071	initialize();
1072	// Application is only created once.
1073	</pre>
1074
1075	<p id="after">
1076	<b class="header">after</b><code>_.after(count, function)</code>
1077	<br />
1078	Creates a version of the function that will only be run after first
1079	being called <b>count</b> times. Useful for grouping asynchronous responses,
1080	where you want to be sure that all the async calls have finished, before
1081	proceeding.
1082	</p>
1083	<pre>
1084	var renderNotes = _.after(notes.length, render);
1085	_.each(notes, function(note) {
1086	note.asyncSave({success: renderNotes});
1087	});
1088	// renderNotes is run once, after all notes have saved.
1089	</pre>
1090
1091	<p id="wrap">
1092	<b class="header">wrap</b><code>_.wrap(function, wrapper)</code>
1093	<br />
1094	Wraps the first <b>function</b> inside of the <b>wrapper</b> function,
1095	passing it as the first argument. This allows the <b>wrapper</b> to
1096	execute code before and after the <b>function</b> runs, adjust the arguments,
1097	and execute it conditionally.
1098	</p>
1099	<pre>
1100	var hello = function(name) { return "hello: " + name; };
1101	hello = _.wrap(hello, function(func) {
1102	return "before, " + func("moe") + ", after";
1103	});
1104	hello();
1105	=> 'before, hello: moe, after'
1106	</pre>
1107
1108	<p id="compose">
1109	<b class="header">compose</b><code>_.compose(*functions)</code>
1110	<br />
1111	Returns the composition of a list of <b>functions</b>, where each function
1112	consumes the return value of the function that follows. In math terms,
1113	composing the functions <i>f()</i>, <i>g()</i>, and <i>h()</i> produces
1114	<i>f(g(h()))</i>.
1115	</p>
1116	<pre>
1117	var greet = function(name){ return "hi: " + name; };
1118	var exclaim = function(statement){ return statement + "!"; };
1119	var welcome = _.compose(exclaim, greet);
1120	welcome('moe');
1121	=> 'hi: moe!'
1122	</pre>
1123
1124	<h2 id="objects">Object Functions</h2>
1125
1126	<p id="keys">
1127	<b class="header">keys</b><code>_.keys(object)</code>
1128	<br />
1129	Retrieve all the names of the <b>object</b>'s properties.
1130	</p>
1131	<pre>
1132	_.keys({one : 1, two : 2, three : 3});
1133	=> ["one", "two", "three"]
1134	</pre>
1135
1136	<p id="values">
1137	<b class="header">values</b><code>_.values(object)</code>
1138	<br />
1139	Return all of the values of the <b>object</b>'s properties.
1140	</p>
1141	<pre>
1142	_.values({one : 1, two : 2, three : 3});
1143	=> [1, 2, 3]
1144	</pre>
1145
1146	<p id="pairs">
1147	<b class="header">pairs</b><code>_.pairs(object)</code>
1148	<br />
1149	Convert an object into a list of <tt>[key, value]</tt> pairs.
1150	</p>
1151	<pre>
1152	_.pairs({one: 1, two: 2, three: 3});
1153	=> [["one", 1], ["two", 2], ["three", 3]]
1154	</pre>
1155
1156	<p id="invert">
1157	<b class="header">invert</b><code>_.invert(object)</code>
1158	<br />
1159	Returns a copy of the <b>object</b> where the keys have become the values
1160	and the values the keys. For this to work, all of your object's values
1161	should be unique and string serializable.
1162	</p>
1163	<pre>
1164	_.invert({Moe: "Moses", Larry: "Louis", Curly: "Jerome"});
1165	=> {Moses: "Moe", Louis: "Larry", Jerome: "Curly"};
1166	</pre>
1167
1168	<p id="object-functions">
1169	<b class="header">functions</b><code>_.functions(object)</code>
1170	<span class="alias">Alias: <b>methods</b></span>
1171	<br />
1172	Returns a sorted list of the names of every method in an object —
1173	that is to say, the name of every function property of the object.
1174	</p>
1175	<pre>
1176	_.functions(_);
1177	=> ["all", "any", "bind", "bindAll", "clone", "compact", "compose" ...
1178	</pre>
1179
1180	<p id="extend">
1181	<b class="header">extend</b><code>_.extend(destination, *sources)</code>
1182	<br />
1183	Copy all of the properties in the <b>source</b> objects over to the
1184	<b>destination</b> object, and return the <b>destination</b> object.
1185	It's in-order, so the last source will override properties of the same
1186	name in previous arguments.
1187	</p>
1188	<pre>
1189	_.extend({name : 'moe'}, {age : 50});
1190	=> {name : 'moe', age : 50}
1191	</pre>
1192
1193	<p id="pick">
1194	<b class="header">pick</b><code>_.pick(object, *keys)</code>
1195	<br />
1196	Return a copy of the <b>object</b>, filtered to only have values for
1197	the whitelisted <b>keys</b> (or array of valid keys).
1198	</p>
1199	<pre>
1200	_.pick({name : 'moe', age: 50, userid : 'moe1'}, 'name', 'age');
1201	=> {name : 'moe', age : 50}
1202	</pre>
1203
1204	<p id="omit">
1205	<b class="header">omit</b><code>_.omit(object, *keys)</code>
1206	<br />
1207	Return a copy of the <b>object</b>, filtered to omit the blacklisted
1208	<b>keys</b> (or array of keys).
1209	</p>
1210	<pre>
1211	_.omit({name : 'moe', age : 50, userid : 'moe1'}, 'userid');
1212	=> {name : 'moe', age : 50}
1213	</pre>
1214
1215	<p id="defaults">
1216	<b class="header">defaults</b><code>_.defaults(object, *defaults)</code>
1217	<br />
1218	Fill in null and undefined properties in <b>object</b> with values from the
1219	<b>defaults</b> objects, and return the <b>object</b>. As soon as the
1220	property is filled, further defaults will have no effect.
1221	</p>
1222	<pre>
1223	var iceCream = {flavor : "chocolate"};
1224	_.defaults(iceCream, {flavor : "vanilla", sprinkles : "lots"});
1225	=> {flavor : "chocolate", sprinkles : "lots"}
1226	</pre>
1227
1228	<p id="clone">
1229	<b class="header">clone</b><code>_.clone(object)</code>
1230	<br />
1231	Create a shallow-copied clone of the <b>object</b>. Any nested objects
1232	or arrays will be copied by reference, not duplicated.
1233	</p>
1234	<pre>
1235	_.clone({name : 'moe'});
1236	=> {name : 'moe'};
1237	</pre>
1238
1239	<p id="tap">
1240	<b class="header">tap</b><code>_.tap(object, interceptor)</code>
1241	<br />
1242	Invokes <b>interceptor</b> with the <b>object</b>, and then returns <b>object</b>.
1243	The primary purpose of this method is to "tap into" a method chain, in order to perform operations on intermediate results within the chain.
1244	</p>
1245	<pre>
1246	_.chain([1,2,3,200])
1247	.filter(function(num) { return num % 2 == 0; })
1248	.tap(alert)
1249	.map(function(num) { return num * num })
1250	.value();
1251	=> // [2, 200] (alerted)
1252	=> [4, 40000]
1253	</pre>
1254
1255	<p id="has">
1256	<b class="header">has</b><code>_.has(object, key)</code>
1257	<br />
1258	Does the object contain the given key? Identical to
1259	<tt>object.hasOwnProperty(key)</tt>, but uses a safe reference to the
1260	<tt>hasOwnProperty</tt> function, in case it's been
1261	<a href="http://www.devthought.com/2012/01/18/an-object-is-not-a-hash/">overridden accidentally</a>.
1262	</p>
1263	<pre>
1264	_.has({a: 1, b: 2, c: 3}, "b");
1265	=> true
1266	</pre>
1267
1268	<p id="isEqual">
1269	<b class="header">isEqual</b><code>_.isEqual(object, other)</code>
1270	<br />
1271	Performs an optimized deep comparison between the two objects, to determine
1272	if they should be considered equal.
1273	</p>
1274	<pre>
1275	var moe = {name : 'moe', luckyNumbers : [13, 27, 34]};
1276	var clone = {name : 'moe', luckyNumbers : [13, 27, 34]};
1277	moe == clone;
1278	=> false
1279	_.isEqual(moe, clone);
1280	=> true
1281	</pre>
1282
1283	<p id="isEmpty">
1284	<b class="header">isEmpty</b><code>_.isEmpty(object)</code>
1285	<br />
1286	Returns <i>true</i> if <b>object</b> contains no values.
1287	</p>
1288	<pre>
1289	_.isEmpty([1, 2, 3]);
1290	=> false
1291	_.isEmpty({});
1292	=> true
1293	</pre>
1294
1295	<p id="isElement">
1296	<b class="header">isElement</b><code>_.isElement(object)</code>
1297	<br />
1298	Returns <i>true</i> if <b>object</b> is a DOM element.
1299	</p>
1300	<pre>
1301	_.isElement(jQuery('body')[0]);
1302	=> true
1303	</pre>
1304
1305	<p id="isArray">
1306	<b class="header">isArray</b><code>_.isArray(object)</code>
1307	<br />
1308	Returns <i>true</i> if <b>object</b> is an Array.
1309	</p>
1310	<pre>
1311	(function(){ return _.isArray(arguments); })();
1312	=> false
1313	_.isArray([1,2,3]);
1314	=> true
1315	</pre>
1316
1317	<p id="isObject">
1318	<b class="header">isObject</b><code>_.isObject(value)</code>
1319	<br />
1320	Returns <i>true</i> if <b>value</b> is an Object. Note that JavaScript
1321	arrays and functions are objects, while (normal) strings and numbers are not.
1322	</p>
1323	<pre>
1324	_.isObject({});
1325	=> true
1326	_.isObject(1);
1327	=> false
1328	</pre>
1329
1330	<p id="isArguments">
1331	<b class="header">isArguments</b><code>_.isArguments(object)</code>
1332	<br />
1333	Returns <i>true</i> if <b>object</b> is an Arguments object.
1334	</p>
1335	<pre>
1336	(function(){ return _.isArguments(arguments); })(1, 2, 3);
1337	=> true
1338	_.isArguments([1,2,3]);
1339	=> false
1340	</pre>
1341
1342	<p id="isFunction">
1343	<b class="header">isFunction</b><code>_.isFunction(object)</code>
1344	<br />
1345	Returns <i>true</i> if <b>object</b> is a Function.
1346	</p>
1347	<pre>
1348	_.isFunction(alert);
1349	=> true
1350	</pre>
1351
1352	<p id="isString">
1353	<b class="header">isString</b><code>_.isString(object)</code>
1354	<br />
1355	Returns <i>true</i> if <b>object</b> is a String.
1356	</p>
1357	<pre>
1358	_.isString("moe");
1359	=> true
1360	</pre>
1361
1362	<p id="isNumber">
1363	<b class="header">isNumber</b><code>_.isNumber(object)</code>
1364	<br />
1365	Returns <i>true</i> if <b>object</b> is a Number (including <tt>NaN</tt>).
1366	</p>
1367	<pre>
1368	_.isNumber(8.4 * 5);
1369	=> true
1370	</pre>
1371
1372	<p id="isFinite">
1373	<b class="header">isFinite</b><code>_.isFinite(object)</code>
1374	<br />
1375	Returns <i>true</i> if <b>object</b> is a finite Number.
1376	</p>
1377	<pre>
1378	_.isFinite(-101);
1379	=> true
1380
1381	_.isFinite(-Infinity);
1382	=> false
1383	</pre>
1384
1385	<p id="isBoolean">
1386	<b class="header">isBoolean</b><code>_.isBoolean(object)</code>
1387	<br />
1388	Returns <i>true</i> if <b>object</b> is either <i>true</i> or <i>false</i>.
1389	</p>
1390	<pre>
1391	_.isBoolean(null);
1392	=> false
1393	</pre>
1394
1395	<p id="isDate">
1396	<b class="header">isDate</b><code>_.isDate(object)</code>
1397	<br />
1398	Returns <i>true</i> if <b>object</b> is a Date.
1399	</p>
1400	<pre>
1401	_.isDate(new Date());
1402	=> true
1403	</pre>
1404
1405	<p id="isRegExp">
1406	<b class="header">isRegExp</b><code>_.isRegExp(object)</code>
1407	<br />
1408	Returns <i>true</i> if <b>object</b> is a RegExp.
1409	</p>
1410	<pre>
1411	_.isRegExp(/moe/);
1412	=> true
1413	</pre>
1414
1415	<p id="isNaN">
1416	<b class="header">isNaN</b><code>_.isNaN(object)</code>
1417	<br />
1418	Returns <i>true</i> if <b>object</b> is <i>NaN</i>.<br /> Note: this is not
1419	the same as the native <b>isNaN</b> function, which will also return
1420	true if the variable is <i>undefined</i>.
1421	</p>
1422	<pre>
1423	_.isNaN(NaN);
1424	=> true
1425	isNaN(undefined);
1426	=> true
1427	_.isNaN(undefined);
1428	=> false
1429	</pre>
1430
1431	<p id="isNull">
1432	<b class="header">isNull</b><code>_.isNull(object)</code>
1433	<br />
1434	Returns <i>true</i> if the value of <b>object</b> is <i>null</i>.
1435	</p>
1436	<pre>
1437	_.isNull(null);
1438	=> true
1439	_.isNull(undefined);
1440	=> false
1441	</pre>
1442
1443	<p id="isUndefined">
1444	<b class="header">isUndefined</b><code>_.isUndefined(value)</code>
1445	<br />
1446	Returns <i>true</i> if <b>value</b> is <i>undefined</i>.
1447	</p>
1448	<pre>
1449	_.isUndefined(window.missingVariable);
1450	=> true
1451	</pre>
1452
1453	<h2 id="utility">Utility Functions</h2>
1454
1455	<p id="noConflict">
1456	<b class="header">noConflict</b><code>_.noConflict()</code>
1457	<br />
1458	Give control of the "_" variable back to its previous owner. Returns
1459	a reference to the <b>Underscore</b> object.
1460	</p>
1461	<pre>
1462	var underscore = _.noConflict();</pre>
1463
1464	<p id="identity">
1465	<b class="header">identity</b><code>_.identity(value)</code>
1466	<br />
1467	Returns the same value that is used as the argument. In math:
1468	<tt>f(x) = x</tt><br />
1469	This function looks useless, but is used throughout Underscore as
1470	a default iterator.
1471	</p>
1472	<pre>
1473	var moe = {name : 'moe'};
1474	moe === _.identity(moe);
1475	=> true</pre>
1476
1477	<p id="times">
1478	<b class="header">times</b><code>_.times(n, iterator, [context])</code>
1479	<br />
1480	Invokes the given iterator function <b>n</b> times. Each invocation of
1481	<b>iterator</b> is called with an <tt>index</tt> argument.
1482	<br />
1483	<i>Note: this example uses the <a href="#chaining">chaining syntax</a></i>.
1484	</p>
1485	<pre>
1486	_(3).times(function(n){ genie.grantWishNumber(n); });</pre>
1487
1488	<p id="random">
1489	<b class="header">random</b><code>_.random(min, max)</code>
1490	<br />
1491	Returns a random integer between <b>min</b> and <b>max</b>, inclusive.
1492	If you only pass one argument, it will return a number between <tt>0</tt>
1493	and that number.
1494	</p>
1495	<pre>
1496	_.random(0, 100);
1497	=> 42</pre>
1498
1499	<p id="mixin">
1500	<b class="header">mixin</b><code>_.mixin(object)</code>
1501	<br />
1502	Allows you to extend Underscore with your own utility functions. Pass
1503	a hash of <tt>{name: function}</tt> definitions to have your functions
1504	added to the Underscore object, as well as the OOP wrapper.
1505	</p>
1506	<pre>
1507	_.mixin({
1508	capitalize : function(string) {
1509	return string.charAt(0).toUpperCase() + string.substring(1).toLowerCase();
1510	}
1511	});
1512	_("fabio").capitalize();
1513	=> "Fabio"
1514	</pre>
1515
1516	<p id="uniqueId">
1517	<b class="header">uniqueId</b><code>_.uniqueId([prefix])</code>
1518	<br />
1519	Generate a globally-unique id for client-side models or DOM elements
1520	that need one. If <b>prefix</b> is passed, the id will be appended to it.
1521	</p>
1522	<pre>
1523	_.uniqueId('contact_');
1524	=> 'contact_104'</pre>
1525
1526	<p id="escape">
1527	<b class="header">escape</b><code>_.escape(string)</code>
1528	<br />
1529	Escapes a string for insertion into HTML, replacing
1530	<tt>&</tt>, <tt><</tt>, <tt>></tt>, <tt>"</tt>, <tt>'</tt>, and <tt>/</tt> characters.
1531	</p>
1532	<pre>
1533	_.escape('Curly, Larry & Moe');
1534	=> "Curly, Larry &amp; Moe"</pre>
1535
1536	<p id="unescape">
1537	<b class="header">unescape</b><code>_.unescape(string)</code>
1538	<br />
1539	The opposite of <a href="#escape"><b>escape</b></a>, replaces
1540	<tt>&amp;</tt>, <tt>&lt;</tt>, <tt>&gt;</tt>,
1541	<tt>&quot;</tt>, <tt>&#x27;</tt>, and <tt>&#x2F;</tt>
1542	with their unescaped counterparts.
1543	</p>
1544	<pre>
1545	_.unescape('Curly, Larry &amp; Moe');
1546	=> "Curly, Larry & Moe"</pre>
1547
1548	<p id="result">
1549	<b class="header">result</b><code>_.result(object, property)</code>
1550	<br />
1551	If the value of the named property is a function then invoke it; otherwise, return it.
1552	</p>
1553	<pre>
1554	var object = {cheese: 'crumpets', stuff: function(){ return 'nonsense'; }};
1555	_.result(object, 'cheese');
1556	=> "crumpets"
1557	_.result(object, 'stuff');
1558	=> "nonsense"</pre>
1559
1560	<p id="template">
1561	<b class="header">template</b><code>_.template(templateString, [data], [settings])</code>
1562	<br />
1563	Compiles JavaScript templates into functions that can be evaluated
1564	for rendering. Useful for rendering complicated bits of HTML from JSON
1565	data sources. Template functions can both interpolate variables, using
1566	<tt><%= … %></tt>, as well as execute arbitrary JavaScript code, with
1567	<tt><% … %></tt>. If you wish to interpolate a value, and have
1568	it be HTML-escaped, use <tt><%- … %></tt> When you evaluate a template function, pass in a
1569	<b>data</b> object that has properties corresponding to the template's free
1570	variables. If you're writing a one-off, you can pass the <b>data</b>
1571	object as the second parameter to <b>template</b> in order to render
1572	immediately instead of returning a template function. The <b>settings</b> argument
1573	should be a hash containing any <tt>_.templateSettings</tt> that should be overridden.
1574	</p>
1575
1576	<pre>
1577	var compiled = _.template("hello: <%= name %>");
1578	compiled({name : 'moe'});
1579	=> "hello: moe"
1580
1581	var list = "<% _.each(people, function(name) { %> <li><%= name %></li> <% }); %>";
1582	_.template(list, {people : ['moe', 'curly', 'larry']});
1583	=> "<li>moe</li><li>curly</li><li>larry</li>"
1584
1585	var template = _.template("<b><%- value %></b>");
1586	template({value : '<script>'});
1587	=> "<b>&lt;script&gt;</b>"</pre>
1588
1589	<p>
1590	You can also use <tt>print</tt> from within JavaScript code. This is
1591	sometimes more convenient than using <tt><%= ... %></tt>.
1592	</p>
1593
1594	<pre>
1595	var compiled = _.template("<% print('Hello ' + epithet); %>");
1596	compiled({epithet: "stooge"});
1597	=> "Hello stooge."</pre>
1598
1599	<p>
1600	If ERB-style delimiters aren't your cup of tea, you can change Underscore's
1601	template settings to use different symbols to set off interpolated code.
1602	Define an <b>interpolate</b> regex to match expressions that should be
1603	interpolated verbatim, an <b>escape</b> regex to match expressions that should
1604	be inserted after being HTML escaped, and an <b>evaluate</b> regex to match
1605	expressions that should be evaluated without insertion into the resulting
1606	string. You may define or omit any combination of the three.
1607	For example, to perform
1608	<a href="http://github.com/janl/mustache.js#readme">Mustache.js</a>
1609	style templating:
1610	</p>
1611
1612	<pre>
1613	_.templateSettings = {
1614	interpolate : /\{\{(.+?)\}\}/g
1615	};
1616
1617	var template = _.template("Hello {{ name }}!");
1618	template({name : "Mustache"});
1619	=> "Hello Mustache!"</pre>
1620
1621	<p>
1622	By default, <b>template</b> places the values from your data in the local scope
1623	via the <tt>with</tt> statement. However, you can specify a single variable name
1624	with the <b>variable</b> setting. This can significantly improve the speed
1625	at which a template is able to render.
1626	</p>
1627
1628	<pre>
1629	_.template("Using 'with': <%= data.answer %>", {answer: 'no'}, {variable: 'data'});
1630	=> "Using 'with': no"</pre>
1631
1632	<p>
1633	Precompiling your templates can be a big help when debugging errors you can't
1634	reproduce. This is because precompiled templates can provide line numbers and
1635	a stack trace, something that is not possible when compiling templates on the client.
1636	The <b>source</b> property is available on the compiled template
1637	function for easy precompilation.
1638	</p>
1639
1640	<pre><script>
1641	JST.project = <%= _.template(jstText).source %>;
1642	</script></pre>
1643
1644
1645	<h2 id="chaining">Chaining</h2>
1646
1647	<p>
1648	You can use Underscore in either an object-oriented or a functional style,
1649	depending on your preference. The following two lines of code are
1650	identical ways to double a list of numbers.
1651	</p>
1652
1653	<pre>
1654	_.map([1, 2, 3], function(n){ return n * 2; });
1655	_([1, 2, 3]).map(function(n){ return n * 2; });</pre>
1656
1657	<p>
1658	Calling <tt>chain</tt> will cause all future method calls to return
1659	wrapped objects. When you've finished the computation, use
1660	<tt>value</tt> to retrieve the final value. Here's an example of chaining
1661	together a <b>map/flatten/reduce</b>, in order to get the word count of
1662	every word in a song.
1663	</p>
1664
1665	<pre>
1666	var lyrics = [
1667	{line : 1, words : "I'm a lumberjack and I'm okay"},
1668	{line : 2, words : "I sleep all night and I work all day"},
1669	{line : 3, words : "He's a lumberjack and he's okay"},
1670	{line : 4, words : "He sleeps all night and he works all day"}
1671	];
1672
1673	_.chain(lyrics)
1674	.map(function(line) { return line.words.split(' '); })
1675	.flatten()
1676	.reduce(function(counts, word) {
1677	counts[word] = (counts[word] \|\| 0) + 1;
1678	return counts;
1679	}, {})
1680	.value();
1681
1682	=> {lumberjack : 2, all : 4, night : 2 ... }</pre>
1683
1684	<p>
1685	In addition, the
1686	<a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/prototype">Array prototype's methods</a>
1687	are proxied through the chained Underscore object, so you can slip a
1688	<tt>reverse</tt> or a <tt>push</tt> into your chain, and continue to
1689	modify the array.
1690	</p>
1691
1692	<p id="chain">
1693	<b class="header">chain</b><code>_.chain(obj)</code>
1694	<br />
1695	Returns a wrapped object. Calling methods on this object will continue
1696	to return wrapped objects until <tt>value</tt> is used.
1697	</p>
1698	<pre>
1699	var stooges = [{name : 'curly', age : 25}, {name : 'moe', age : 21}, {name : 'larry', age : 23}];
1700	var youngest = _.chain(stooges)
1701	.sortBy(function(stooge){ return stooge.age; })
1702	.map(function(stooge){ return stooge.name + ' is ' + stooge.age; })
1703	.first()
1704	.value();
1705	=> "moe is 21"
1706	</pre>
1707
1708	<p id="value">
1709	<b class="header">value</b><code>_(obj).value()</code>
1710	<br />
1711	Extracts the value of a wrapped object.
1712	</p>
1713	<pre>
1714	_([1, 2, 3]).value();
1715	=> [1, 2, 3]
1716	</pre>
1717
1718	<h2 id="links">Links & Suggested Reading</h2>
1719
1720	<p>
1721	The Underscore documentation is also available in
1722	<a href="http://learning.github.com/underscore/">Simplified Chinese</a>.
1723	</p>
1724
1725	<p>
1726	<a href="http://mirven.github.com/underscore.lua/">Underscore.lua</a>,
1727	a Lua port of the functions that are applicable in both languages.
1728	Includes OOP-wrapping and chaining.
1729	(<a href="http://github.com/mirven/underscore.lua">source</a>)
1730	</p>
1731
1732	<p>
1733	<a href="http://underscorem.org">Underscore.m</a>, an Objective-C port
1734	of many of the Underscore.js functions, using a syntax that encourages
1735	chaining.
1736	(<a href="https://github.com/robb/Underscore.m">source</a>)
1737	</p>
1738
1739	<p>
1740	<a href="http://kmalakoff.github.com/_.m/">_.m</a>, an alternative
1741	Objective-C port that tries to stick a little closer to the original
1742	Underscore.js API.
1743	(<a href="https://github.com/kmalakoff/_.m">source</a>)
1744	</p>
1745
1746	<p>
1747	<a href="http://brianhaveri.github.com/Underscore.php/">Underscore.php</a>,
1748	a PHP port of the functions that are applicable in both languages.
1749	Includes OOP-wrapping and chaining.
1750	(<a href="http://github.com/brianhaveri/Underscore.php">source</a>)
1751	</p>
1752
1753	<p>
1754	<a href="http://vti.github.com/underscore-perl/">Underscore-perl</a>,
1755	a Perl port of many of the Underscore.js functions,
1756	aimed at on Perl hashes and arrays.
1757	(<a href="https://github.com/vti/underscore-perl/">source</a>)
1758	</p>
1759
1760	<p>
1761	<a href="http://russplaysguitar.github.com/UnderscoreCF/">Underscore.cfc</a>,
1762	a Coldfusion port of many of the Underscore.js functions.
1763	(<a href="https://github.com/russplaysguitar/underscorecf">source</a>)
1764	</p>
1765
1766	<p>
1767	<a href="https://github.com/edtsech/underscore.string">Underscore.string</a>,
1768	an Underscore extension that adds functions for string-manipulation:
1769	<tt>trim</tt>, <tt>startsWith</tt>, <tt>contains</tt>, <tt>capitalize</tt>,
1770	<tt>reverse</tt>, <tt>sprintf</tt>, and more.
1771	</p>
1772
1773	<p>
1774	Ruby's <a href="http://ruby-doc.org/core/classes/Enumerable.html">Enumerable</a> module.
1775	</p>
1776
1777	<p>
1778	<a href="http://www.prototypejs.org/">Prototype.js</a>, which provides
1779	JavaScript with collection functions in the manner closest to Ruby's Enumerable.
1780	</p>
1781
1782	<p>
1783	Oliver Steele's
1784	<a href="http://osteele.com/sources/javascript/functional/">Functional JavaScript</a>,
1785	which includes comprehensive higher-order function support as well as string lambdas.
1786	</p>
1787
1788	<p>
1789	Michael Aufreiter's <a href="http://github.com/michael/data">Data.js</a>,
1790	a data manipulation + persistence library for JavaScript.
1791	</p>
1792
1793	<p>
1794	Python's <a href="http://docs.python.org/library/itertools.html">itertools</a>.
1795	</p>
1796
1797	<h2 id="changelog">Change Log</h2>
1798
1799	<p>
1800	<b class="header">1.4.4</b> — <small><i>Jan. 30, 2013</i></small> — <a href="https://github.com/documentcloud/underscore/compare/1.4.3...1.4.4">Diff</a><br />
1801	<ul>
1802	<li>
1803	Added <tt>_.findWhere</tt>, for finding the first element in a list
1804	that matches a particular set of keys and values.
1805	</li>
1806	<li>
1807	Added <tt>_.partial</tt>, for partially applying a function <i>without</i>
1808	changing its dynamic reference to <tt>this</tt>.
1809	</li>
1810	<li>
1811	Simplified <tt>bind</tt> by removing some edge cases involving
1812	constructor functions. In short: don't <tt>_.bind</tt> your
1813	constructors.
1814	</li>
1815	<li>
1816	A minor optimization to <tt>invoke</tt>.
1817	</li>
1818	<li>
1819	Fix bug in the minified version due to the minifier incorrectly
1820	optimizing-away <tt>isFunction</tt>.
1821	</li>
1822	</ul>
1823	</p>
1824
1825	<p>
1826	<b class="header">1.4.3</b> — <small><i>Dec. 4, 2012</i></small> — <a href="https://github.com/documentcloud/underscore/compare/1.4.2...1.4.3">Diff</a><br />
1827	<ul>
1828	<li>
1829	Improved Underscore compatibility with Adobe's JS engine that can be
1830	used to script Illustrator, Photoshop, and friends.
1831	</li>
1832	<li>
1833	Added a default <tt>_.identity</tt> iterator to <tt>countBy</tt> and
1834	<tt>groupBy</tt>.
1835	</li>
1836	<li>
1837	The <tt>uniq</tt> function can now take <tt>array, iterator, context</tt>
1838	as the argument list.
1839	</li>
1840	<li>
1841	The <tt>times</tt> function now returns the mapped array of iterator
1842	results.
1843	</li>
1844	<li>
1845	Simplified and fixed bugs in <tt>throttle</tt>.
1846	</li>
1847	</ul>
1848	</p>
1849
1850	<p>
1851	<b class="header">1.4.2</b> — <small><i>Oct. 1, 2012</i></small> — <a href="https://github.com/documentcloud/underscore/compare/1.4.1...1.4.2">Diff</a><br />
1852	<ul>
1853	<li>
1854	For backwards compatibility, returned to pre-1.4.0 behavior when
1855	passing <tt>null</tt> to iteration functions. They now become no-ops
1856	again.
1857	</li>
1858	</ul>
1859	</p>
1860
1861	<p>
1862	<b class="header">1.4.1</b> — <small><i>Oct. 1, 2012</i></small> — <a href="https://github.com/documentcloud/underscore/compare/1.4.0...1.4.1">Diff</a><br />
1863	<ul>
1864	<li>
1865	Fixed a 1.4.0 regression in the <tt>lastIndexOf</tt> function.
1866	</li>
1867	</ul>
1868	</p>
1869
1870	<p>
1871	<b class="header">1.4.0</b> — <small><i>Sept. 27, 2012</i></small> — <a href="https://github.com/documentcloud/underscore/compare/1.3.3...1.4.0">Diff</a><br />
1872	<ul>
1873	<li>
1874	Added a <tt>pairs</tt> function, for turning a JavaScript object
1875	into <tt>[key, value]</tt> pairs ... as well as an <tt>object</tt>
1876	function, for converting an array of <tt>[key, value]</tt> pairs
1877	into an object.
1878	</li>
1879	<li>
1880	Added a <tt>countBy</tt> function, for counting the number of objects
1881	in a list that match a certain criteria.
1882	</li>
1883	<li>
1884	Added an <tt>invert</tt> function, for performing a simple inversion
1885	of the keys and values in an object.
1886	</li>
1887	<li>
1888	Added a <tt>where</tt> function, for easy cases of filtering a list
1889	for objects with specific values.
1890	</li>
1891	<li>
1892	Added an <tt>omit</tt> function, for filtering an object to remove
1893	certain keys.
1894	</li>
1895	<li>
1896	Added a <tt>random</tt> function, to return a random number in a
1897	given range.
1898	</li>
1899	<li>
1900	<tt>_.debounce</tt>'d functions now return their last updated value,
1901	just like <tt>_.throttle</tt>'d functions do.
1902	</li>
1903	<li>
1904	The <tt>sortBy</tt> function now runs a stable sort algorithm.
1905	</li>
1906	<li>
1907	Added the optional <tt>fromIndex</tt> option to <tt>indexOf</tt> and
1908	<tt>lastIndexOf</tt>.
1909	</li>
1910	<li>
1911	"Sparse" arrays are no longer supported in Underscore iteration
1912	functions. Use a <tt>for</tt> loop instead (or better yet, an object).
1913	</li>
1914	<li>
1915	The <tt>min</tt> and <tt>max</tt> functions may now be called on
1916	<i>very</i> large arrays.
1917	</li>
1918	<li>
1919	Interpolation in templates now represents <tt>null</tt> and
1920	<tt>undefined</tt> as the empty string.
1921	</li>
1922	<li>
1923	<del>Underscore iteration functions no longer accept <tt>null</tt> values
1924	as a no-op argument. You'll get an early error instead.</del>
1925	</li>
1926	<li>
1927	A number of edge-cases fixes and tweaks, which you can spot in the
1928	<a href="https://github.com/documentcloud/underscore/compare/1.3.3...1.4.0">diff</a>.
1929	Depending on how you're using Underscore, <b>1.4.0</b> may be more
1930	backwards-incompatible than usual — please test when you upgrade.
1931	</li>
1932	</ul>
1933	</p>
1934
1935	<p>
1936	<b class="header">1.3.3</b> — <small><i>April 10, 2012</i></small><br />
1937	<ul>
1938	<li>
1939	Many improvements to <tt>_.template</tt>, which now provides the
1940	<tt>source</tt> of the template function as a property, for potentially
1941	even more efficient pre-compilation on the server-side. You may now
1942	also set the <tt>variable</tt> option when creating a template,
1943	which will cause your passed-in data to be made available under the
1944	variable you named, instead of using a <tt>with</tt> statement —
1945	significantly improving the speed of rendering the template.
1946	</li>
1947	<li>
1948	Added the <tt>pick</tt> function, which allows you to filter an
1949	object literal with a whitelist of allowed property names.
1950	</li>
1951	<li>
1952	Added the <tt>result</tt> function, for convenience when working
1953	with APIs that allow either functions or raw properties.
1954	</li>
1955	<li>
1956	Added the <tt>isFinite</tt> function, because sometimes knowing that
1957	a value is a number just ain't quite enough.
1958	</li>
1959	<li>
1960	The <tt>sortBy</tt> function may now also be passed the string name
1961	of a property to use as the sort order on each object.
1962	</li>
1963	<li>
1964	Fixed <tt>uniq</tt> to work with sparse arrays.
1965	</li>
1966	<li>
1967	The <tt>difference</tt> function now performs a shallow flatten
1968	instead of a deep one when computing array differences.
1969	</li>
1970	<li>
1971	The <tt>debounce</tt> function now takes an <tt>immediate</tt>
1972	parameter, which will cause the callback to fire on the leading
1973	instead of the trailing edge.
1974	</li>
1975	</ul>
1976	</p>
1977
1978	<p>
1979	<b class="header">1.3.1</b> — <small><i>Jan. 23, 2012</i></small><br />
1980	<ul>
1981	<li>
1982	Added an <tt>_.has</tt> function, as a safer way to use <tt>hasOwnProperty</tt>.
1983	</li>
1984	<li>
1985	Added <tt>_.collect</tt> as an alias for <tt>_.map</tt>. Smalltalkers, rejoice.
1986	</li>
1987	<li>
1988	Reverted an old change so that <tt>_.extend</tt> will correctly copy
1989	over keys with undefined values again.
1990	</li>
1991	<li>
1992	Bugfix to stop escaping slashes within interpolations in <tt>_.template</tt>.
1993	</li>
1994	</ul>
1995	</p>
1996
1997	<p>
1998	<b class="header">1.3.0</b> — <small><i>Jan. 11, 2012</i></small><br />
1999	<ul>
2000	<li>
2001	Removed AMD (RequireJS) support from Underscore. If you'd like to use
2002	Underscore with RequireJS, you can load it as a normal script, wrap
2003	or patch your copy, or download a forked version.
2004	</li>
2005	</ul>
2006	</p>
2007
2008	<p>
2009	<b class="header">1.2.4</b> — <small><i>Jan. 4, 2012</i></small><br />
2010	<ul>
2011	<li>
2012	You now can (and probably should, as it's simpler)
2013	write <tt>_.chain(list)</tt>
2014	instead of <tt>_(list).chain()</tt>.
2015	</li>
2016	<li>
2017	Fix for escaped characters in Underscore templates, and for supporting
2018	customizations of <tt>_.templateSettings</tt> that only define one or
2019	two of the required regexes.
2020	</li>
2021	<li>
2022	Fix for passing an array as the first argument to an <tt>_.wrap</tt>'d function.
2023	</li>
2024	<li>
2025	Improved compatibility with ClojureScript, which adds a <tt>call</tt>
2026	function to <tt>String.prototype</tt>.
2027	</li>
2028	</ul>
2029	</p>
2030
2031	<p>
2032	<b class="header">1.2.3</b> — <small><i>Dec. 7, 2011</i></small><br />
2033	<ul>
2034	<li>
2035	Dynamic scope is now preserved for compiled <tt>_.template</tt> functions,
2036	so you can use the value of <tt>this</tt> if you like.
2037	</li>
2038	<li>
2039	Sparse array support of <tt>_.indexOf</tt>, <tt>_.lastIndexOf</tt>.
2040	</li>
2041	<li>
2042	Both <tt>_.reduce</tt> and <tt>_.reduceRight</tt> can now be passed an
2043	explicitly <tt>undefined</tt> value. (There's no reason why you'd
2044	want to do this.)
2045	</li>
2046	</ul>
2047	</p>
2048
2049	<p>
2050	<b class="header">1.2.2</b> — <small><i>Nov. 14, 2011</i></small><br />
2051	<ul>
2052	<li>
2053	Continued tweaks to <tt>_.isEqual</tt> semantics. Now JS primitives are
2054	considered equivalent to their wrapped versions, and arrays are compared
2055	by their numeric properties only <small>(#351)</small>.
2056	</li>
2057	<li>
2058	<tt>_.escape</tt> no longer tries to be smart about not double-escaping
2059	already-escaped HTML entities. Now it just escapes regardless <small>(#350)</small>.
2060	</li>
2061	<li>
2062	In <tt>_.template</tt>, you may now leave semicolons out of evaluated
2063	statements if you wish: <tt><% }) %></tt> <small>(#369)</small>.
2064	</li>
2065	<li>
2066	<tt>_.after(callback, 0)</tt> will now trigger the callback immediately,
2067	making "after" easier to use with asynchronous APIs <small>(#366)</small>.
2068	</li>
2069	</ul>
2070	</p>
2071
2072	<p>
2073	<b class="header">1.2.1</b> — <small><i>Oct. 24, 2011</i></small><br />
2074	<ul>
2075	<li>
2076	Several important bug fixes for <tt>_.isEqual</tt>, which should now
2077	do better on mutated Arrays, and on non-Array objects with
2078	<tt>length</tt> properties. <small>(#329)</small>
2079	</li>
2080	<li>
2081	<b>jrburke</b> contributed Underscore exporting for AMD module loaders,
2082	and <b>tonylukasavage</b> for Appcelerator Titanium.
2083	<small>(#335, #338)</small>
2084	</li>
2085	<li>
2086	You can now <tt>_.groupBy(list, 'property')</tt> as a shortcut for
2087	grouping values by a particular common property.
2088	</li>
2089	<li>
2090	<tt>_.throttle</tt>'d functions now fire immediately upon invocation,
2091	and are rate-limited thereafter <small>(#170, #266)</small>.
2092	</li>
2093	<li>
2094	Most of the <tt>_.is[Type]</tt> checks no longer ducktype.
2095	</li>
2096	<li>
2097	The <tt>_.bind</tt> function now also works on constructors, a-la
2098	ES5 ... but you would never want to use <tt>_.bind</tt> on a
2099	constructor function.
2100	</li>
2101	<li>
2102	<tt>_.clone</tt> no longer wraps non-object types in Objects.
2103	</li>
2104	<li>
2105	<tt>_.find</tt> and <tt>_.filter</tt> are now the preferred names for
2106	<tt>_.detect</tt> and <tt>_.select</tt>.
2107	</li>
2108	</ul>
2109	</p>
2110
2111	<p>
2112	<b class="header">1.2.0</b> — <small><i>Oct. 5, 2011</i></small><br />
2113	<ul>
2114	<li>
2115	The <tt>_.isEqual</tt> function now
2116	supports true deep equality comparisons, with checks for cyclic structures,
2117	thanks to Kit Cambridge.
2118	</li>
2119	<li>
2120	Underscore templates now support HTML escaping interpolations, using
2121	<tt><%- ... %></tt> syntax.
2122	</li>
2123	<li>
2124	Ryan Tenney contributed <tt>_.shuffle</tt>, which uses a modified
2125	Fisher-Yates to give you a shuffled copy of an array.
2126	</li>
2127	<li>
2128	<tt>_.uniq</tt> can now be passed an optional iterator, to determine by
2129	what criteria an object should be considered unique.
2130	</li>
2131	<li>
2132	<tt>_.last</tt> now takes an optional argument which will return the last
2133	N elements of the list.
2134	</li>
2135	<li>
2136	A new <tt>_.initial</tt> function was added, as a mirror of <tt>_.rest</tt>,
2137	which returns all the initial values of a list (except the last N).
2138	</li>
2139	</ul>
2140	</p>
2141
2142	<p>
2143	<b class="header">1.1.7</b> — <small><i>July 13, 2011</i></small><br />
2144	Added <tt>_.groupBy</tt>, which aggregates a collection into groups of like items.
2145	Added <tt>_.union</tt> and <tt>_.difference</tt>, to complement the
2146	(re-named) <tt>_.intersection</tt>.
2147	Various improvements for support of sparse arrays.
2148	<tt>_.toArray</tt> now returns a clone, if directly passed an array.
2149	<tt>_.functions</tt> now also returns the names of functions that are present
2150	in the prototype chain.
2151	</p>
2152
2153	<p>
2154	<b class="header">1.1.6</b> — <small><i>April 18, 2011</i></small><br />
2155	Added <tt>_.after</tt>, which will return a function that only runs after
2156	first being called a specified number of times.
2157	<tt>_.invoke</tt> can now take a direct function reference.
2158	<tt>_.every</tt> now requires an iterator function to be passed, which
2159	mirrors the ECMA5 API.
2160	<tt>_.extend</tt> no longer copies keys when the value is undefined.
2161	<tt>_.bind</tt> now errors when trying to bind an undefined value.
2162	</p>
2163
2164	<p>
2165	<b class="header">1.1.5</b> — <small><i>Mar 20, 2011</i></small><br />
2166	Added an <tt>_.defaults</tt> function, for use merging together JS objects
2167	representing default options.
2168	Added an <tt>_.once</tt> function, for manufacturing functions that should
2169	only ever execute a single time.
2170	<tt>_.bind</tt> now delegates to the native ECMAScript 5 version,
2171	where available.
2172	<tt>_.keys</tt> now throws an error when used on non-Object values, as in
2173	ECMAScript 5.
2174	Fixed a bug with <tt>_.keys</tt> when used over sparse arrays.
2175	</p>
2176
2177	<p>
2178	<b class="header">1.1.4</b> — <small><i>Jan 9, 2011</i></small><br />
2179	Improved compliance with ES5's Array methods when passing <tt>null</tt>
2180	as a value. <tt>_.wrap</tt> now correctly sets <tt>this</tt> for the
2181	wrapped function. <tt>_.indexOf</tt> now takes an optional flag for
2182	finding the insertion index in an array that is guaranteed to already
2183	be sorted. Avoiding the use of <tt>.callee</tt>, to allow <tt>_.isArray</tt>
2184	to work properly in ES5's strict mode.
2185	</p>
2186
2187	<p>
2188	<b class="header">1.1.3</b> — <small><i>Dec 1, 2010</i></small><br />
2189	In CommonJS, Underscore may now be required with just: <br />
2190	<tt>var _ = require("underscore")</tt>.
2191	Added <tt>_.throttle</tt> and <tt>_.debounce</tt> functions.
2192	Removed <tt>_.breakLoop</tt>, in favor of an ECMA5-style un-<i>break</i>-able
2193	each implementation — this removes the try/catch, and you'll now have
2194	better stack traces for exceptions that are thrown within an Underscore iterator.
2195	Improved the <b>isType</b> family of functions for better interoperability
2196	with Internet Explorer host objects.
2197	<tt>_.template</tt> now correctly escapes backslashes in templates.
2198	Improved <tt>_.reduce</tt> compatibility with the ECMA5 version:
2199	if you don't pass an initial value, the first item in the collection is used.
2200	<tt>_.each</tt> no longer returns the iterated collection, for improved
2201	consistency with ES5's <tt>forEach</tt>.
2202	</p>
2203
2204	<p>
2205	<b class="header">1.1.2</b><br />
2206	Fixed <tt>_.contains</tt>, which was mistakenly pointing at
2207	<tt>_.intersect</tt> instead of <tt>_.include</tt>, like it should
2208	have been. Added <tt>_.unique</tt> as an alias for <tt>_.uniq</tt>.
2209	</p>
2210
2211	<p>
2212	<b class="header">1.1.1</b><br />
2213	Improved the speed of <tt>_.template</tt>, and its handling of multiline
2214	interpolations. Ryan Tenney contributed optimizations to many Underscore
2215	functions. An annotated version of the source code is now available.
2216	</p>
2217
2218	<p>
2219	<b class="header">1.1.0</b><br />
2220	The method signature of <tt>_.reduce</tt> has been changed to match
2221	the ECMAScript 5 signature, instead of the Ruby/Prototype.js version.
2222	This is a backwards-incompatible change. <tt>_.template</tt> may now be
2223	called with no arguments, and preserves whitespace. <tt>_.contains</tt>
2224	is a new alias for <tt>_.include</tt>.
2225	</p>
2226
2227	<p>
2228	<b class="header">1.0.4</b><br />
2229	<a href="http://themoell.com/">Andri MÃ¶ll</a> contributed the <tt>_.memoize</tt>
2230	function, which can be used to speed up expensive repeated computations
2231	by caching the results.
2232	</p>
2233
2234	<p>
2235	<b class="header">1.0.3</b><br />
2236	Patch that makes <tt>_.isEqual</tt> return <tt>false</tt> if any property
2237	of the compared object has a <tt>NaN</tt> value. Technically the correct
2238	thing to do, but of questionable semantics. Watch out for NaN comparisons.
2239	</p>
2240
2241	<p>
2242	<b class="header">1.0.2</b><br />
2243	Fixes <tt>_.isArguments</tt> in recent versions of Opera, which have
2244	arguments objects as real Arrays.
2245	</p>
2246
2247	<p>
2248	<b class="header">1.0.1</b><br />
2249	Bugfix for <tt>_.isEqual</tt>, when comparing two objects with the same
2250	number of undefined keys, but with different names.
2251	</p>
2252
2253	<p>
2254	<b class="header">1.0.0</b><br />
2255	Things have been stable for many months now, so Underscore is now
2256	considered to be out of beta, at <b>1.0</b>. Improvements since <b>0.6</b>
2257	include <tt>_.isBoolean</tt>, and the ability to have <tt>_.extend</tt>
2258	take multiple source objects.
2259	</p>
2260
2261	<p>
2262	<b class="header">0.6.0</b><br />
2263	Major release. Incorporates a number of
2264	<a href="http://github.com/ratbeard">Mile Frawley's</a> refactors for
2265	safer duck-typing on collection functions, and cleaner internals. A new
2266	<tt>_.mixin</tt> method that allows you to extend Underscore with utility
2267	functions of your own. Added <tt>_.times</tt>, which works the same as in
2268	Ruby or Prototype.js. Native support for ECMAScript 5's <tt>Array.isArray</tt>,
2269	and <tt>Object.keys</tt>.
2270	</p>
2271
2272	<p>
2273	<b class="header">0.5.8</b><br />
2274	Fixed Underscore's collection functions to work on
2275	<a href="https://developer.mozilla.org/En/DOM/NodeList">NodeLists</a> and
2276	<a href="https://developer.mozilla.org/En/DOM/HTMLCollection">HTMLCollections</a>
2277	once more, thanks to
2278	<a href="http://github.com/jmtulloss">Justin Tulloss</a>.
2279	</p>
2280
2281	<p>
2282	<b class="header">0.5.7</b><br />
2283	A safer implementation of <tt>_.isArguments</tt>, and a
2284	faster <tt>_.isNumber</tt>,<br />thanks to
2285	<a href="http://jedschmidt.com/">Jed Schmidt</a>.
2286	</p>
2287
2288	<p>
2289	<b class="header">0.5.6</b><br />
2290	Customizable delimiters for <tt>_.template</tt>, contributed by
2291	<a href="http://github.com/iamnoah">Noah Sloan</a>.
2292	</p>
2293
2294	<p>
2295	<b class="header">0.5.5</b><br />
2296	Fix for a bug in MobileSafari's OOP-wrapper, with the arguments object.
2297	</p>
2298
2299	<p>
2300	<b class="header">0.5.4</b><br />
2301	Fix for multiple single quotes within a template string for
2302	<tt>_.template</tt>. See:
2303	<a href="http://www.west-wind.com/Weblog/posts/509108.aspx">Rick Strahl's blog post</a>.
2304	</p>
2305
2306	<p>
2307	<b class="header">0.5.2</b><br />
2308	New implementations of <tt>isArray</tt>, <tt>isDate</tt>, <tt>isFunction</tt>,
2309	<tt>isNumber</tt>, <tt>isRegExp</tt>, and <tt>isString</tt>, thanks to
2310	a suggestion from
2311	<a href="http://www.broofa.com/">Robert Kieffer</a>.
2312	Instead of doing <tt>Object#toString</tt>
2313	comparisons, they now check for expected properties, which is less safe,
2314	but more than an order of magnitude faster. Most other Underscore
2315	functions saw minor speed improvements as a result.
2316	<a href="http://dolzhenko.org/">Evgeniy Dolzhenko</a>
2317	contributed <tt>_.tap</tt>,
2318	<a href="http://ruby-doc.org/core-1.9/classes/Object.html#M000191">similar to Ruby 1.9's</a>,
2319	which is handy for injecting side effects (like logging) into chained calls.
2320	</p>
2321
2322	<p>
2323	<b class="header">0.5.1</b><br />
2324	Added an <tt>_.isArguments</tt> function. Lots of little safety checks
2325	and optimizations contributed by
2326	<a href="http://github.com/iamnoah/">Noah Sloan</a> and
2327	<a href="http://themoell.com/">Andri MÃ¶ll</a>.
2328	</p>
2329
2330	<p>
2331	<b class="header">0.5.0</b><br />
2332	<b>[API Changes]</b> <tt>_.bindAll</tt> now takes the context object as
2333	its first parameter. If no method names are passed, all of the context
2334	object's methods are bound to it, enabling chaining and easier binding.
2335	<tt>_.functions</tt> now takes a single argument and returns the names
2336	of its Function properties. Calling <tt>_.functions(_)</tt> will get you
2337	the previous behavior.
2338	Added <tt>_.isRegExp</tt> so that <tt>isEqual</tt> can now test for RegExp equality.
2339	All of the "is" functions have been shrunk down into a single definition.
2340	<a href="http://github.com/grayrest/">Karl Guertin</a> contributed patches.
2341	</p>
2342
2343	<p>
2344	<b class="header">0.4.7</b><br />
2345	Added <tt>isDate</tt>, <tt>isNaN</tt>, and <tt>isNull</tt>, for completeness.
2346	Optimizations for <tt>isEqual</tt> when checking equality between Arrays
2347	or Dates. <tt>_.keys</tt> is now <small><i><b>25%–2X</b></i></small> faster (depending on your
2348	browser) which speeds up the functions that rely on it, such as <tt>_.each</tt>.
2349	</p>
2350
2351	<p>
2352	<b class="header">0.4.6</b><br />
2353	Added the <tt>range</tt> function, a port of the
2354	<a href="http://docs.python.org/library/functions.html#range">Python
2355	function of the same name</a>, for generating flexibly-numbered lists
2356	of integers. Original patch contributed by
2357	<a href="http://github.com/kylichuku">Kirill Ishanov</a>.
2358	</p>
2359
2360	<p>
2361	<b class="header">0.4.5</b><br />
2362	Added <tt>rest</tt> for Arrays and arguments objects, and aliased
2363	<tt>first</tt> as <tt>head</tt>, and <tt>rest</tt> as <tt>tail</tt>,
2364	thanks to <a href="http://github.com/lukesutton/">Luke Sutton</a>'s patches.
2365	Added tests ensuring that all Underscore Array functions also work on
2366	<i>arguments</i> objects.
2367	</p>
2368
2369	<p>
2370	<b class="header">0.4.4</b><br />
2371	Added <tt>isString</tt>, and <tt>isNumber</tt>, for consistency. Fixed
2372	<tt>_.isEqual(NaN, NaN)</tt> to return <i>true</i> (which is debatable).
2373	</p>
2374
2375	<p>
2376	<b class="header">0.4.3</b><br />
2377	Started using the native <tt>StopIteration</tt> object in browsers that support it.
2378	Fixed Underscore setup for CommonJS environments.
2379	</p>
2380
2381	<p>
2382	<b class="header">0.4.2</b><br />
2383	Renamed the unwrapping function to <tt>value</tt>, for clarity.
2384	</p>
2385
2386	<p>
2387	<b class="header">0.4.1</b><br />
2388	Chained Underscore objects now support the Array prototype methods, so
2389	that you can perform the full range of operations on a wrapped array
2390	without having to break your chain. Added a <tt>breakLoop</tt> method
2391	to <b>break</b> in the middle of any Underscore iteration. Added an
2392	<tt>isEmpty</tt> function that works on arrays and objects.
2393	</p>
2394
2395	<p>
2396	<b class="header">0.4.0</b><br />
2397	All Underscore functions can now be called in an object-oriented style,
2398	like so: <tt>_([1, 2, 3]).map(...);</tt>. Original patch provided by
2399	<a href="http://macournoyer.com/">Marc-AndrÃ© Cournoyer</a>.
2400	Wrapped objects can be chained through multiple
2401	method invocations. A <a href="#object-functions"><tt>functions</tt></a> method
2402	was added, providing a sorted list of all the functions in Underscore.
2403	</p>
2404
2405	<p>
2406	<b class="header">0.3.3</b><br />
2407	Added the JavaScript 1.8 function <tt>reduceRight</tt>. Aliased it
2408	as <tt>foldr</tt>, and aliased <tt>reduce</tt> as <tt>foldl</tt>.
2409	</p>
2410
2411	<p>
2412	<b class="header">0.3.2</b><br />
2413	Now runs on stock <a href="http://www.mozilla.org/rhino/">Rhino</a>
2414	interpreters with: <tt>load("underscore.js")</tt>.
2415	Added <a href="#identity"><tt>identity</tt></a> as a utility function.
2416	</p>
2417
2418	<p>
2419	<b class="header">0.3.1</b><br />
2420	All iterators are now passed in the original collection as their third
2421	argument, the same as JavaScript 1.6's <b>forEach</b>. Iterating over
2422	objects is now called with <tt>(value, key, collection)</tt>, for details
2423	see <a href="#each"><tt>_.each</tt></a>.
2424	</p>
2425
2426	<p>
2427	<b class="header">0.3.0</b><br />
2428	Added <a href="http://github.com/dmitryBaranovskiy">Dmitry Baranovskiy</a>'s
2429	comprehensive optimizations, merged in
2430	<a href="http://github.com/kriskowal/">Kris Kowal</a>'s patches to make Underscore
2431	<a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> and
2432	<a href="http://narwhaljs.org/">Narwhal</a> compliant.
2433	</p>
2434
2435	<p>
2436	<b class="header">0.2.0</b><br />
2437	Added <tt>compose</tt> and <tt>lastIndexOf</tt>, renamed <tt>inject</tt> to
2438	<tt>reduce</tt>, added aliases for <tt>inject</tt>, <tt>filter</tt>,
2439	<tt>every</tt>, <tt>some</tt>, and <tt>forEach</tt>.
2440	</p>
2441
2442	<p>
2443	<b class="header">0.1.1</b><br />
2444	Added <tt>noConflict</tt>, so that the "Underscore" object can be assigned to
2445	other variables.
2446	</p>
2447
2448	<p>
2449	<b class="header">0.1.0</b><br />
2450	Initial release of Underscore.js.
2451	</p>
2452
2453	<p>
2454	<a href="http://documentcloud.org/" title="A DocumentCloud Project" style="background:none;">
2455	<img src="http://jashkenas.s3.amazonaws.com/images/a_documentcloud_project.png" alt="A DocumentCloud Project" />
2456	</a>
2457	</p>
2458
2459	</div>
2460
2461	</div>
2462
2463	<!-- Include Underscore, so you can play with it in the console. -->
2464	<script type="text/javascript" src="underscore.js"></script>
2465
2466	</body>
2467	</html>

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: Dev/trunk/node_modules/underscore/index.html

Download in other formats: