142
St
startsInvasion / files
startsInvasion / libs / node_modules / underscore / index.html
55.7 KB
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 <title>Underscore.js</title> 7 <style> 8 body { 9 font-size: 16px; 10 line-height: 24px; 11 background: #f0f0e5; 12 color: #252519; 13 font-family: "Palatino Linotype", "Book Antiqua", Palatino, FreeSerif, serif; 14 } 15 div.container { 16 width: 720px; 17 margin: 50px 0 50px 50px; 18 } 19 p { 20 width: 550px; 21 } 22 #documentation p { 23 margin-bottom: 4px; 24 } 25 a, a:visited { 26 padding: 0 2px; 27 text-decoration: none; 28 background: #dadaba; 29 color: #252519; 30 } 31 a:active, a:hover { 32 color: #000; 33 background: #f0c095; 34 } 35 h1, h2, h3, h4, h5, h6 { 36 margin-top: 40px; 37 } 38 b.header { 39 font-size: 18px; 40 } 41 span.alias { 42 font-size: 14px; 43 font-style: italic; 44 margin-left: 20px; 45 } 46 table, tr, td { 47 margin: 0; padding: 0; 48 } 49 td { 50 padding: 2px 12px 2px 0; 51 } 52 code, pre, tt { 53 font-family: Monaco, Consolas, "Lucida Console", monospace; 54 font-size: 12px; 55 line-height: 18px; 56 color: #555529; 57 } 58 code { 59 margin-left: 20px; 60 } 61 pre { 62 font-size: 12px; 63 padding: 2px 0 2px 12px; 64 border-left: 6px solid #aaaa99; 65 margin: 0px 0 30px; 66 } 67 </style> 68</head> 69<body> 70 71 <div class="container"> 72 73 <h1>Underscore.js</h1> 74 75 <p> 76 <a href="http://github.com/documentcloud/underscore/">Underscore</a> is a 77 utility-belt library for JavaScript that provides a lot of the 78 functional programming support that you would expect in 79 <a href="http://prototypejs.org/api">Prototype.js</a> 80 (or <a href="http://www.ruby-doc.org/core/classes/Enumerable.html">Ruby</a>), 81 but without extending any of the built-in JavaScript objects. It's the 82 tie to go along with <a href="http://docs.jquery.com">jQuery</a>'s tux. 83 </p> 84 85 <p> 86 Underscore provides 60-odd functions that support both the usual 87 functional suspects: <b>map</b>, <b>select</b>, <b>invoke</b> — 88 as well as more specialized helpers: function binding, javascript 89 templating, deep equality testing, and so on. It delegates to built-in 90 functions, if present, so modern browsers will use the 91 native implementations of <b>forEach</b>, <b>map</b>, <b>reduce</b>, 92 <b>filter</b>, <b>every</b>, <b>some</b> and <b>indexOf</b>. 93 </p> 94 95 <p> 96 A complete <a href="test/test.html">Test & Benchmark Suite</a> 97 is included for your perusal. 98 </p> 99 100 <p> 101 You may also read through the <a href="docs/underscore.html">annotated source code</a>. 102 </p> 103 104 <p> 105 The project is 106 <a href="http://github.com/documentcloud/underscore/">hosted on GitHub</a>. 107 You can report bugs and discuss features on the 108 <a href="http://github.com/documentcloud/underscore/issues">issues page</a>, 109 on Freenode in the <tt>#documentcloud</tt> channel, 110 or send tweets to <a href="http://twitter.com/documentcloud">@documentcloud</a>. 111 </p> 112 113 <p> 114 <i>Underscore is an open-source component of <a href="http://documentcloud.org/">DocumentCloud</a>.</i> 115 </p> 116 117 <h2>Downloads <i style="padding-left: 12px; font-size:12px;">(Right-click, and use "Save As")</i></h2> 118 119 <table> 120 <tr> 121 <td><a href="underscore.js">Development Version (1.1.6)</a></td> 122 <td><i>27kb, Uncompressed with Comments</i></td> 123 </tr> 124 <tr> 125 <td><a href="underscore-min.js">Production Version (1.1.6)</a></td> 126 <td><i>3kb, Minified and Gzipped</i></td> 127 </tr> 128 </table> 129 130 <h2>Table of Contents</h2> 131 132 <a href="#styles">Object-Oriented and Functional Styles</a> 133 134 <p> 135 <b>Collections</b> 136 <br /> 137 <span class="methods"><a href="#each">each</a>, <a href="#map">map</a>, 138 <a href="#reduce">reduce</a>, <a href="#reduceRight">reduceRight</a>, 139 <a href="#detect">detect</a>, <a href="#select">select</a>, 140 <a href="#reject">reject</a>, <a href="#all">all</a>, 141 <a href="#any">any</a>, <a href="#include">include</a>, 142 <a href="#invoke">invoke</a>, <a href="#pluck">pluck</a>, 143 <a href="#max">max</a>, <a href="#min">min</a>, 144 <a href="#sortBy">sortBy</a>, <a href="#sortedIndex">sortedIndex</a>, 145 <a href="#toArray">toArray</a>, <a href="#size">size</a></span> 146 </p> 147 148 <p> 149 <b>Arrays</b> 150 <br /> 151 <span class="methods"><a href="#first">first</a>, <a href="#rest">rest</a>, <a href="#last">last</a>, 152 <a href="#compact">compact</a>, <a href="#flatten">flatten</a>, <a href="#without">without</a>, <a href="#uniq">uniq</a>, 153 <a href="#intersect">intersect</a>, <a href="#zip">zip</a>, <a href="#indexOf">indexOf</a>, 154 <a href="#lastIndexOf">lastIndexOf</a>, <a href="#range">range</a></span> 155 </p> 156 157 <p> 158 <b>Functions</b> 159 <br /> 160 <span class="methods"><a href="#bind">bind</a>, <a href="#bindAll">bindAll</a>, 161 <a href="#memoize">memoize</a>, <a href="#delay">delay</a>, <a href="#defer">defer</a>, 162 <a href="#throttle">throttle</a>, <a href="#debounce">debounce</a>, 163 <a href="#once">once</a>, <a href="#after">after</a>, <a href="#wrap">wrap</a>, <a href="#compose">compose</a></span> 164 </p> 165 166 <p> 167 <b>Objects</b> 168 <br /> 169 <span class="methods"><a href="#keys">keys</a>, <a href="#values">values</a>, 170 <a href="#functions">functions</a>, <a href="#extend">extend</a>, <a href="#defaults">defaults</a>, <a href="#clone">clone</a>, <a href="#tap">tap</a>, 171 <a href="#isEqual">isEqual</a>, <a href="#isEmpty">isEmpty</a>, <a href="#isElement">isElement</a>, 172 <a href="#isArray">isArray</a>, <a href="#isArguments">isArguments</a>, <a href="#isFunction">isFunction</a>, <a href="#isString">isString</a>, 173 <a href="#isNumber">isNumber</a>, <a href="#isBoolean">isBoolean</a>, <a href="#isDate">isDate</a>, <a href="#isRegExp">isRegExp</a> 174 <a href="#isNaN">isNaN</a>, <a href="#isNull">isNull</a>, 175 <a href="#isUndefined">isUndefined</a> 176 </span> 177 </p> 178 179 <p> 180 <b>Utility</b> 181 <br /> 182 <span class="methods"><a href="#noConflict">noConflict</a>, 183 <a href="#identity">identity</a>, <a href="#times">times</a>, 184 <a href="#mixin">mixin</a>, <a href="#uniqueId">uniqueId</a>, 185 <a href="#template">template</a></span> 186 </p> 187 188 <p> 189 <b>Chaining</b> 190 <br /> 191 <span class="methods"><a href="#chain">chain</a>, <a href="#value">value</a> 192 </p> 193 194 <div id="documentation"> 195 196 <h2 id="styles">Object-Oriented and Functional Styles</h2> 197 198 <p> 199 You can use Underscore in either an object-oriented or a functional style, 200 depending on your preference. The following two lines of code are 201 identical ways to double a list of numbers. 202 </p> 203 204 <pre> 205_.map([1, 2, 3], function(n){ return n * 2; }); 206_([1, 2, 3]).map(function(n){ return n * 2; });</pre> 207 208 <p> 209 Using the object-oriented style allows you to chain together methods. Calling 210 <tt>chain</tt> on a wrapped object will cause all future method calls to 211 return wrapped objects as well. When you've finished the computation, 212 use <tt>value</tt> to retrieve the final value. Here's an example of chaining 213 together a <b>map/flatten/reduce</b>, in order to get the word count of 214 every word in a song. 215 </p> 216 217<pre> 218var lyrics = [ 219 {line : 1, words : "I'm a lumberjack and I'm okay"}, 220 {line : 2, words : "I sleep all night and I work all day"}, 221 {line : 3, words : "He's a lumberjack and he's okay"}, 222 {line : 4, words : "He sleeps all night and he works all day"} 223]; 224 225_(lyrics).chain() 226 .map(function(line) { return line.words.split(' '); }) 227 .flatten() 228 .reduce(function(counts, word) { 229 counts[word] = (counts[word] || 0) + 1; 230 return counts; 231}, {}).value(); 232 233=> {lumberjack : 2, all : 4, night : 2 ... }</pre> 234 235 <p> 236 In addition, the 237 <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/prototype">Array prototype's methods</a> 238 are proxied through the chained Underscore object, so you can slip a 239 <tt>reverse</tt> or a <tt>push</tt> into your chain, and continue to 240 modify the array. 241 </p> 242 243 <h2>Collection Functions (Arrays or Objects)</h2> 244 245 <p id="each"> 246 <b class="header">each</b><code>_.each(list, iterator, [context])</code> 247 <span class="alias">Alias: <b>forEach</b></span> 248 <br /> 249 Iterates over a <b>list</b> of elements, yielding each in turn to an <b>iterator</b> 250 function. The <b>iterator</b> is bound to the <b>context</b> object, if one is 251 passed. Each invocation of <b>iterator</b> is called with three arguments: 252 <tt>(element, index, list)</tt>. If <b>list</b> is a JavaScript object, <b>iterator</b>'s 253 arguments will be <tt>(value, key, list)</tt>. Delegates to the native 254 <b>forEach</b> function if it exists. 255 </p> 256 <pre> 257_.each([1, 2, 3], function(num){ alert(num); }); 258=> alerts each number in turn... 259_.each({one : 1, two : 2, three : 3}, function(num, key){ alert(num); }); 260=> alerts each number in turn...</pre> 261 262 <p id="map"> 263 <b class="header">map</b><code>_.map(list, iterator, [context])</code> 264 <br /> 265 Produces a new array of values by mapping each value in <b>list</b> 266 through a transformation function (<b>iterator</b>). If the native <b>map</b> method 267 exists, it will be used instead. If <b>list</b> is a JavaScript object, 268 <b>iterator</b>'s arguments will be <tt>(value, key, list)</tt>. 269 </p> 270 <pre> 271_.map([1, 2, 3], function(num){ return num * 3; }); 272=> [3, 6, 9] 273_.map({one : 1, two : 2, three : 3}, function(num, key){ return num * 3; }); 274=> [3, 6, 9]</pre> 275 276 <p id="reduce"> 277 <b class="header">reduce</b><code>_.reduce(list, iterator, memo, [context])</code> 278 <span class="alias">Aliases: <b>inject, foldl</b></span> 279 <br /> 280 Also known as <b>inject</b> and <b>foldl</b>, <b>reduce</b> boils down a 281 <b>list</b> of values into a single value. <b>Memo</b> is the initial state 282 of the reduction, and each successive step of it should be returned by 283 <b>iterator</b>. 284 </p> 285 <pre> 286var sum = _.reduce([1, 2, 3], function(memo, num){ return memo + num; }, 0); 287=> 6 288</pre> 289 290 <p id="reduceRight"> 291 <b class="header">reduceRight</b><code>_.reduceRight(list, iterator, memo, [context])</code> 292 <span class="alias">Alias: <b>foldr</b></span> 293 <br /> 294 The right-associative version of <b>reduce</b>. Delegates to the 295 JavaScript 1.8 version of <b>reduceRight</b>, if it exists. <b>Foldr</b> 296 is not as useful in JavaScript as it would be in a language with lazy 297 evaluation. 298 </p> 299 <pre> 300var list = [[0, 1], [2, 3], [4, 5]]; 301var flat = _.reduceRight(list, function(a, b) { return a.concat(b); }, []); 302=> [4, 5, 2, 3, 0, 1] 303</pre> 304 305 <p id="detect"> 306 <b class="header">detect</b><code>_.detect(list, iterator, [context])</code> 307 <br /> 308 Looks through each value in the <b>list</b>, returning the first one that 309 passes a truth test (<b>iterator</b>). The function returns as 310 soon as it finds an acceptable element, and doesn't traverse the 311 entire list. 312 </p> 313 <pre> 314var even = _.detect([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; }); 315=> 2 316</pre> 317 318 <p id="select"> 319 <b class="header">select</b><code>_.select(list, iterator, [context])</code> 320 <span class="alias">Alias: <b>filter</b></span> 321 <br /> 322 Looks through each value in the <b>list</b>, returning an array of all 323 the values that pass a truth test (<b>iterator</b>). Delegates to the 324 native <b>filter</b> method, if it exists. 325 </p> 326 <pre> 327var evens = _.select([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; }); 328=> [2, 4, 6] 329</pre> 330 331 <p id="reject"> 332 <b class="header">reject</b><code>_.reject(list, iterator, [context])</code> 333 <br /> 334 Returns the values in <b>list</b> without the elements that the truth 335 test (<b>iterator</b>) passes. The opposite of <b>select</b>. 336 </p> 337 <pre> 338var odds = _.reject([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; }); 339=> [1, 3, 5] 340</pre> 341 342 <p id="all"> 343 <b class="header">all</b><code>_.all(list, [iterator], [context])</code> 344 <span class="alias">Alias: <b>every</b></span> 345 <br /> 346 Returns <i>true</i> if all of the values in the <b>list</b> pass the <b>iterator</b> 347 truth test. If an <b>iterator</b> is not provided, the truthy value of 348 the element will be used instead. Delegates to the native method <b>every</b>, if 349 present. 350 </p> 351 <pre> 352_.all([true, 1, null, 'yes']); 353=> false 354</pre> 355 356 <p id="any"> 357 <b class="header">any</b><code>_.any(list, [iterator], [context])</code> 358 <span class="alias">Alias: <b>some</b></span> 359 <br /> 360 Returns <i>true</i> if any of the values in the <b>list</b> pass the 361 <b>iterator</b> truth test. Short-circuits and stops traversing the list 362 if a true element is found. Delegates to the native method <b>some</b>, 363 if present. 364 </p> 365 <pre> 366_.any([null, 0, 'yes', false]); 367=> true 368</pre> 369 370 <p id="include"> 371 <b class="header">include</b><code>_.include(list, value)</code> 372 <span class="alias">Alias: <b>contains</b></span> 373 <br /> 374 Returns <i>true</i> if the <b>value</b> is present in the <b>list</b>, using 375 <i>===</i> to test equality. Uses <b>indexOf</b> internally, if <b>list</b> 376 is an Array. 377 </p> 378 <pre> 379_.include([1, 2, 3], 3); 380=> true 381</pre> 382 383 <p id="invoke"> 384 <b class="header">invoke</b><code>_.invoke(list, methodName, [*arguments])</code> 385 <br /> 386 Calls the method named by <b>methodName</b> on each value in the <b>list</b>. 387 Any extra arguments passed to <b>invoke</b> will be forwarded on to the 388 method invocation. 389 </p> 390 <pre> 391_.invoke([[5, 1, 7], [3, 2, 1]], 'sort'); 392=> [[1, 5, 7], [1, 2, 3]] 393</pre> 394 395 <p id="pluck"> 396 <b class="header">pluck</b><code>_.pluck(list, propertyName)</code> 397 <br /> 398 An convenient version of what is perhaps the most common use-case for 399 <b>map</b>: extracting a list of property values. 400 </p> 401 <pre> 402var stooges = [{name : 'moe', age : 40}, {name : 'larry', age : 50}, {name : 'curly', age : 60}]; 403_.pluck(stooges, 'name'); 404=> ["moe", "larry", "curly"] 405</pre> 406 407 <p id="max"> 408 <b class="header">max</b><code>_.max(list, [iterator], [context])</code> 409 <br /> 410 Returns the maximum value in <b>list</b>. If <b>iterator</b> is passed, 411 it will be used on each value to generate the criterion by which the 412 value is ranked. 413 </p> 414 <pre> 415var stooges = [{name : 'moe', age : 40}, {name : 'larry', age : 50}, {name : 'curly', age : 60}]; 416_.max(stooges, function(stooge){ return stooge.age; }); 417=> {name : 'curly', age : 60}; 418</pre> 419 420 <p id="min"> 421 <b class="header">min</b><code>_.min(list, [iterator], [context])</code> 422 <br /> 423 Returns the minimum value in <b>list</b>. If <b>iterator</b> is passed, 424 it will be used on each value to generate the criterion by which the 425 value is ranked. 426 </p> 427 <pre> 428var numbers = [10, 5, 100, 2, 1000]; 429_.min(numbers); 430=> 2 431</pre> 432 433 <p id="sortBy"> 434 <b class="header">sortBy</b><code>_.sortBy(list, iterator, [context])</code> 435 <br /> 436 Returns a sorted <b>list</b>, ranked by the results of running each 437 value through <b>iterator</b>. 438 </p> 439 <pre> 440_.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); }); 441=> [5, 4, 6, 3, 1, 2] 442</pre> 443 444 <p id="sortedIndex"> 445 <b class="header">sortedIndex</b><code>_.sortedIndex(list, value, [iterator])</code> 446 <br /> 447 Uses a binary search to determine the index at which the <b>value</b> 448 <i>should</i> be inserted into the <b>list</b> in order to maintain the <b>list</b>'s 449 sorted order. If an <b>iterator</b> is passed, it will be used to compute 450 the sort ranking of each value. 451 </p> 452 <pre> 453_.sortedIndex([10, 20, 30, 40, 50], 35); 454=> 3 455</pre> 456 457 <p id="toArray"> 458 <b class="header">toArray</b><code>_.toArray(list)</code> 459 <br /> 460 Converts the <b>list</b> (anything that can be iterated over), into a 461 real Array. Useful for transmuting the <b>arguments</b> object. 462 </p> 463 <pre> 464(function(){ return _.toArray(arguments).slice(0); })(1, 2, 3); 465=> [1, 2, 3] 466</pre> 467 468 <p id="size"> 469 <b class="header">size</b><code>_.size(list)</code> 470 <br /> 471 Return the number of values in the <b>list</b>. 472 </p> 473 <pre> 474_.size({one : 1, two : 2, three : 3}); 475=> 3 476</pre> 477 478 <h2>Array Functions</h2> 479 480 <p> 481 <i>Note: All array functions will also work on the <b>arguments</b> object.</i> 482 </p> 483 484 <p id="first"> 485 <b class="header">first</b><code>_.first(array, [n])</code> 486 <span class="alias">Alias: <b>head</b></span> 487 <br /> 488 Returns the first element of an <b>array</b>. Passing <b>n</b> will 489 return the first <b>n</b> elements of the array. 490 </p> 491 <pre> 492_.first([5, 4, 3, 2, 1]); 493=> 5 494</pre> 495 496 <p id="rest"> 497 <b class="header">rest</b><code>_.rest(array, [index])</code> 498 <span class="alias">Alias: <b>tail</b></span> 499 <br /> 500 Returns the <b>rest</b> of the elements in an array. Pass an <b>index</b> 501 to return the values of the array from that index onward. 502 </p> 503 <pre> 504_.rest([5, 4, 3, 2, 1]); 505=> [4, 3, 2, 1] 506</pre> 507 508 <p id="last"> 509 <b class="header">last</b><code>_.last(array)</code> 510 <br /> 511 Returns the last element of an <b>array</b>. 512 </p> 513 <pre> 514_.last([5, 4, 3, 2, 1]); 515=> 1 516</pre> 517 518 <p id="compact"> 519 <b class="header">compact</b><code>_.compact(array)</code> 520 <br /> 521 Returns a copy of the <b>array</b> with all falsy values removed. 522 In JavaScript, <i>false</i>, <i>null</i>, <i>0</i>, <i>""</i>, 523 <i>undefined</i> and <i>NaN</i> are all falsy. 524 </p> 525 <pre> 526_.compact([0, 1, false, 2, '', 3]); 527=> [1, 2, 3] 528</pre> 529 530 <p id="flatten"> 531 <b class="header">flatten</b><code>_.flatten(array)</code> 532 <br /> 533 Flattens a nested <b>array</b> (the nesting can be to any depth). 534 </p> 535 <pre> 536_.flatten([1, [2], [3, [[[4]]]]]); 537=> [1, 2, 3, 4]; 538</pre> 539 540 <p id="without"> 541 <b class="header">without</b><code>_.without(array, [*values])</code> 542 <br /> 543 Returns a copy of the <b>array</b> with all instances of the <b>values</b> 544 removed. <i>===</i> is used for the equality test. 545 </p> 546 <pre> 547_.without([1, 2, 1, 0, 3, 1, 4], 0, 1); 548=> [2, 3, 4] 549</pre> 550 551 <p id="uniq"> 552 <b class="header">uniq</b><code>_.uniq(array, [isSorted])</code> 553 <span class="alias">Alias: <b>unique</b></span> 554 <br /> 555 Produces a duplicate-free version of the <b>array</b>, using <i>===</i> to test 556 object equality. If you know in advance that the <b>array</b> is sorted, 557 passing <i>true</i> for <b>isSorted</b> will run a much faster algorithm. 558 </p> 559 <pre> 560_.uniq([1, 2, 1, 3, 1, 4]); 561=> [1, 2, 3, 4] 562</pre> 563 564 <p id="intersect"> 565 <b class="header">intersect</b><code>_.intersect(*arrays)</code> 566 <br /> 567 Computes the list of values that are the intersection of all the <b>arrays</b>. 568 Each value in the result is present in each of the <b>arrays</b>. 569 </p> 570 <pre> 571_.intersect([1, 2, 3], [101, 2, 1, 10], [2, 1]); 572=> [1, 2] 573</pre> 574 575 <p id="zip"> 576 <b class="header">zip</b><code>_.zip(*arrays)</code> 577 <br /> 578 Merges together the values of each of the <b>arrays</b> with the 579 values at the corresponding position. Useful when you have separate 580 data sources that are coordinated through matching array indexes. 581 If you're working with a matrix of nested arrays, <b>zip.apply</b> 582 can transpose the matrix in a similar fashion. 583 </p> 584 <pre> 585_.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]); 586=> [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]] 587</pre> 588 589 <p id="indexOf"> 590 <b class="header">indexOf</b><code>_.indexOf(array, value, [isSorted])</code> 591 <br /> 592 Returns the index at which <b>value</b> can be found in the <b>array</b>, 593 or <i>-1</i> if value is not present in the <b>array</b>. Uses the native 594 <b>indexOf</b> function unless it's missing. If you're working with a 595 large array, and you know that the array is already sorted, pass <tt>true</tt> 596 for <b>isSorted</b> to use a faster binary search. 597 </p> 598 <pre> 599_.indexOf([1, 2, 3], 2); 600=> 1 601</pre> 602 603 <p id="lastIndexOf"> 604 <b class="header">lastIndexOf</b><code>_.lastIndexOf(array, value)</code> 605 <br /> 606 Returns the index of the last occurrence of <b>value</b> in the <b>array</b>, 607 or <i>-1</i> if value is not present. Uses the native <b>lastIndexOf</b> 608 function if possible. 609 </p> 610 <pre> 611_.lastIndexOf([1, 2, 3, 1, 2, 3], 2); 612=> 4 613</pre> 614 615 <p id="range"> 616 <b class="header">range</b><code>_.range([start], stop, [step])</code> 617 <br /> 618 A function to create flexibly-numbered lists of integers, handy for 619 <tt>each</tt> and <tt>map</tt> loops. <b>start</b>, if omitted, defaults 620 to <i>0</i>; <b>step</b> defaults to <i>1</i>. Returns a list of integers 621 from <b>start</b> to <b>stop</b>, incremented (or decremented) by <b>step</b>, 622 exclusive. 623 </p> 624 <pre> 625_.range(10); 626=> [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 627_.range(1, 11); 628=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] 629_.range(0, 30, 5); 630=> [0, 5, 10, 15, 20, 25] 631_.range(0, -10, -1); 632=> [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] 633_.range(0); 634=> [] 635</pre> 636 637 <h2>Function (uh, ahem) Functions</h2> 638 639 <p id="bind"> 640 <b class="header">bind</b><code>_.bind(function, object, [*arguments])</code> 641 <br /> 642 Bind a <b>function</b> to an <b>object</b>, meaning that whenever 643 the function is called, the value of <i>this</i> will be the <b>object</b>. 644 Optionally, bind <b>arguments</b> to the <b>function</b> to pre-fill them, 645 also known as <b>currying</b>. 646 </p> 647 <pre> 648var func = function(greeting){ return greeting + ': ' + this.name }; 649func = _.bind(func, {name : 'moe'}, 'hi'); 650func(); 651=> 'hi: moe' 652</pre> 653 654 <p id="bindAll"> 655 <b class="header">bindAll</b><code>_.bindAll(object, [*methodNames])</code> 656 <br /> 657 Binds a number of methods on the <b>object</b>, specified by 658 <b>methodNames</b>, to be run in the context of that object whenever they 659 are invoked. Very handy for binding functions that are going to be used 660 as event handlers, which would otherwise be invoked with a fairly useless 661 <i>this</i>. If no <b>methodNames</b> are provided, all of the object's 662 function properties will be bound to it. 663 </p> 664 <pre> 665var buttonView = { 666 label : 'underscore', 667 onClick : function(){ alert('clicked: ' + this.label); }, 668 onHover : function(){ console.log('hovering: ' + this.label); } 669}; 670_.bindAll(buttonView); 671jQuery('#underscore_button').bind('click', buttonView.onClick); 672=> When the button is clicked, this.label will have the correct value... 673</pre> 674 675 <p id="memoize"> 676 <b class="header">memoize</b><code>_.memoize(function, [hashFunction])</code> 677 <br /> 678 Memoizes a given <b>function</b> by caching the computed result. Useful 679 for speeding up slow-running computations. If passed an optional 680 <b>hashFunction</b>, it will be used to compute the hash key for storing 681 the result, based on the arguments to the original function. The default 682 <b>hashFunction</b> just uses the first argument to the memoized function 683 as the key. 684 </p> 685 <pre> 686var fibonacci = function(n) { 687 return n < 2 ? n : fibonacci(n - 1) + fibonacci(n - 2); 688}; 689var fastFibonacci = _.memoize(fibonacci); 690</pre> 691 692 <p id="delay"> 693 <b class="header">delay</b><code>_.delay(function, wait, [*arguments])</code> 694 <br /> 695 Much like <b>setTimeout</b>, invokes <b>function</b> after <b>wait</b> 696 milliseconds. If you pass the optional <b>arguments</b>, they will be 697 forwarded on to the <b>function</b> when it is invoked. 698 </p> 699 <pre> 700var log = _.bind(console.log, console); 701_.delay(log, 1000, 'logged later'); 702=> 'logged later' // Appears after one second. 703</pre> 704 705 <p id="defer"> 706 <b class="header">defer</b><code>_.defer(function)</code> 707 <br /> 708 Defers invoking the <b>function</b> until the current call stack has cleared, 709 similar to using <b>setTimeout</b> with a delay of 0. Useful for performing 710 expensive computations or HTML rendering in chunks without blocking the UI thread 711 from updating. 712 </p> 713 <pre> 714_.defer(function(){ alert('deferred'); }); 715// Returns from the function before the alert runs. 716</pre> 717 718 <p id="throttle"> 719 <b class="header">throttle</b><code>_.throttle(function, wait)</code> 720 <br /> 721 Returns a throttled version of the function, that, when invoked repeatedly, 722 will only actually call the wrapped function at most once per every <b>wait</b> 723 milliseconds. Useful for rate-limiting events that occur faster than you 724 can keep up with. 725 </p> 726 <pre> 727var throttled = _.throttle(updatePosition, 100); 728$(window).scroll(throttled); 729</pre> 730 731 <p id="debounce"> 732 <b class="header">debounce</b><code>_.debounce(function, wait)</code> 733 <br /> 734 Repeated calls to a debounced function will postpone it's execution 735 until after <b>wait</b> milliseconds have elapsed. Useful for implementing 736 behavior that should only happen <i>after</i> the input has stopped arriving. 737 For example: rendering a preview of a Markdown comment, recalculating a 738 layout after the window has stopped being resized... 739 </p> 740 <pre> 741var lazyLayout = _.debounce(calculateLayout, 300); 742$(window).resize(lazyLayout); 743</pre> 744 745 <p id="once"> 746 <b class="header">once</b><code>_.once(function)</code> 747 <br /> 748 Creates a version of the function that can only be called one time. 749 Repeated calls to the modified function will have no effect, returning 750 the value from the original call. Useful for initialization functions, 751 instead of having to set a boolean flag and then check it later. 752 </p> 753 <pre> 754var initialize = _.once(createApplication); 755initialize(); 756initialize(); 757// Application is only created once. 758</pre> 759 760 <p id="after"> 761 <b class="header">after</b><code>_.after(count, function)</code> 762 <br /> 763 Creates a version of the function that will only be run after first 764 being called <b>count</b> times. Useful for grouping asynchronous responses, 765 where you want to be sure that all the async calls have finished, before 766 proceeding. 767 </p> 768 <pre> 769var renderNotes = _.after(notes.length, render); 770_.each(notes, function(note) { 771 note.asyncSave({success: renderNotes}); 772}); 773// renderNotes is run once, after all notes have saved. 774</pre> 775 776 <p id="wrap"> 777 <b class="header">wrap</b><code>_.wrap(function, wrapper)</code> 778 <br /> 779 Wraps the first <b>function</b> inside of the <b>wrapper</b> function, 780 passing it as the first argument. This allows the <b>wrapper</b> to 781 execute code before and after the <b>function</b> runs, adjust the arguments, 782 and execute it conditionally. 783 </p> 784 <pre> 785var hello = function(name) { return "hello: " + name; }; 786hello = _.wrap(hello, function(func) { 787 return "before, " + func("moe") + ", after"; 788}); 789hello(); 790=> 'before, hello: moe, after' 791</pre> 792 793 <p id="compose"> 794 <b class="header">compose</b><code>_.compose(*functions)</code> 795 <br /> 796 Returns the composition of a list of <b>functions</b>, where each function 797 consumes the return value of the function that follows. In math terms, 798 composing the functions <i>f()</i>, <i>g()</i>, and <i>h()</i> produces 799 <i>f(g(h()))</i>. 800 </p> 801 <pre> 802var greet = function(name){ return "hi: " + name; }; 803var exclaim = function(statement){ return statement + "!"; }; 804var welcome = _.compose(exclaim, greet); 805welcome('moe'); 806=> 'hi: moe!' 807</pre> 808 809 <h2>Object Functions</h2> 810 811 <p id="keys"> 812 <b class="header">keys</b><code>_.keys(object)</code> 813 <br /> 814 Retrieve all the names of the <b>object</b>'s properties. 815 </p> 816 <pre> 817_.keys({one : 1, two : 2, three : 3}); 818=> ["one", "two", "three"] 819</pre> 820 821 <p id="values"> 822 <b class="header">values</b><code>_.values(object)</code> 823 <br /> 824 Return all of the values of the <b>object</b>'s properties. 825 </p> 826 <pre> 827_.values({one : 1, two : 2, three : 3}); 828=> [1, 2, 3] 829</pre> 830 831 <p id="functions"> 832 <b class="header">functions</b><code>_.functions(object)</code> 833 <span class="alias">Alias: <b>methods</b></span> 834 <br /> 835 Returns a sorted list of the names of every method in an object — 836 that is to say, the name of every function property of the object. 837 </p> 838 <pre> 839_.functions(_); 840=> ["all", "any", "bind", "bindAll", "clone", "compact", "compose" ... 841</pre> 842 843 <p id="extend"> 844 <b class="header">extend</b><code>_.extend(destination, *sources)</code> 845 <br /> 846 Copy all of the properties in the <b>source</b> objects over to the 847 <b>destination</b> object. It's in-order, to the last source will override 848 properties of the same name in previous arguments. 849 </p> 850 <pre> 851_.extend({name : 'moe'}, {age : 50}); 852=> {name : 'moe', age : 50} 853</pre> 854 855 <p id="defaults"> 856 <b class="header">defaults</b><code>_.defaults(object, *defaults)</code> 857 <br /> 858 Fill in missing properties in <b>object</b> with default values from the 859 <b>defaults</b> objects. As soon as the property is filled, further defaults 860 will have no effect. 861 </p> 862 <pre> 863var iceCream = {flavor : "chocolate"}; 864_.defaults(iceCream, {flavor : "vanilla", sprinkles : "lots"}); 865=> {flavor : "chocolate", sprinkles : "lots"} 866</pre> 867 868 <p id="clone"> 869 <b class="header">clone</b><code>_.clone(object)</code> 870 <br /> 871 Create a shallow-copied clone of the <b>object</b>. Any nested objects 872 or arrays will be copied by reference, not duplicated. 873 </p> 874 <pre> 875_.clone({name : 'moe'}); 876=> {name : 'moe'}; 877</pre> 878 879 <p id="tap"> 880 <b class="header">tap</b><code>_.tap(object, interceptor)</code> 881 <br /> 882 Invokes <b>interceptor</b> with the <b>object</b>, and then returns <b>object</b>. 883 The primary purpose of this method is to "tap into" a method chain, in order to perform operations on intermediate results within the chain. 884 </p> 885 <pre> 886_([1,2,3,200]).chain(). 887 select(function(num) { return num % 2 == 0; }). 888 tap(console.log). 889 map(function(num) { return num * num }). 890 value(); 891=> [2, 200] 892=> [4, 40000] 893</pre> 894 895 <p id="isEqual"> 896 <b class="header">isEqual</b><code>_.isEqual(object, other)</code> 897 <br /> 898 Performs an optimized deep comparison between the two objects, to determine 899 if they should be considered equal. 900 </p> 901 <pre> 902var moe = {name : 'moe', luckyNumbers : [13, 27, 34]}; 903var clone = {name : 'moe', luckyNumbers : [13, 27, 34]}; 904moe == clone; 905=> false 906_.isEqual(moe, clone); 907=> true 908</pre> 909 910 <p id="isEmpty"> 911 <b class="header">isEmpty</b><code>_.isEmpty(object)</code> 912 <br /> 913 Returns <i>true</i> if <b>object</b> contains no values. 914 </p> 915 <pre> 916_.isEmpty([1, 2, 3]); 917=> false 918_.isEmpty({}); 919=> true 920</pre> 921 922 <p id="isElement"> 923 <b class="header">isElement</b><code>_.isElement(object)</code> 924 <br /> 925 Returns <i>true</i> if <b>object</b> is a DOM element. 926 </p> 927 <pre> 928_.isElement(jQuery('body')[0]); 929=> true 930</pre> 931 932 <p id="isArray"> 933 <b class="header">isArray</b><code>_.isArray(object)</code> 934 <br /> 935 Returns <i>true</i> if <b>object</b> is an Array. 936 </p> 937 <pre> 938(function(){ return _.isArray(arguments); })(); 939=> false 940_.isArray([1,2,3]); 941=> true 942</pre> 943 944 <p id="isArguments"> 945 <b class="header">isArguments</b><code>_.isArguments(object)</code> 946 <br /> 947 Returns <i>true</i> if <b>object</b> is an Arguments object. 948 </p> 949 <pre> 950(function(){ return _.isArguments(arguments); })(1, 2, 3); 951=> true 952_.isArguments([1,2,3]); 953=> false 954</pre> 955 956 <p id="isFunction"> 957 <b class="header">isFunction</b><code>_.isFunction(object)</code> 958 <br /> 959 Returns <i>true</i> if <b>object</b> is a Function. 960 </p> 961 <pre> 962_.isFunction(alert); 963=> true 964</pre> 965 966 <p id="isString"> 967 <b class="header">isString</b><code>_.isString(object)</code> 968 <br /> 969 Returns <i>true</i> if <b>object</b> is a String. 970 </p> 971 <pre> 972_.isString("moe"); 973=> true 974</pre> 975 976 <p id="isNumber"> 977 <b class="header">isNumber</b><code>_.isNumber(object)</code> 978 <br /> 979 Returns <i>true</i> if <b>object</b> is a Number. 980 </p> 981 <pre> 982_.isNumber(8.4 * 5); 983=> true 984</pre> 985 986 <p id="isBoolean"> 987 <b class="header">isBoolean</b><code>_.isBoolean(object)</code> 988 <br /> 989 Returns <i>true</i> if <b>object</b> is either <i>true</i> or <i>false</i>. 990 </p> 991 <pre> 992_.isBoolean(null); 993=> false 994</pre> 995 996 <p id="isDate"> 997 <b class="header">isDate</b><code>_.isDate(object)</code> 998 <br /> 999 Returns <i>true</i> if <b>object</b> is a Date. 1000 </p> 1001 <pre> 1002_.isDate(new Date()); 1003=> true 1004</pre> 1005 1006 <p id="isRegExp"> 1007 <b class="header">isRegExp</b><code>_.isRegExp(object)</code> 1008 <br /> 1009 Returns <i>true</i> if <b>object</b> is a RegExp. 1010 </p> 1011 <pre> 1012_.isRegExp(/moe/); 1013=> true 1014</pre> 1015 1016 <p id="isNaN"> 1017 <b class="header">isNaN</b><code>_.isNaN(object)</code> 1018 <br /> 1019 Returns <i>true</i> if <b>object</b> is <i>NaN</i>.<br /> Note: this is not 1020 the same as the native <b>isNaN</b> function, which will also return 1021 true if the variable is <i>undefined</i>. 1022 </p> 1023 <pre> 1024_.isNaN(NaN); 1025=> true 1026isNaN(undefined); 1027=> true 1028_.isNaN(undefined); 1029=> false 1030</pre> 1031 1032 <p id="isNull"> 1033 <b class="header">isNull</b><code>_.isNull(object)</code> 1034 <br /> 1035 Returns <i>true</i> if the value of <b>object</b> is <i>null</i>. 1036 </p> 1037 <pre> 1038_.isNull(null); 1039=> true 1040_.isNull(undefined); 1041=> false 1042</pre> 1043 1044 <p id="isUndefined"> 1045 <b class="header">isUndefined</b><code>_.isUndefined(variable)</code> 1046 <br /> 1047 Returns <i>true</i> if <b>variable</b> is <i>undefined</i>. 1048 </p> 1049 <pre> 1050_.isUndefined(window.missingVariable); 1051=> true 1052</pre> 1053 1054 <h2>Utility Functions</h2> 1055 1056 <p id="noConflict"> 1057 <b class="header">noConflict</b><code>_.noConflict()</code> 1058 <br /> 1059 Give control of the "_" variable back to its previous owner. Returns 1060 a reference to the <b>Underscore</b> object. 1061 </p> 1062 <pre> 1063var underscore = _.noConflict();</pre> 1064 1065 <p id="identity"> 1066 <b class="header">identity</b><code>_.identity(value)</code> 1067 <br /> 1068 Returns the same value that is used as the argument. In math: 1069 <tt>f(x) = x</tt><br /> 1070 This function looks useless, but is used throughout Underscore as 1071 a default iterator. 1072 </p> 1073 <pre> 1074var moe = {name : 'moe'}; 1075moe === _.identity(moe); 1076=> true</pre> 1077 1078 <p id="times"> 1079 <b class="header">times</b><code>_.times(n, iterator)</code> 1080 <br /> 1081 Invokes the given iterator function <b>n</b> times. 1082 </p> 1083 <pre> 1084_(3).times(function(){ genie.grantWish(); });</pre> 1085 1086 <p id="mixin"> 1087 <b class="header">mixin</b><code>_.mixin(object)</code> 1088 <br /> 1089 Allows you to extend Underscore with your own utility functions. Pass 1090 a hash of <tt>{name: function}</tt> definitions to have your functions 1091 added to the Underscore object, as well as the OOP wrapper. 1092 </p> 1093 <pre> 1094_.mixin({ 1095 capitalize : function(string) { 1096 return string.charAt(0).toUpperCase() + string.substring(1).toLowerCase(); 1097 } 1098}); 1099_("fabio").capitalize(); 1100=> "Fabio" 1101</pre> 1102 1103 <p id="uniqueId"> 1104 <b class="header">uniqueId</b><code>_.uniqueId([prefix])</code> 1105 <br /> 1106 Generate a globally-unique id for client-side models or DOM elements 1107 that need one. If <b>prefix</b> is passed, the id will be appended to it. 1108 </p> 1109 <pre> 1110_.uniqueId('contact_'); 1111=> 'contact_104'</pre> 1112 1113 <p id="template"> 1114 <b class="header">template</b><code>_.template(templateString, [context])</code> 1115 <br /> 1116 Compiles JavaScript templates into functions that can be evaluated 1117 for rendering. Useful for rendering complicated bits of HTML from JSON 1118 data sources. Template functions can both interpolate variables, using<br /> 1119 <tt><%= … %></tt>, as well as execute arbitrary JavaScript code, with 1120 <tt><% … %></tt>. When you evaluate a template function, pass in a 1121 <b>context</b> object that has properties corresponding to the template's free 1122 variables. If you're writing a one-off, you can pass the <b>context</b> 1123 object as the second parameter to <b>template</b> in order to render 1124 immediately instead of returning a template function. 1125 </p> 1126 <pre> 1127var compiled = _.template("hello: <%= name %>"); 1128compiled({name : 'moe'}); 1129=> "hello: moe" 1130 1131var list = "<% _.each(people, function(name) { %> <li><%= name %></li> <% }); %>"; 1132_.template(list, {people : ['moe', 'curly', 'larry']}); 1133=> "<li>moe</li><li>curly</li><li>larry</li>"</pre> 1134 1135 <p> 1136 You can also use <tt>print</tt> from within JavaScript code. This is 1137 sometimes more convenient than using <tt><%= ... %></tt>. 1138 </p> 1139 1140 <pre> 1141var compiled = _.template("<% print('Hello ' + epithet); %>"); 1142compiled({epithet: "stooge"}); 1143=> "Hello stooge."</pre> 1144 1145 <p> 1146 If ERB-style delimiters aren't your cup of tea, you can change Underscore's 1147 template settings to use different symbols to set off interpolated code. 1148 Define an <b>interpolate</b> regex, and an (optional) <b>evaluate</b> regex 1149 to match expressions that should be inserted and evaluated, respectively. 1150 If no <b>evaluate</b> regex is provided, your templates will only be 1151 capable of interpolating values. 1152 For example, to perform 1153 <a href="http://github.com/janl/mustache.js#readme">Mustache.js</a> 1154 style templating: 1155 </p> 1156 1157 <pre> 1158_.templateSettings = { 1159 interpolate : /\{\{(.+?)\}\}/g 1160}; 1161 1162var template = _.template("Hello {{ name }}!"); 1163template({name : "Mustache"}); 1164=> "Hello Mustache!"</pre> 1165 1166 <h2>Chaining</h2> 1167 1168 <p id="chain"> 1169 <b class="header">chain</b><code>_(obj).chain()</code> 1170 <br /> 1171 Returns a wrapped object. Calling methods on this object will continue 1172 to return wrapped objects until <tt>value</tt> is used. ( 1173 <a href="#styles">A more realistic example.</a>) 1174 </p> 1175 <pre> 1176var stooges = [{name : 'curly', age : 25}, {name : 'moe', age : 21}, {name : 'larry', age : 23}]; 1177var youngest = _(stooges).chain() 1178 .sortBy(function(stooge){ return stooge.age; }) 1179 .map(function(stooge){ return stooge.name + ' is ' + stooge.age; }) 1180 .first() 1181 .value(); 1182=> "moe is 21" 1183</pre> 1184 1185 <p id="value"> 1186 <b class="header">value</b><code>_(obj).value()</code> 1187 <br /> 1188 Extracts the value of a wrapped object. 1189 </p> 1190 <pre> 1191_([1, 2, 3]).value(); 1192=> [1, 2, 3] 1193</pre> 1194 1195 <h2 id="duck_typing">Duck Typing</h2> 1196 1197 <p> 1198 The <b>isType</b> (<tt>isArray</tt>, <tt>isFunction</tt>, <tt>isString</tt> ...) family of type-checking 1199 functions use property detection to do their work, which, although 1200 orders of magnitude faster than the alternative, isn't entirely safe when dealing 1201 with objects that are used as hashes, where arbitrary strings are being 1202 set for the keys. It's entirely possible for an object to masquerade as 1203 another type, if you're setting properties with names like "concat" and 1204 "charCodeAt". So be aware. 1205 </p> 1206 1207 1208 <h2>Links & Suggested Reading</h2> 1209 1210 <p> 1211 <a href="http://mirven.github.com/underscore.lua/">Underscore.lua</a>, 1212 a Lua port of the functions that are applicable in both languages. 1213 Includes OOP-wrapping and chaining. 1214 The <a href="http://github.com/mirven/underscore.lua">source</a> is 1215 available on GitHub. 1216 </p> 1217 1218 <p> 1219 <a href="https://github.com/edtsech/underscore.string">Underscore.string</a>, 1220 an Underscore extension that adds functions for string-manipulation: 1221 <tt>trim</tt>, <tt>startsWith</tt>, <tt>contains</tt>, <tt>capitalize</tt>, 1222 <tt>reverse</tt>, <tt>sprintf</tt>, and more. 1223 </p> 1224 1225 <p> 1226 Ruby's <a href="http://ruby-doc.org/core/classes/Enumerable.html">Enumerable</a> module. 1227 </p> 1228 1229 <p> 1230 <a href="http://www.prototypejs.org/">Prototype.js</a>, which provides 1231 JavaScript with collection functions in the manner closest to Ruby's Enumerable. 1232 </p> 1233 1234 <p> 1235 Oliver Steele's 1236 <a href="http://osteele.com/sources/javascript/functional/">Functional JavaScript</a>, 1237 which includes comprehensive higher-order function support as well as string lambdas. 1238 </p> 1239 1240 <p> 1241 Python's <a href="http://docs.python.org/library/itertools.html">itertools</a>. 1242 </p> 1243 1244 <h2 id="changelog">Change Log</h2> 1245 1246 <p> 1247 <b class="header">1.1.6</b> — <small><i>April 18, 2011</i></small><br /> 1248 Added <tt>_.after</tt>, which will return a function that only runs after 1249 first being called a specified number of times. 1250 <tt>_.invoke</tt> can now take a direct function reference. 1251 <tt>_.every</tt> now requires an iterator function to be passed, which 1252 mirrors the ECMA5 API. 1253 <tt>_.extend</tt> no longer copies keys when the value is undefined. 1254 <tt>_.bind</tt> now errors when trying to bind an undefined value. 1255 </p> 1256 1257 <p> 1258 <b class="header">1.1.5</b> — <small><i>Mar 20, 2011</i></small><br /> 1259 Added an <tt>_.defaults</tt> function, for use merging together JS objects 1260 representing default options. 1261 Added an <tt>_.once</tt> function, for manufacturing functions that should 1262 only ever execute a single time. 1263 <tt>_.bind</tt> now delegates to the native ECMAScript 5 version, 1264 where available. 1265 <tt>_.keys</tt> now throws an error when used on non-Object values, as in 1266 ECMAScript 5. 1267 Fixed a bug with <tt>_.keys</tt> when used over sparse arrays. 1268 </p> 1269 1270 <p> 1271 <b class="header">1.1.4</b> — <small><i>Jan 9, 2011</i></small><br /> 1272 Improved compliance with ES5's Array methods when passing <tt>null</tt> 1273 as a value. <tt>_.wrap</tt> now correctly sets <tt>this</tt> for the 1274 wrapped function. <tt>_.indexOf</tt> now takes an optional flag for 1275 finding the insertion index in an array that is guaranteed to already 1276 be sorted. Avoiding the use of <tt>.callee</tt>, to allow <tt>_.isArray</tt> 1277 to work properly in ES5's strict mode. 1278 </p> 1279 1280 <p> 1281 <b class="header">1.1.3</b> — <small><i>Dec 1, 2010</i></small><br /> 1282 In CommonJS, Underscore may now be required with just: <br /> 1283 <tt>var _ = require("underscore")</tt>. 1284 Added <tt>_.throttle</tt> and <tt>_.debounce</tt> functions. 1285 Removed <tt>_.breakLoop</tt>, in favor of an ECMA5-style un-<i>break</i>-able 1286 each implementation — this removes the try/catch, and you'll now have 1287 better stack traces for exceptions that are thrown within an Underscore iterator. 1288 Improved the <b>isType</b> family of functions for better interoperability 1289 with Internet Explorer host objects. 1290 <tt>_.template</tt> now correctly escapes backslashes in templates. 1291 Improved <tt>_.reduce</tt> compatibility with the ECMA5 version: 1292 if you don't pass an initial value, the first item in the collection is used. 1293 <tt>_.each</tt> no longer returns the iterated collection, for improved 1294 consistency with ES5's <tt>forEach</tt>. 1295 </p> 1296 1297 <p> 1298 <b class="header">1.1.2</b><br /> 1299 Fixed <tt>_.contains</tt>, which was mistakenly pointing at 1300 <tt>_.intersect</tt> instead of <tt>_.include</tt>, like it should 1301 have been. Added <tt>_.unique</tt> as an alias for <tt>_.uniq</tt>. 1302 </p> 1303 1304 <p> 1305 <b class="header">1.1.1</b><br /> 1306 Improved the speed of <tt>_.template</tt>, and its handling of multiline 1307 interpolations. Ryan Tenney contributed optimizations to many Underscore 1308 functions. An annotated version of the source code is now available. 1309 </p> 1310 1311 <p> 1312 <b class="header">1.1.0</b><br /> 1313 The method signature of <tt>_.reduce</tt> has been changed to match 1314 the ECMAScript 5 signature, instead of the Ruby/Prototype.js version. 1315 This is a backwards-incompatible change. <tt>_.template</tt> may now be 1316 called with no arguments, and preserves whitespace. <tt>_.contains</tt> 1317 is a new alias for <tt>_.include</tt>. 1318 </p> 1319 1320 <p> 1321 <b class="header">1.0.4</b><br /> 1322 <a href="http://themoell.com/">Andri Möll</a> contributed the <tt>_.memoize</tt> 1323 function, which can be used to speed up expensive repeated computations 1324 by caching the results. 1325 </p> 1326 1327 <p> 1328 <b class="header">1.0.3</b><br /> 1329 Patch that makes <tt>_.isEqual</tt> return <tt>false</tt> if any property 1330 of the compared object has a <tt>NaN</tt> value. Technically the correct 1331 thing to do, but of questionable semantics. Watch out for NaN comparisons. 1332 </p> 1333 1334 <p> 1335 <b class="header">1.0.2</b><br /> 1336 Fixes <tt>_.isArguments</tt> in recent versions of Opera, which have 1337 arguments objects as real Arrays. 1338 </p> 1339 1340 <p> 1341 <b class="header">1.0.1</b><br /> 1342 Bugfix for <tt>_.isEqual</tt>, when comparing two objects with the same 1343 number of undefined keys, but with different names. 1344 </p> 1345 1346 <p> 1347 <b class="header">1.0.0</b><br /> 1348 Things have been stable for many months now, so Underscore is now 1349 considered to be out of beta, at <b>1.0</b>. Improvements since <b>0.6</b> 1350 include <tt>_.isBoolean</tt>, and the ability to have <tt>_.extend</tt> 1351 take multiple source objects. 1352 </p> 1353 1354 <p> 1355 <b class="header">0.6.0</b><br /> 1356 Major release. Incorporates a number of 1357 <a href="http://github.com/ratbeard">Mile Frawley's</a> refactors for 1358 safer duck-typing on collection functions, and cleaner internals. A new 1359 <tt>_.mixin</tt> method that allows you to extend Underscore with utility 1360 functions of your own. Added <tt>_.times</tt>, which works the same as in 1361 Ruby or Prototype.js. Native support for ECMAScript 5's <tt>Array.isArray</tt>, 1362 and <tt>Object.keys</tt>. 1363 </p> 1364 1365 <p> 1366 <b class="header">0.5.8</b><br /> 1367 Fixed Underscore's collection functions to work on 1368 <a href="https://developer.mozilla.org/En/DOM/NodeList">NodeLists</a> and 1369 <a href="https://developer.mozilla.org/En/DOM/HTMLCollection">HTMLCollections</a> 1370 once more, thanks to 1371 <a href="http://github.com/jmtulloss">Justin Tulloss</a>. 1372 </p> 1373 1374 <p> 1375 <b class="header">0.5.7</b><br /> 1376 A safer implementation of <tt>_.isArguments</tt>, and a 1377 faster <tt>_.isNumber</tt>,<br />thanks to 1378 <a href="http://jedschmidt.com/">Jed Schmidt</a>. 1379 </p> 1380 1381 <p> 1382 <b class="header">0.5.6</b><br /> 1383 Customizable delimiters for <tt>_.template</tt>, contributed by 1384 <a href="http://github.com/iamnoah">Noah Sloan</a>. 1385 </p> 1386 1387 <p> 1388 <b class="header">0.5.5</b><br /> 1389 Fix for a bug in MobileSafari's OOP-wrapper, with the arguments object. 1390 </p> 1391 1392 <p> 1393 <b class="header">0.5.4</b><br /> 1394 Fix for multiple single quotes within a template string for 1395 <tt>_.template</tt>. See: 1396 <a href="http://www.west-wind.com/Weblog/posts/509108.aspx">Rick Strahl's blog post</a>. 1397 </p> 1398 1399 <p> 1400 <b class="header">0.5.2</b><br /> 1401 New implementations of <tt>isArray</tt>, <tt>isDate</tt>, <tt>isFunction</tt>, 1402 <tt>isNumber</tt>, <tt>isRegExp</tt>, and <tt>isString</tt>, thanks to 1403 a suggestion from 1404 <a href="http://www.broofa.com/">Robert Kieffer</a>. 1405 Instead of doing <tt>Object#toString</tt> 1406 comparisons, they now check for expected properties, which is less safe, 1407 but more than an order of magnitude faster. Most other Underscore 1408 functions saw minor speed improvements as a result. 1409 <a href="http://dolzhenko.org/">Evgeniy Dolzhenko</a> 1410 contributed <tt>_.tap</tt>, 1411 <a href="http://ruby-doc.org/core-1.9/classes/Object.html#M000191">similar to Ruby 1.9's</a>, 1412 which is handy for injecting side effects (like logging) into chained calls. 1413 </p> 1414 1415 <p> 1416 <b class="header">0.5.1</b><br /> 1417 Added an <tt>_.isArguments</tt> function. Lots of little safety checks 1418 and optimizations contributed by 1419 <a href="http://github.com/iamnoah/">Noah Sloan</a> and 1420 <a href="http://themoell.com/">Andri Möll</a>. 1421 </p> 1422 1423 <p> 1424 <b class="header">0.5.0</b><br /> 1425 <b>[API Changes]</b> <tt>_.bindAll</tt> now takes the context object as 1426 its first parameter. If no method names are passed, all of the context 1427 object's methods are bound to it, enabling chaining and easier binding. 1428 <tt>_.functions</tt> now takes a single argument and returns the names 1429 of its Function properties. Calling <tt>_.functions(_)</tt> will get you 1430 the previous behavior. 1431 Added <tt>_.isRegExp</tt> so that <tt>isEqual</tt> can now test for RegExp equality. 1432 All of the "is" functions have been shrunk down into a single definition. 1433 <a href="http://github.com/grayrest/">Karl Guertin</a> contributed patches. 1434 </p> 1435 1436 <p> 1437 <b class="header">0.4.7</b><br /> 1438 Added <tt>isDate</tt>, <tt>isNaN</tt>, and <tt>isNull</tt>, for completeness. 1439 Optimizations for <tt>isEqual</tt> when checking equality between Arrays 1440 or Dates. <tt>_.keys</tt> is now <small><i><b>25%–2X</b></i></small> faster (depending on your 1441 browser) which speeds up the functions that rely on it, such as <tt>_.each</tt>. 1442 </p> 1443 1444 <p> 1445 <b class="header">0.4.6</b><br /> 1446 Added the <tt>range</tt> function, a port of the 1447 <a href="http://docs.python.org/library/functions.html#range">Python 1448 function of the same name</a>, for generating flexibly-numbered lists 1449 of integers. Original patch contributed by 1450 <a href="http://github.com/kylichuku">Kirill Ishanov</a>. 1451 </p> 1452 1453 <p> 1454 <b class="header">0.4.5</b><br /> 1455 Added <tt>rest</tt> for Arrays and arguments objects, and aliased 1456 <tt>first</tt> as <tt>head</tt>, and <tt>rest</tt> as <tt>tail</tt>, 1457 thanks to <a href="http://github.com/lukesutton/">Luke Sutton</a>'s patches. 1458 Added tests ensuring that all Underscore Array functions also work on 1459 <i>arguments</i> objects. 1460 </p> 1461 1462 <p> 1463 <b class="header">0.4.4</b><br /> 1464 Added <tt>isString</tt>, and <tt>isNumber</tt>, for consistency. Fixed 1465 <tt>_.isEqual(NaN, NaN)</tt> to return <i>true</i> (which is debatable). 1466 </p> 1467 1468 <p> 1469 <b class="header">0.4.3</b><br /> 1470 Started using the native <tt>StopIteration</tt> object in browsers that support it. 1471 Fixed Underscore setup for CommonJS environments. 1472 </p> 1473 1474 <p> 1475 <b class="header">0.4.2</b><br /> 1476 Renamed the unwrapping function to <tt>value</tt>, for clarity. 1477 </p> 1478 1479 <p> 1480 <b class="header">0.4.1</b><br /> 1481 Chained Underscore objects now support the Array prototype methods, so 1482 that you can perform the full range of operations on a wrapped array 1483 without having to break your chain. Added a <tt>breakLoop</tt> method 1484 to <b>break</b> in the middle of any Underscore iteration. Added an 1485 <tt>isEmpty</tt> function that works on arrays and objects. 1486 </p> 1487 1488 <p> 1489 <b class="header">0.4.0</b><br /> 1490 All Underscore functions can now be called in an object-oriented style, 1491 like so: <tt>_([1, 2, 3]).map(...);</tt>. Original patch provided by 1492 <a href="http://macournoyer.com/">Marc-André Cournoyer</a>. 1493 Wrapped objects can be chained through multiple 1494 method invocations. A <a href="#functions"><tt>functions</tt></a> method 1495 was added, providing a sorted list of all the functions in Underscore. 1496 </p> 1497 1498 <p> 1499 <b class="header">0.3.3</b><br /> 1500 Added the JavaScript 1.8 function <tt>reduceRight</tt>. Aliased it 1501 as <tt>foldr</tt>, and aliased <tt>reduce</tt> as <tt>foldl</tt>. 1502 </p> 1503 1504 <p> 1505 <b class="header">0.3.2</b><br /> 1506 Now runs on stock <a href="http://www.mozilla.org/rhino/">Rhino</a> 1507 interpreters with: <tt>load("underscore.js")</tt>. 1508 Added <a href="#identity"><tt>identity</tt></a> as a utility function. 1509 </p> 1510 1511 <p> 1512 <b class="header">0.3.1</b><br /> 1513 All iterators are now passed in the original collection as their third 1514 argument, the same as JavaScript 1.6's <b>forEach</b>. Iterating over 1515 objects is now called with <tt>(value, key, collection)</tt>, for details 1516 see <a href="#each"><tt>_.each</tt></a>. 1517 </p> 1518 1519 <p> 1520 <b class="header">0.3.0</b><br /> 1521 Added <a href="http://github.com/dmitryBaranovskiy">Dmitry Baranovskiy</a>'s 1522 comprehensive optimizations, merged in 1523 <a href="http://github.com/kriskowal/">Kris Kowal</a>'s patches to make Underscore 1524 <a href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> and 1525 <a href="http://narwhaljs.org/">Narwhal</a> compliant. 1526 </p> 1527 1528 <p> 1529 <b class="header">0.2.0</b><br /> 1530 Added <tt>compose</tt> and <tt>lastIndexOf</tt>, renamed <tt>inject</tt> to 1531 <tt>reduce</tt>, added aliases for <tt>inject</tt>, <tt>filter</tt>, 1532 <tt>every</tt>, <tt>some</tt>, and <tt>forEach</tt>. 1533 </p> 1534 1535 <p> 1536 <b class="header">0.1.1</b><br /> 1537 Added <tt>noConflict</tt>, so that the "Underscore" object can be assigned to 1538 other variables. 1539 </p> 1540 1541 <p> 1542 <b class="header">0.1.0</b><br /> 1543 Initial release of Underscore.js. 1544 </p> 1545 1546 <p> 1547 <a href="http://documentcloud.org/" title="A DocumentCloud Project" style="background:none;"> 1548 <img src="http://jashkenas.s3.amazonaws.com/images/a_documentcloud_project.png" alt="A DocumentCloud Project" /> 1549 </a> 1550 </p> 1551 1552 </div> 1553 1554 </div> 1555 1556 <!-- Include Underscore, so you can play with it in the console. --> 1557 <script type="text/javascript" src="underscore.js"></script> 1558 1559</body> 1560</html>