jsdoc-75lb

<!doctype html> <html> <head> <title></title> <link rel="stylesheet" type="text/css" href="tocdoc.css" /> </head> <body> <div class="toc"><ul><li><a href="#introduction">Introduction</a><ul><li><a href="#places">Places</a></li><li><a href="#why-underscore-contrib">Why underscore-contrib?</a></li><li><a href="#use">Use</a><ul><li><a href="#in-the-browser">In the Browser</a></li><li><a href="#in-node.js">In Node.js</a></li></ul></li><li><a href="#license">License</a></li></ul></li><li><a href="#sub-libraries">Sub-libraries</a><ul><li><a href="#array.builders">array.builders</a><ul><li><a href="#cat">cat</a></li><li><a href="#chunk">chunk</a></li><li><a href="#chunkall">chunkAll</a></li><li><a href="#cons">cons</a></li><li><a href="#cycle">cycle</a></li><li><a href="#interpose">interpose</a></li><li><a href="#iterateuntil">iterateUntil</a></li><li><a href="#keepindexed">keepIndexed</a></li><li><a href="#mapcat">mapcat</a></li><li><a href="#reductions">reductions</a></li><li><a href="#repeat">repeat</a></li><li><a href="#splitat">splitAt</a></li><li><a href="#takeskipping">takeSkipping</a></li><li><a href="#weave">weave</a></li></ul></li><li><a href="#array.selectors">array.selectors</a><ul><li><a href="#best">best</a></li><li><a href="#dropwhile">dropWhile</a></li><li><a href="#keep">keep</a></li><li><a href="#nth">nth</a></li><li><a href="#partitionby">partitionBy</a></li><li><a href="#second">second</a></li><li><a href="#takewhile">takeWhile</a></li><li><a href="#third">third</a></li></ul></li><li><a href="#collections.walk">collections.walk</a></li><li><a href="#function.arity">function.arity</a><ul><li><a href="#arity">arity</a></li><li><a href="#binary">binary</a></li><li><a href="#curry">curry</a></li><li><a href="#curry2">curry2</a></li><li><a href="#curry3">curry3</a></li><li><a href="#fix">fix</a></li><li><a href="#quaternary">quaternary</a></li><li><a href="#ternary">ternary</a></li><li><a href="#unary">unary</a></li><li><a href="#rcurry">rCurry</a></li><li><a href="#rcurry2">rcurry2</a></li><li><a href="#rcurry3">rcurry3</a></li></ul></li><li><a href="#function.combinators">function.combinators</a><ul><li><a href="#always">always</a></li><li><a href="#bound">bound</a></li><li><a href="#comparator">comparator</a></li><li><a href="#complement">complement</a></li><li><a href="#conjoin">conjoin</a></li><li><a href="#disjoin">disjoin</a></li><li><a href="#juxt">juxt</a></li><li><a href="#flip">flip</a></li><li><a href="#flip2">flip2</a></li><li><a href="#fnull">fnull</a></li><li><a href="#functionalize">functionalize</a></li><li><a href="#mapargs">mapArgs</a></li><li><a href="#mapargswith">mapArgsWith</a></li><li><a href="#methodize">methodize</a></li><li><a href="#pipeline">pipeline</a></li><li><a href="#splat">splat</a></li><li><a href="#unsplat">unsplat</a></li><li><a href="#unsplatl">unsplatl</a></li></ul></li><li><a href="#function.iterators">function.iterators</a><ul><li><a href="#iterators.accumulate">iterators.accumulate</a></li><li><a href="#iterators.accumulatewithreturn">iterators.accumulateWithReturn</a></li><li><a href="#iterators.drop">iterators.drop</a></li><li><a href="#iterators.foldl">iterators.foldl</a></li><li><a href="#iterators.k">iterators.K</a></li><li><a href="#iterators.list">iterators.List</a></li><li><a href="#iterators.map">iterators.map</a></li><li><a href="#iterators.mapcat">iterators.mapcat</a></li><li><a href="#iterators.numbers">iterators.numbers</a></li><li><a href="#iterators.range">iterators.range</a></li><li><a href="#iterators.reject">iterators.reject</a></li><li><a href="#iterators.select">iterators.select</a></li><li><a href="#iterators.slice">iterators.slice</a></li><li><a href="#iterators.take">iterators.take</a></li><li><a href="#iterators.tree">iterators.Tree</a></li><li><a href="#iterators.unfold">iterators.unfold</a></li><li><a href="#iterators.unfoldwithreturn">iterators.unfoldWithReturn</a></li></ul></li><li><a href="#function.predicates">function.predicates</a><ul><li><a href="#isassociative">isAssociative</a></li><li><a href="#isdecreasing">isDecreasing</a></li><li><a href="#iseven">isEven</a></li><li><a href="#isfloat">isFloat</a></li><li><a href="#isincreasing">isIncreasing</a></li><li><a href="#isindexed">isIndexed</a></li><li><a href="#isinstanceof">isInstanceOf</a></li><li><a href="#isinteger">isInteger</a></li><li><a href="#isjson">isJSON</a></li><li><a href="#isnegative">isNegative</a></li><li><a href="#isnumeric">isNumeric</a></li><li><a href="#isodd">isOdd</a></li><li><a href="#isplainobject">isPlainObject</a></li><li><a href="#ispositive">isPositive</a></li><li><a href="#issequential">isSequential</a></li><li><a href="#isvaliddate">isValidDate</a></li><li><a href="#iszero">isZero</a></li></ul></li><li><a href="#object.builders">object.builders</a><ul><li><a href="#frequencies">frequencies</a></li><li><a href="#merge">merge</a></li><li><a href="#renamekeys">renameKeys</a></li><li><a href="#setpath">setPath</a></li><li><a href="#snapshot">snapshot</a></li></ul></li><li><a href="#object.selectors">object.selectors</a><ul><li><a href="#accessor">accessor</a></li><li><a href="#dictionary">dictionary</a></li><li><a href="#getpath">getPath</a></li><li><a href="#haspath">hasPath</a></li><li><a href="#kv">kv</a></li><li><a href="#omitwhen">omitWhen</a></li><li><a href="#pickwhen">pickWhen</a></li><li><a href="#selectkeys">selectKeys</a></li></ul></li><li><a href="#util.existential">util.existential</a><ul><li><a href="#exists">exists</a></li><li><a href="#falsey">falsey</a></li><li><a href="#firstexisting">firstExisting</a></li><li><a href="#not">not</a></li><li><a href="#truthy">truthy</a></li></ul></li><li><a href="#util.operators">util.operators</a><ul><li><a href="#add">add</a></li><li><a href="#bitwiseand">bitwiseAnd</a></li><li><a href="#bitwiseleft">bitwiseLeft</a></li><li><a href="#bitwiseright">bitwiseRight</a></li><li><a href="#bitwisenot">bitwiseNot</a></li><li><a href="#bitwiseor">bitwiseOr</a></li><li><a href="#bitwisexor">bitwiseXor</a></li><li><a href="#bitwisez">bitwiseZ</a></li><li><a href="#dec">dec</a></li><li><a href="#div">div</a></li><li><a href="#eq">eq</a></li><li><a href="#gt">gt</a></li><li><a href="#gte">gte</a></li><li><a href="#inc">inc</a></li><li><a href="#lt">lt</a></li><li><a href="#lte">lte</a></li><li><a href="#mul">mul</a></li><li><a href="#mod">mod</a></li><li><a href="#neg">neg</a></li><li><a href="#neq">neq</a></li><li><a href="#not-1">not</a></li><li><a href="#seq">seq</a></li><li><a href="#sneq">sneq</a></li><li><a href="#sub">sub</a></li></ul></li><li><a href="#util.strings">util.strings</a><ul><li><a href="#camelcase">camelCase</a></li><li><a href="#explode">explode</a></li><li><a href="#fromquery">fromQuery</a></li><li><a href="#implode">implode</a></li><li><a href="#strcontains">strContains</a></li><li><a href="#todash">toDash</a></li><li><a href="#toquery">toQuery</a></li></ul></li><li><a href="#util.trampolines">util.trampolines</a></li><li><a href="#changelog">Changelog</a><ul><li><a href="#0.3.0">0.3.0</a></li></ul></li></ul></li></ul></div> <h1 id="underscore-contrib-0-3-0-">Underscore-contrib (0.3.0)</h1> <blockquote> <p>The brass buckles on Underscore's utility belt - a contributors' library for <a href="http://underscorejs.org/">Underscore</a>.</p> </blockquote> <h2 id="introduction"><a href="#introduction" name="introduction">Introduction</a></h2> <h3 id="places"><a href="#places" name="places">Places</a></h3> <ul> <li><a href="http://documentcloud.github.io/underscore-contrib/">Documentation</a></li> <li><a href="https://github.com/documentcloud/underscore-contrib">Source repository</a></li> <li><a href="https://github.com/documentcloud/underscore-contrib/issues?state=open">Tickets and bug reports</a></li> <li><a href="http://www.fogus.me">Maintainer's website</a></li> </ul> <h3 id="why-underscore-contrib-"><a href="#why-underscore-contrib" name="why-underscore-contrib">Why underscore-contrib?</a></h3> <p>While Underscore provides a bevy of useful tools to support functional programming in JavaScript, it can't (and shouldn't) be everything to everyone. Underscore-contrib is intended as a home for functions that, for various reasons, don't belong in Underscore proper. In particular, it aims to be:</p> <ul> <li>a home for functions that are limited in scope, but solve certain point problems, and</li> <li>a proving ground for features that belong in Underscore proper, but need some advocacy and/or evolution (or devolution) to get them there.</li> </ul> <h3 id="use"><a href="#use" name="use">Use</a></h3> <h4 id="in-the-browser"><a href="#in-the-browser" name="in-the-browser">In the Browser</a></h4> <p>First, you'll need Underscore <strong>version 1.6.0 or higher</strong>. Then you can grab the relevant underscore-contrib sub-libraries and simply add something like the following to your pages:</p> <pre><code class="lang-html"><script type="text/javascript" src="underscore.js"></script> <script type="text/javascript" src="underscore.object.builders.js"></script></code></pre> <p>At the moment there are no cross-contrib dependencies (i.e. each sub-library can stand by itself), but that may change in the future.</p> <h4 id="in-node-js"><a href="#in-node.js" name="in-node.js">In Node.js</a></h4> <p>Using contrib in Node is very simple. Just install it with npm:</p> <pre><code>npm install underscore-contrib --save</code></pre> <p>Then require it within your project like so:</p> <pre><code class="lang-javascript">var _ = require('underscore-contrib');</code></pre> <p>The <code>_</code> variable will be a copy of Underscore with contrib's methods already mixed in.</p> <h3 id="license"><a href="#license" name="license">License</a></h3> <p>_.contrib is open sourced under the <a href="https://github.com/documentcloud/underscore-contrib/blob/master/LICENSE">MIT license</a>.</p> <h2 id="sub-libraries"><a href="#sub-libraries" name="sub-libraries">Sub-libraries</a></h2> <p>The _.contrib library currently contains a number of related capabilities, aggregated into the following files.</p> <ul> <li><a href="#array.builders">underscore.array.builders</a> - functions to build arrays</li> <li><a href="#array.selectors">underscore.array.selectors</a> - functions to take things from arrays</li> <li><a href="#collections.walk">underscore.collections.walk</a> - functions to walk and transform nested JavaScript objects</li> <li><a href="#function.arity">underscore.function.arity</a> - functions to manipulate and fix function argument arity</li> <li><a href="#function.combinators">underscore.function.combinators</a> - functions to combine functions to make new functions</li> <li><a href="#function.iterators">underscore.function.iterators</a> - functions to lazily produce, manipulate and consume sequence iterators</li> <li><a href="#function.predicates">underscore.function.predicates</a> - functions that return <code>true</code> or <code>false</code> based on some criteria</li> <li><a href="#object.builders">underscore.object.builders</a> - functions to build JavaScript objects</li> <li><a href="#object.selectors">underscore.object.selectors</a> - functions to pick things from JavaScript objects</li> <li><a href="#util.existential">underscore.util.existential</a> - functions that check for the existence or truthiness of JavaScript data types</li> <li><a href="#util.operators">underscore.util.operators</a> - functions that wrap common (or missing) JavaScript operators</li> <li><a href="#util.strings">underscore.util.strings</a> - functions to work with strings</li> <li><a href="#util.trampolines">underscore.util.trampolines</a> - functions to facilitate calling functions recursively without blowing the stack</li> </ul> <p>The links above are to the annotated source code. Full-blown _.contrib documentation is in the works. Contributors welcomed.</p> <h3 id="array-builders"><a href="#array.builders" name="array.builders">array.builders</a></h3> <blockquote> <p>Functions to build arrays. <a href="docs/underscore.array.builders.js.html" class="btn btn-primary btn-xs">View Annotated Source</a></p> </blockquote> <hr> <h4 id="cat"><a href="#cat" name="cat">cat</a></h4> <p>Signature: <code>_.cat(... arrays:Array ...)</code></p> <p>The <code>_.cat</code> function provides a way to concatenate zero or more heterogeneous arrays into one.</p> <pre><code class="lang-javascript">_.cat(); // 0-args //=> [] _.cat([]); // 1-arg, empty array //=> [] _.cat([1,2,3]); // 1-arg //=> [1,2,3] _.cat([1,2,3],[4,5,6]); // 2-args //=> [1,2,3,4,5,6] _.cat([1,2,3],[4,5,6],[7]); // 3+ args //=> [1,2,3,4,5,6,7]</code></pre> <p>Not every argument to <code>_.cat</code> needs to be an array; other types are accepted.</p> <p>Signature: <code>_.cat(... elems:Any ...)</code></p> <pre><code class="lang-javascript">_.cat(1,[2],3,4); // mixed args //=> [1,2,3,4]</code></pre> <p>The <code>_.cat</code> function will also work with the <code>arguments</code> object as if it were an array.</p> <p>Signature: <code>_.cat(... elems:Arguments ...)</code></p> <pre><code class="lang-javascript">function f(){ return _.cat(arguments, 4,5,6); } f(1,2,3); //=> [1,2,3,4,5,6]</code></pre> <hr> <h4 id="chunk"><a href="#chunk" name="chunk">chunk</a></h4> <p>The <code>_.chunk</code> function, by default, accepts an array and a number and splits and returns a new array representing the original array split into some number of arrays of the given size:</p> <pre><code class="lang-javascript">_.chunk([0,1,2,3], 2); //=> , [[0,1],[2,3]]</code></pre> <p>If the original array cannot completely fulfill the chunk scheme then the array returned will drop the undersized final chunk:</p> <pre><code class="lang-javascript">_.chunk([0,1,2,3,4], 2); //=> , [[0,1],[2,3]]</code></pre> <p>You can pass an optional third argument to <code>_.chunk</code> to pad out the final array chunk should it fall short. If the value given as the third argument is <em>not</em> an array then it is repeated the needed number of times:</p> <pre><code class="lang-javascript">_.chunk([0,1,2,3,4], 3, '_'); //=> , [[0,1,2],[3,'_','_']]</code></pre> <p>If you given an array as the optional third argument then that array is used to pad in-place as needed:</p> <pre><code class="lang-javascript">_.chunk([0,1,2,3,4], 3, ['a', 'b']); //=> , [[0,1,2],[3,'a','b']]</code></pre> <hr> <h4 id="chunkall"><a href="#chunkall" name="chunkall">chunkAll</a></h4> <p>The <code>_.chunkAll</code> function is similar to <code>_.chunk</code> except for the following. First, <code>_.chunkAll</code> will never drop short chunks from the end:</p> <pre><code class="lang-javascript">_.chunkAll([0,1,2,3,4], 3); //=> , [[0,1,2],[3]]</code></pre> <p>Also, <code>_.chunkAll</code> takes an optional third argument signifying that paritions should be built from skipped regions:</p> <pre><code class="lang-javascript">_.chunkAll(_.range(1), 2, 4); //=> [[0,1],[4,5],[8,9]]</code></pre> <hr> <h4 id="cons"><a href="#cons" name="cons">cons</a></h4> <p>Signature: <code>_.cons(head:Any, tail:Array)</code></p> <p>The <code>_.cons</code> function provides a way to "construct" a new array by taking some element and putting it at the front of another array.</p> <pre><code class="lang-javascript">_.cons(0, []); //=> [0] _.cons(1, [2]); //=> [1,2] _.cons([0], [1,2,3]); //=> [0,1,2,3]</code></pre> <p>The <code>_.cons</code> function also can be used to create pairs if the second argument is not an array.</p> <p>Signature: <code>_.cons(head:Any, tail:Any)</code></p> <pre><code class="lang-javascript">_.cons(1, 2); //=> [1,2] _.cons([1], 2); //=> [[1],2]</code></pre> <p>Finally, <code>_.cons</code> will operate with the <code>arguments</code> object.</p> <p>Signature: <code>_.cons(head:Any, tail:Arguments)</code></p> <pre><code class="lang-javascript">function f() { return _.cons(0, arguments) } f(1,2,3); //=> [0,1,2,3]</code></pre> <hr> <h4 id="cycle"><a href="#cycle" name="cycle">cycle</a></h4> <p>The <code>_.cycle</code> function takes an integer value used to build an array of that size containing the number of iterations through the given array, strung end-to-end as many times as needed. An example is probably more instructive:</p> <pre><code class="lang-javascript">_.cycle(5, [1,2,3]); //=> [1,2,3,1,2]</code></pre> <hr> <h4 id="interpose"><a href="#interpose" name="interpose">interpose</a></h4> <p>The <code>_.interpose</code> function takes an array and an element and returns a new array with the given element inserted betwixt every element in the original array:</p> <pre><code class="lang-javascript">_.interpose([1,2,3], 0); //=> [1,0,2,0,3]</code></pre> <p>If there are no betweens (i.e. empty and single-element arrays), then the original array is returned:</p> <pre><code class="lang-javascript">_.interpose([1], 0); //=> [1] _.interpose([], 0); //=> []</code></pre> <hr> <h4 id="iterateuntil"><a href="#iterateuntil" name="iterateuntil">iterateUntil</a></h4> <p>The <code>_.iterateUntil</code> function takes a function used as a result generator, a function used as a stop-check and a seed value and returns an array of each generated result. The operation of <code>_.iterateUntil</code> is such that the result generator is passed the seed to start and each subsequent result which will continue <strong>until</strong> a result fails the check function (i.e. returns falsey). An example is best:</p> <pre><code class="lang-javascript">var dec = function(n) { return n - 1; }; var isPos = function(n) { return n > 0; };</code></pre> <p>The <code>dec</code> result generator takes a number and decrements it by one. The <code>isPos</code> predicate takes a number and returns <code>true</code> if it's positive. Using these two functions you can build an array of every number from <code>6</code> to <code>0</code>, inclusive:</p> <pre><code class="lang-javascript">_.iterateUntil(dec, isPos, 6); //=> [5,4,3,2,1]</code></pre> <p>That is, the array only contains every number from <code>5</code> down to <code>1</code> because when the result of <code>dec</code> got to <code>0</code> the <code>isPos</code> check failed (i.e. went falsey) thus terminating the execution.</p> <hr> <h4 id="keepindexed"><a href="#keepindexed" name="keepindexed">keepIndexed</a></h4> <p>The <code>_.keepIndexed</code> function takes an array and a function and returns a new array filled with the <em>non-null</em> return results of the given function on the elements or keys in the given array:</p> <pre><code class="lang-javascript">_.keepIndexed([1,2,3], function(k) { return i === 1 || i === 2; }); //=> [false, true, true]</code></pre> <p>If you return either <code>null</code> or <code>undefined</code> then the result is dropped from the resulting array:</p> <pre><code class="lang-javascript">_.keepIndexed(['a','b','c'], function(k, v) { if (k === 1) return v; }); //=> ['b']</code></pre> <hr> <h4 id="mapcat"><a href="#mapcat" name="mapcat">mapcat</a></h4> <p>There are times when a mapping operation produces results contained in arrays, but the final result should be flattened one level. For these circumstances you can use <code>_.mapcat</code> to produce results:</p> <pre><code class="lang-javascript">var array = [1,2,null,4,undefined,6]; var errors = _.mapcat(array, function(e,i) { if (e == null) { return ["Element @" + i + " is bad"]; } else { return []; } });</code></pre> <p>Inspecting the contents of <code>errors</code> shows:</p> <pre><code class="lang-javascript">["Element @2 is bad", "Element @4 is bad"]</code></pre> <p>The <code>_.mapcat</code> function is equivalent to <code>_.cat.apply(array, _.map(array,fun))</code>.</p> <hr> <h4 id="reductions"><a href="#reductions" name="reductions">reductions</a></h4> <p>The <code>_.reductions</code> function is similar to Underscore's builtin <code>_.reduce</code> function except that it returns an array of every intermediate value in the folding operation:</p> <pre><code class="lang-javascript">_.reductions([1,2,3,4,5], function(agg, n) { return agg + n; }, 0); //=> [1,3,6,10,15]</code></pre> <p>The last element in the array returned from <code>_.reductions</code> is the answer that you would get if you had just chosen to use <code>_.reduce</code>.</p> <hr> <h4 id="repeat"><a href="#repeat" name="repeat">repeat</a></h4> <p>Signature: <code>_.repeat(t:Integer, value:Any)</code></p> <p>The <code>_.repeat</code> function takes an integer value used to build an array of that size containing the value given:</p> <pre><code class="lang-javascript">_.repeat(5, 'a'); //=> ['a','a','a','a','a']</code></pre> <hr> <h4 id="splitat"><a href="#splitat" name="splitat">splitAt</a></h4> <p>The <code>_.splitAt</code> function takes an array and a numeric index and returns a new array with two embedded arrays representing a split of the original array at the index provided:</p> <pre><code class="lang-javascript">_.splitAt([1,2,3,4,5], 2); //=> [[1,2],[3,4,5]] _.splitAt([1,2,3,4,5], 0); //=> [[],[1,2,3,4,5]]</code></pre> <p>The operation of <code>_.splitAt</code> is safe if the index provided is outside the range of legal indices:</p> <pre><code class="lang-javascript">_.splitAt([1,2,3,4,5], 20000); //=> [[1,2,3,4,5],[]] _.splitAt([1,2,3,4,5], -1000); //=> [[],[1,2,3,4,5]] _.splitAt([], 0); //=> [[],[]]</code></pre> <hr> <h4 id="takeskipping"><a href="#takeskipping" name="takeskipping">takeSkipping</a></h4> <p>The <code>_.takeSkipping</code> function takes an array and a number and returns a new array containing every nth element in the original array:</p> <pre><code class="lang-javascript">_.takeSkipping(_.range(10), 2); //=> [0,2,4,6,8]</code></pre> <p>The <code>_.takeSkipping</code> function is safe against numbers larger or smaller than the array size:</p> <pre><code class="lang-javascript">_.takeSkipping(_.range(10), 100000); //=> [0] _.takeSkipping(_.range(10), -100); //=> []</code></pre> <hr> <h4 id="weave"><a href="#weave" name="weave">weave</a></h4> <p>The <code>_.weave</code> function works similarly to <code>_.interpose</code> (shown above) except that it accepts an array used as the interposition values. In other words, <code>_.weave</code> takes two arrays and returns a new array with the original elements woven together. An example would help:</p> <pre><code class="lang-javascript">_.weave(['a','b','c'], [1,2,3]); //=> ['a',1,'b',2,'c',3]</code></pre> <p>The array returned from <code>_.weave</code> will be as long as the longest array given with the woven entries stopping according to the shortest array:</p> <pre><code class="lang-javascript">_.weave(['a','b','c'], [1]); //=> ['a',1,'b','c']</code></pre> <p>The <code>_.interleave</code> function is an alias for <code>_.weave</code>.</p> <hr> <h3 id="array-selectors"><a href="#array.selectors" name="array.selectors">array.selectors</a></h3> <blockquote> <p>Functions to take things from arrays. <a href="docs/underscore.array.selectors.js.html" class="btn btn-primary btn-xs">View Annotated Source</a></p> </blockquote> <hr> <h4 id="best"><a href="#best" name="best">best</a></h4> <p><strong>Signature:</strong> <code>_.best(array:Array, fun:Function)</code></p> <p>Returns the "best" value in an array based on the result of a given function.</p> <pre><code class="lang-javascript">_.best([1, 2, 3, 4, 5], function(x, y) { return x > y; }); //=> 5</code></pre> <hr> <h4 id="dropwhile"><a href="#dropwhile" name="dropwhile">dropWhile</a></h4> <p><strong>Signature:</strong> <code>_.dropWhile(array:Array, pred:Function)</code></p> <p>Drops elements for which the given function returns a truthy value.</p> <pre><code class="lang-javascript">_.dropWhile([-2,-1,0,1,2], isNeg); //=> [0,1,2]</code></pre> <hr> <h4 id="keep"><a href="#keep" name="keep">keep</a></h4> <p><strong>Signature:</strong> <code>_.keep(array:Array, fun:Function)</code></p> <p>Returns an array of existy results of a function over a source array.</p> <pre><code class="lang-javascript">_.keep([1, 2, 3, 4, 5], function(val) { if (val % 3 === 0) { return val; } }); // => [3]</code></pre> <hr> <h4 id="nth"><a href="#nth" name="nth">nth</a></h4> <p><strong>Signature:</strong> <code>_.nth(array:Array, index:Number[, guard:Any])</code></p> <p>The <code>_.nth</code> function is a convenience for the equivalent <code>array[n]</code>. The optional <code>guard</code> value allows <code>_.nth</code> to work correctly as a callback for <code>_.map</code>.</p> <pre><code class="lang-javascript">_.nth(['a','b','c'], 2); //=> 'c'</code></pre> <p>If given an index out of bounds then <code>_.nth</code> will return <code>undefined</code>:</p> <pre><code class="lang-javascript">_.nth(['a','b','c'], 2000); //=> undefined</code></pre> <p>The <code>_.nth</code> function can also be used in conjunction with <code>_.map</code> and <code>_.compact</code> like so:</p> <pre><code class="lang-javascript">var b = [['a'],['b'],[]]; _.compact(_.map(b, function(e) { return _.nth(e,0) })); //=> ['a','b']</code></pre> <p>If wrapping a function around <code>_.nth</code> is too tedious or you'd like to partially apply the index then Underscore-contrib offers any of <code>_.flip2</code>, <code>_.fix</code> or <code>rcurry2</code> to solve this.</p> <hr> <h4 id="partitionby"><a href="#partitionby" name="partitionby">partitionBy</a></h4> <p><strong>Signature:</strong> <code>_.keep(array:Array, fun:Function)</code></p> <p>Takes an array and partitions it into sub-arrays as the given predicate changes truth sense.</p> <pre><code class="lang-javascript">_.partitionBy([1,2,2,3,1,1,5], _.isEven); // => [[1],[2,2],[3,1,1,5]] _.partitionBy([1,2,2,3,1,1,5], _.identity); // => [[1],[2,2],[3],[1,1],[5]]</code></pre> <hr> <h4 id="second"><a href="#second" name="second">second</a></h4> <p><strong>Signature:</strong> <code>_.second(array:Array, index:Number[, guard:Any])</code></p> <p>The <code>_.second</code> function is a convenience for the equivalent <code>array[1]</code>. The optional <code>guard</code> value allows <code>_.second</code> to work correctly as a callback for <code>_.map</code>.</p> <pre><code class="lang-javascript">_.second(['a','b']); //=> 'b' _.map([['a','b'], _.range(10,20)], _.second); //=> ['b',11]</code></pre> <p>You can also pass an optional number to the <code>_.second</code> function to take a number of elements from an array starting with the second element and ending at the given index:</p> <pre><code class="lang-javascript">_.second(_.range(10), 5) //=> [1, 2, 3, 4]</code></pre> <hr> <h4 id="takewhile"><a href="#takewhile" name="takewhile">takeWhile</a></h4> <p><strong>Signature:</strong> <code>_.takeWhile(array:Array, pred:Function)</code></p> <p>The <code>_.takeWhile</code> function takes an array and a function and returns a new array containing the first n elements in the original array for which the given function returns a truthy value:</p> <pre><code class="lang-javascript">var isNeg = function(n) { return n < 0; }; _.takeWhile([-2,-1,0,1,2], isNeg); //=> [-2,-1]</code></pre> <hr> <h4 id="third"><a href="#third" name="third">third</a></h4> <p><strong>Signature:</strong> <code>_.third(array:Array, index:Number[, guard:Any])</code></p> <p>The <code>_.third</code> function is a convenience for the equivalent <code>array[2]</code>. The optional <code>guard</code> value allows <code>_.third</code> to work correctly as a callback for <code>_.map</code>.</p> <pre><code class="lang-javascript">_.third(['a','b','c']); //=> 'c' _.map([['a','b','c'], _.range(10,20)], _.third); //=> ['c',12]</code></pre> <p>You can also pass an optional number to the <code>_.third</code> function to take a number of elements from an array starting with the third element and ending at the given index:</p> <pre><code class="lang-javascript">_.third(_.range(10), 5) //=> [2, 3, 4]</code></pre> <hr> <h3 id="collections-walk"><a href="#collections.walk" name="collections.walk">collections.walk</a></h3> <blockquote> <p>Functions to recursively walk collections which are trees.</p> </blockquote> <p>Documentation should use <a href="https://github.com/jashkenas/journo">Journo</a> formats and standards.</p> <pre><code> _.walk = walk; postorder: function(obj, visitor, context) preorder: function(obj, visitor, context) walk(obj, visitor, null, context) map: function(obj, strategy, visitor, context) pluck: function(obj, propertyName) pluckRec: function(obj, propertyName) _.walk.collect = _.walk.map;</code></pre> <h3 id="function-arity"><a href="#function.arity" name="function.arity">function.arity</a></h3> <blockquote> <p>Functions which manipulate the way functions work with their arguments.</p> </blockquote> <hr> <h4 id="arity"><a href="#arity" name="arity">arity</a></h4> <p><strong>Signature:</strong> <code>_.arity(numberOfArgs:Number, fun:Function)</code></p> <p>Returns a new function which is equivalent to <code>fun</code>, except that the new function's <code>length</code> property is equal to <code>numberOfArgs</code>. This does <strong>not</strong> limit the function to using that number of arguments. It's only effect is on the reported length.</p> <pre><code class="lang-javascript">function addAll() { var sum = 0; for (var i = 0; i < arguments.length; i++) { sum = sum + arguments[i]; } return sum; } addAll.length // => 0 var addAllWithFixedLength = _.arity(2, addAll); addAllWithFixedLength.length // => 2 addAllWithFixedLength(1, 1, 1, 1); // => 4</code></pre> <hr> <h4 id="binary"><a href="#binary" name="binary">binary</a></h4> <p><strong>Signature:</strong> <code>_.binary(fun:Function)</code></p> <p>Returns a new function which accepts only two arguments and passes these arguments to <code>fun</code>. Additional arguments are discarded.</p> <pre><code class="lang-javascript">function addAll() { var sum = 0; for (var i = 0; i < arguments.length; i++) { sum = sum + arguments[i]; } return sum; } var add2 = _.binary(addAll); add2(1, 1); // => 2 add2(1, 1, 1, 1); // => 2</code></pre> <hr> <h4 id="curry"><a href="#curry" name="curry">curry</a></h4> <p><strong>Signature:</strong> <code>_.curry(func:Function[, reverse:Boolean])</code></p> <p>Returns a curried version of <code>func</code>. If <code>reverse</code> is true, arguments will be processed from right to left.</p> <pre><code class="lang-javascript">function add3 (x, y, z) { return x + y + z; } var curried = _.curry(add3); // => function curried(1); // => function curried(1)(2); // => function curried(1)(2)(3); // => 6</code></pre> <hr> <h4 id="curry2"><a href="#curry2" name="curry2">curry2</a></h4> <p><strong>Signature:</strong> <code>_.curry2(fun:Function)</code></p> <p>Returns a curried version of <code>func</code>, but will curry exactly two arguments, no more or less.</p> <pre><code class="lang-javascript">function add2 (a, b) { return a + b; } var curried = _.curry2(add2); // => function curried(1); // => function curried(1)(2); // => 3</code></pre> <hr> <h4 id="curry3"><a href="#curry3" name="curry3">curry3</a></h4> <p><strong>Signature:</strong> <code>_.curry3(fun:Function)</code></p> <p>Returns a curried version of <code>func</code>, but will curry exactly three arguments, no more or less.</p> <pre><code class="lang-javascript">function add3 (a, b, c) { return a + b + c; } var curried = _.curry3(add3); // => function curried(1); // => function curried(1)(2); // => function curried(1)(2)(3); // => 6</code></pre> <hr> <h4 id="fix"><a href="#fix" name="fix">fix</a></h4> <p><strong>Signature:</strong> <code>_.fix(fun:Function[, value:Any...])</code></p> <p>Fixes the arguments to a function based on the parameter template defined by the presence of values and the <code>_</code> placeholder.</p> <pre><code class="lang-javascript">function add3 (a, b, c) { return a + b + c; } var fixedFirstAndLast = _.fix(add3, 1, _, 3); // => function fixedFirstAndLast(2); // => 6 fixedFirstAndLast(10); // => 14</code></pre> <hr> <h4 id="quaternary"><a href="#quaternary" name="quaternary">quaternary</a></h4> <p><strong>Signature:</strong> <code>_.quaternary(fun:Function)</code></p> <p>Returns a new function which accepts only four arguments and passes these arguments to <code>fun</code>. Additional arguments are discarded.</p> <pre><code class="lang-javascript">function addAll() { var sum = 0; for (var i = 0; i < arguments.length; i++) { sum = sum + arguments[i]; } return sum; } var add4 = _.quaternary(addAll); add4(1, 1, 1, 1); // => 4 add4(1, 1, 1, 1, 1, 1); // => 4</code></pre> <hr> <h4 id="ternary"><a href="#ternary" name="ternary">ternary</a></h4> <p><strong>Signature:</strong> <code>_.ternary(fun:Function)</code></p> <p>Returns a new function which accepts only three arguments and passes these arguments to <code>fun</code>. Additional arguments are discarded.</p> <pre><code class="lang-javascript">function addAll() { var sum = 0; for (var i = 0; i < arguments.length; i++) { sum = sum + arguments[i]; } return sum; } var add3 = _.ternary(addAll); add3(1, 1, 1); // => 3 add3(1, 1, 1, 1, 1, 1); // => 3</code></pre> <hr> <h4 id="unary"><a href="#unary" name="unary">unary</a></h4> <p><strong>Signature:</strong> <code>_.unary(fun:Function)</code></p> <p>Returns a new function which accepts only one argument and passes this argument to <code>fun</code>. Additional arguments are discarded.</p> <pre><code class="lang-javascript">function logArgs() { console.log(arguments); } var logOneArg = _.unary(logArgs); logOneArg("first"); // => ["first"] logOneArg("first", "second"); // => ["first"]</code></pre> <hr> <h4 id="rcurry"><a href="#rcurry" name="rcurry">rCurry</a></h4> <p><strong>Signature:</strong> <code>_.rCurry(func:Function)</code></p> <p>Returns a curried version of <code>func</code> where arguments are processed from right to left.</p> <pre><code class="lang-javascript">function divide (a, b) { return a / b; } var curried = _.rCurry(divide); // => function curried(1); // => function curried(1)(2); // => 2 curried(2)(1); // => 0.5</code></pre> <hr> <h4 id="rcurry2"><a href="#rcurry2" name="rcurry2">rcurry2</a></h4> <p><strong>Signature:</strong> <code>_.rcurry2(func:Function)</code></p> <p>Returns a curried version of <code>func</code> where a maxium of two arguments are processed from right to left.</p> <pre><code class="lang-javascript">function concat () { var str = ""; for (var i = 0; i < arguments.length; i++) { str = str + arguments[i]; } return str; } var curried = _.rcurry2(concat); // => function curried("a"); // => function curried("a")("b"); // => "ba"</code></pre> <hr> <h4 id="rcurry3"><a href="#rcurry3" name="rcurry3">rcurry3</a></h4> <p><strong>Signature:</strong> <code>_.rcurry3(func:Function)</code></p> <p>Returns a curried version of <code>func</code> where a maxium of three arguments are processed from right to left.</p> <pre><code class="lang-javascript">function concat () { var str = ""; for (var i = 0; i < arguments.length; i++) { str = str + arguments[i]; } return str; } var curried = _.rcurry3(concat); // => function curried("a"); // => function curried("a")("b"); // => function curried("a")("b")("c"); // => "cba"</code></pre> <h3 id="function-combinators"><a href="#function.combinators" name="function.combinators">function.combinators</a></h3> <blockquote> <p>Functions that are combinators.</p> </blockquote> <hr> <h4 id="always"><a href="#always" name="always">always</a></h4> <p><strong>Signature:</strong> <code>_.always(value:Any)</code></p> <p><strong>Aliases:</strong> <code>_.k</code></p> <p>Takes <code>value</code> and returns a function that will always return <code>value</code>.</p> <pre><code class="lang-javascript">var platonicForm = _.always("Eternal & Unchangeable"); platonicForm(); // => "Eternal & Unchangeable"</code></pre> <hr> <h4 id="bound"><a href="#bound" name="bound">bound</a></h4> <p><strong>Signature:</strong> <code>_.bound(obj:Object, fname:String)</code></p> <p>Returns function property of an object by name, bound to object.</p> <pre><code class="lang-javascript">var aristotle = { name: "Aristotle", telos: "flourishing", stateTelos: function() { return this.name + "'s telos is " + this.telos; } }; var stateAristotlesTelos = _.bound(aristotle, "stateTelos"); stateAristotlesTelos(); // => "Aristotle's Telos is flourishing"</code></pre> <hr> <h4 id="comparator"><a href="#comparator" name="comparator">comparator</a></h4> <p><strong>Signature:</strong> <code>_.comparator(fun:Function)</code></p> <p>Takes a binary predicate-like function and returns a comparator function (return values of <code>-1</code>, <code>0</code>, <code>1</code>) which can be used as a callback for <code>_.sort</code> or <code>Array.prototype.sort</code>.</p> <pre><code class="lang-javascript">var lessOrEqual = function(x, y) { return x <= y; }; var arr = [0, 1, -2]; arr.sort(_.comparator(lessOrEqual)); // => [-2, 0, 1]</code></pre> <hr> <h4 id="complement"><a href="#complement" name="complement">complement</a></h4> <p><strong>Signature:</strong> <code>_.complement(pred:Function)</code></p> <p>Returns a function that reverses the sense of a given predicate-like.</p> <pre><code class="lang-javascript">function isAugustine (val) { return val === "Augustine"; } isNotAugustine = _.complement(isAugustine); isNotAugustine("Dionysius"); // => True</code></pre> <hr> <h4 id="conjoin"><a href="#conjoin" name="conjoin">conjoin</a></h4> <p><strong>Signature:</strong> <code>_.conjoin(pred:Function...)</code></p> <p>Composes multiple predicates into a single predicate that checks all elements of an array for conformance to <strong>all</strong> of the original predicates.</p> <pre><code class="lang-javascript">function startsWithA (val) { return val[0] === "A"; } function endsWithE (val) { return val[val.length - 1] === "e"; } var names = ["Aristotle", "Aquinas", "Plato", "Augustine"]; var startsAAndEndsE = _.conjoin(startsWithA, endsWithE); startsAAndEndsE(names); // => ["Aristotle", "Augustine"]</code></pre> <hr> <h4 id="disjoin"><a href="#disjoin" name="disjoin">disjoin</a></h4> <p><strong>Signature:</strong> <code>_.disjoin(pred:Function...)</code></p> <p>Composes multiple predicates into a single predicate that checks all elements of an array for conformance to <strong>any</strong> of the original predicates.</p> <pre><code class="lang-javascript">function startsWithA (val) { return val[0] === "A"; } function endsWithE (val) { return val[val.length - 1] === "e"; } var names = ["Aristotle", "Aquinas", "Plato", "Augustine"]; var startsAOrEndsE = _.disjoin(startsWithA, endsWithE); startsAOrEndsE(names); // => ["Aristotle", "Aquinas", "Augustine"]</code></pre> <hr> <h4 id="juxt"><a href="#juxt" name="juxt">juxt</a></h4> <p><strong>Signature:</strong> <code>_.juxt(fun:Function...)</code></p> <p>Returns a function whose return value is an array of the results of calling each of the original functions with the arguments.</p> <pre><code class="lang-javascript">function firstChar (val) { return val[0]; } function lastChar (val) { return val[val.length - 1]; } var firstAndLastChars = _.juxt(firstChar, lastChar); firstAndLastChars("Etruria"); // => ["E", "a"]</code></pre> <hr> <h4 id="flip"><a href="#flip" name="flip">flip</a></h4> <p><strong>Signature:</strong> <code>_.flip(fun:Function)</code></p> <p>Returns a function that works identically to <code>fun</code>, but accepts the arguments in reverse order.</p> <pre><code class="lang-javascript">function regionCapitol (region, capitol) { return "The capitol of " + region + " is " + capitol; } capitolRegion = _.flip(regionCapitol); capitolRegion("Thessalonica", "Illyrica"); // => "The capitol of Illyrica is Thessalonica"</code></pre> <hr> <h4 id="flip2"><a href="#flip2" name="flip2">flip2</a></h4> <p><strong>Signature:</strong> <code>_.flip2(fun:Function)</code></p> <p>Returns a function that works identically to <code>fun</code>, but accepts the first two arguments in reverse order. The order of all other arguments remains the same.</p> <pre><code class="lang-javascript">function regionCapitol (region, capitol) { return "The capitol of " + region + " is " + capitol; } capitolRegion = _.flip2(regionCapitol); capitolRegion("Thessalonica", "Illyrica"); // => "The capitol of Illyrica is Thessalonica"</code></pre> <hr> <h4 id="fnull"><a href="#fnull" name="fnull">fnull</a></h4> <p><strong>Signature:</strong> <code>_.fnull(fun:Function[, default:Any...])</code></p> <p>Returns a function that protects <code>fun</code> from receiving non-existy values. Each subsequent value provided to <code>fnull</code> acts as the default to the original <code>fun</code> should a call receive non-existy values in the defaulted arg slots.</p> <pre><code class="lang-javascript">function getLength (val) { return val.length; } safeGetLength = _.fnull(getLength, []); safeGetLength([1, 2, 3]); // => 3 safeGetLength(null); // => 0</code></pre> <hr> <h4 id="functionalize"><a href="#functionalize" name="functionalize">functionalize</a></h4> <p><strong>Signature:</strong> <code>_.functionalize(fun:Function[, default:Any...])</code></p> <p>Takes a method-style function (one which uses <code>this</code>) and pushes <code>this</code> into the argument list. The returned function uses its first argument as the receiver/context of the original function, and the rest of the arguments are used as the original's entire argument list.</p> <pre><code class="lang-javascript">var militaryUnits = { centuria: "80 men", cohort: "480 men", getDescription: function (unitName) { return this[unitName]; } }; var getDescription = _.functionalize(militaryUnits.getDescription); var rulers = { Leonidas: "King of Sparta", Augustus: "First Roman Emperor" }; getDescription(rulers, "Augustus"); // => "First Roman Emperor"</code></pre> <hr> <h4 id="mapargs"><a href="#mapargs" name="mapargs">mapArgs</a></h4> <p><strong>Signature:</strong> <code>_.mapArgs(fun:Function)</code></p> <p>Takes a target function and returns a new function which accepts a mapping function, which in turn returns a function that will map its arguments before calling the original target function.</p> <pre><code class="lang-javascript">function doubleNum (x) { return 2 * x; } function squareNum (x) { return x * x; } var squareThenDouble = _.mapArgs(doubleNum)(squareNum); squareThenDouble(3); // => 18</code></pre> <hr> <h4 id="mapargswith"><a href="#mapargswith" name="mapargswith">mapArgsWith</a></h4> <p><strong>Signature:</strong> <code>_.mapArgs(mapFun:Function)</code></p> <p>Takes a mapping function and returns a new combinator function which will take a target function and return a new version which maps its arguments with the mapping function before executing the body of the target function.</p> <pre><code class="lang-javascript">function doubleNum (x) { return 2 * x; } function squareNum (x) { return x * x; } var squareArgs = _.mapArgsWith(squareNum); var squareThenDouble = squareArgs(doubleNum); squareThenDouble(3); // => 18</code></pre> <hr> <h4 id="methodize"><a href="#methodize" name="methodize">methodize</a></h4> <p><strong>Signature:</strong> <code>_.methodize(func:Function)</code></p> <p>Takes a function and pulls the first argument out of the argument list and into <code>this</code> position. The returned function calls the original with its receiver (<code>this</code>) prepending the argument list. The original is called with a receiver of <code>null</code>.</p> <pre><code class="lang-javascript">function describe (obj) { return obj.name + ": " + obj.description; } var democritus = { name: "Democritus", description: "originator of the atomic hypothesis", describe: _.methodize(describe) }; democritus.describe(); // => "Democritus: originator of the atomic hypothesis"</code></pre> <hr> <h4 id="pipeline"><a href="#pipeline" name="pipeline">pipeline</a></h4> <p><strong>Signature:</strong> <code>_.pipeline(func:Function[, func2:Function...])</code> or <code>_.pipeline(funcArr:Array)</code></p> <p><strong>Aliases:</strong> <code>_.t</code></p> <p>Takes a list of functions, either as an array or as individual arguments and returns a function that takes some value as its first argument and runs it through a pipeline of the original functions given.</p> <pre><code class="lang-javascript">function halveNum (x) { return x / 2; }; function squareNum (x) { return x * x; }; function doubleNum (x) { return 2 * x; }; var halveSquareDouble = _.pipeline(halveNum, squareNum, doubleNum); halveSquareDouble(1); // => 0.5 var doubleSquareHalve = _.pipeline([doubleNum, squareNum, halveNum]); doubleSquareHalve(1); // => 2</code></pre> <hr> <h4 id="splat"><a href="#splat" name="splat">splat</a></h4> <p><strong>Signature:</strong> <code>_.splat(fun:Function)</code></p> <p>Takes a function expecting one or more arguments and returns a function that takes an array and uses its elements as the arguments to the original function. This roughly corresponds to the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator">spread operator</a> in ECMAScript 6.</p> <pre><code class="lang-javascript">function listTwoNames (a, b) { return a.name + " & " + b.name; } var listTwoNamesFromArray = _.splat(listTwoNames); listTwoNamesFromArray([{ name: "Zeno" }, { name: "Parmenides"}]); // => "Zeno & Parmenides"</code></pre> <hr> <h4 id="unsplat"><a href="#unsplat" name="unsplat">unsplat</a></h4> <p><strong>Signature:</strong> <code>_.unsplat(fun:Function)</code></p> <p><strong>Aliases:</strong> <code>_.unsplatr</code></p> <p>Takes a function expecting an array as its <em>last</em> argument and returns a function which works identically, but takes a list of trailing arguments instead. Roughly corresponds to <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions_and_function_scope/rest_parameters">rest parameters</a> in ECMAScript 6.</p> <pre><code class="lang-javascript">function joinWith (joiner, arr) { return arr.join(joiner); } var joinArgsWith = _.unsplat(joinWith); joinArgsWith(" & ", "Plutarch", "Proclus"); // => "Plutarch & Proclus"</code></pre> <hr> <h4 id="unsplatl"><a href="#unsplatl" name="unsplatl">unsplatl</a></h4> <p><strong>Signature:</strong> <code>_.unsplatl(fun:Function)</code></p> <p>Similar to <a href="#unsplat">unsplat</a>, but takes a function expecting an array as its <em>first</em> argument and returns a function which works identically, but takes a list of leading arguments instead. Roughly corresponds to <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions_and_function_scope/rest_parameters">rest parameters</a> in ECMAScript 6.</p> <pre><code class="lang-javascript">function joinWith (arr, joiner) { return arr.join(joiner); } var joinArgsWith = _.unsplat(joinWith); joinArgsWith("Olympiodorus", "Syrianus", " & "); // => "Olympiodorus & Syrianus"</code></pre> <hr> <h3 id="function-iterators"><a href="#function.iterators" name="function.iterators">function.iterators</a></h3> <blockquote> <p>Functions to iterate over collections.</p> </blockquote> <hr> <h4 id="iterators-accumulate"><a href="#iterators.accumulate" name="iterators.accumulate">iterators.accumulate</a></h4> <p><strong>Signature:</strong> <code>_.iterators.accumulate(iter:Function, binaryFn:Function, initial:Any)</code></p> <p>Returns a function that when called will iterate one step with <code>iter</code> and return the value currently accumulated by using <code>binaryFn</code>. The function will return <code>undefined</code> once all values have been iterated over.</p> <pre><code class="lang-javascript">var generalsIterator = _.iterators.List(["Hannibal", "Scipio"]); function countLetters(memo, element) { return memo + element.length; } var generalsAcc = _.iterators.accumulate(generalsIterator, countLetters, 0); generalsAcc(); // => 8 generalsAcc(); //