lodash-contrib
Version:
The brass buckles on lodash's utility belt
658 lines (475 loc) • 27.5 kB
HTML
<html>
<head>
<title>_.function.combinators.js.md</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
<link rel="stylesheet" media="all" href="docco.css" />
</head>
<body>
<div id="container">
<div id="background"></div>
<ul id="jump_to">
<li>
<a class="large" href="javascript:void(0);">Jump To …</a>
<a class="small" href="javascript:void(0);">+</a>
<div id="jump_wrapper">
<div id="jump_page_wrapper">
<div id="jump_page">
<a class="source" href="_.array.builders.js.html">
_.array.builders.js.md
</a>
<a class="source" href="_.array.selectors.js.html">
_.array.selectors.js.md
</a>
<a class="source" href="_.collections.walk.js.html">
_.collections.walk.js.md
</a>
<a class="source" href="_.function.arity.js.html">
_.function.arity.js.md
</a>
<a class="source" href="_.function.combinators.js.html">
_.function.combinators.js.md
</a>
<a class="source" href="_.function.iterators.js.html">
_.function.iterators.js.md
</a>
<a class="source" href="_.function.predicates.js.html">
_.function.predicates.js.md
</a>
<a class="source" href="_.object.builders.js.html">
_.object.builders.js.md
</a>
<a class="source" href="_.object.selectors.js.html">
_.object.selectors.js.md
</a>
<a class="source" href="_.util.existential.js.html">
_.util.existential.js.md
</a>
<a class="source" href="_.util.operators.js.html">
_.util.operators.js.md
</a>
<a class="source" href="_.util.strings.js.html">
_.util.strings.js.md
</a>
<a class="source" href="_.util.trampolines.js.html">
_.util.trampolines.js.md
</a>
<a class="source" href="index.html">
index.md
</a>
</div>
</div>
</li>
</ul>
<ul class="sections">
<li id="title">
<div class="annotation">
<h1>_.function.combinators.js.md</h1>
</div>
</li>
<li id="section-1">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-1">¶</a>
</div>
<h3 id="function-combinators">function.combinators</h3>
<blockquote>
<p>Functions that are combinators.</p>
</blockquote>
<hr>
</div>
</li>
<li id="section-2">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-2">¶</a>
</div>
<h4 id="always">always</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"><span class="hljs-keyword">var</span> platonicForm = _.always(<span class="hljs-string">"Eternal & Unchangeable"</span>);
platonicForm();
<span class="hljs-comment">// => "Eternal & Unchangeable"</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-3">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-3">¶</a>
</div>
<h4 id="bound">bound</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"><span class="hljs-keyword">var</span> aristotle = {
name: <span class="hljs-string">"Aristotle"</span>,
telos: <span class="hljs-string">"flourishing"</span>,
stateTelos: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.name + <span class="hljs-string">"'s telos is "</span> + <span class="hljs-keyword">this</span>.telos;
}
};
<span class="hljs-keyword">var</span> stateAristotlesTelos = _.bound(aristotle, <span class="hljs-string">"stateTelos"</span>);
stateAristotlesTelos();
<span class="hljs-comment">// => "Aristotle's Telos is flourishing"</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-4">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-4">¶</a>
</div>
<h4 id="comparator">comparator</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"><span class="hljs-keyword">var</span> lessOrEqual = <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">x, y</span>) </span>{ <span class="hljs-keyword">return</span> x <= y; };
<span class="hljs-keyword">var</span> arr = [<span class="hljs-number">0</span>, <span class="hljs-number">1</span>, -<span class="hljs-number">2</span>];
arr.sort(_.comparator(lessOrEqual));
<span class="hljs-comment">// => [-2, 0, 1]</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-5">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-5">¶</a>
</div>
<h4 id="complement">complement</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">isAugustine</span> (<span class="hljs-params">val</span>) </span>{
<span class="hljs-keyword">return</span> val === <span class="hljs-string">"Augustine"</span>;
}
isNotAugustine = _.complement(isAugustine);
isNotAugustine(<span class="hljs-string">"Dionysius"</span>);
<span class="hljs-comment">// => True</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-6">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-6">¶</a>
</div>
<h4 id="conjoin">conjoin</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">startsWithA</span> (<span class="hljs-params">val</span>) </span>{
<span class="hljs-keyword">return</span> val[<span class="hljs-number">0</span>] === <span class="hljs-string">"A"</span>;
}
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">endsWithE</span> (<span class="hljs-params">val</span>) </span>{
<span class="hljs-keyword">return</span> val[val.length - <span class="hljs-number">1</span>] === <span class="hljs-string">"e"</span>;
}
<span class="hljs-keyword">var</span> names = [<span class="hljs-string">"Aristotle"</span>, <span class="hljs-string">"Aquinas"</span>, <span class="hljs-string">"Plato"</span>, <span class="hljs-string">"Augustine"</span>];
<span class="hljs-keyword">var</span> startsAAndEndsE = _.conjoin(startsWithA, endsWithE);
startsAAndEndsE(names);
<span class="hljs-comment">// => ["Aristotle", "Augustine"]</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-7">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-7">¶</a>
</div>
<h4 id="disjoin">disjoin</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">startsWithA</span> (<span class="hljs-params">val</span>) </span>{
<span class="hljs-keyword">return</span> val[<span class="hljs-number">0</span>] === <span class="hljs-string">"A"</span>;
}
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">endsWithE</span> (<span class="hljs-params">val</span>) </span>{
<span class="hljs-keyword">return</span> val[val.length - <span class="hljs-number">1</span>] === <span class="hljs-string">"e"</span>;
}
<span class="hljs-keyword">var</span> names = [<span class="hljs-string">"Aristotle"</span>, <span class="hljs-string">"Aquinas"</span>, <span class="hljs-string">"Plato"</span>, <span class="hljs-string">"Augustine"</span>];
<span class="hljs-keyword">var</span> startsAOrEndsE = _.disjoin(startsWithA, endsWithE);
startsAOrEndsE(names);
<span class="hljs-comment">// => ["Aristotle", "Aquinas", "Augustine"]</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-8">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-8">¶</a>
</div>
<h4 id="juxt">juxt</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">firstChar</span> (<span class="hljs-params">val</span>) </span>{
<span class="hljs-keyword">return</span> val[<span class="hljs-number">0</span>];
}
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">lastChar</span> (<span class="hljs-params">val</span>) </span>{
<span class="hljs-keyword">return</span> val[val.length - <span class="hljs-number">1</span>];
}
<span class="hljs-keyword">var</span> firstAndLastChars = _.juxt(firstChar, lastChar);
firstAndLastChars(<span class="hljs-string">"Etruria"</span>);
<span class="hljs-comment">// => ["E", "a"]</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-9">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-9">¶</a>
</div>
<h4 id="flip">flip</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">regionCapitol</span> (<span class="hljs-params">region, capitol</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-string">"The capitol of "</span> + region + <span class="hljs-string">" is "</span> + capitol;
}
capitolRegion = _.flip(regionCapitol);
capitolRegion(<span class="hljs-string">"Thessalonica"</span>, <span class="hljs-string">"Illyrica"</span>);
<span class="hljs-comment">// => "The capitol of Illyrica is Thessalonica"</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-10">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-10">¶</a>
</div>
<h4 id="flip2">flip2</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">regionCapitol</span> (<span class="hljs-params">region, capitol</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-string">"The capitol of "</span> + region + <span class="hljs-string">" is "</span> + capitol;
}
capitolRegion = _.flip2(regionCapitol);
capitolRegion(<span class="hljs-string">"Thessalonica"</span>, <span class="hljs-string">"Illyrica"</span>);
<span class="hljs-comment">// => "The capitol of Illyrica is Thessalonica"</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-11">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-11">¶</a>
</div>
<h4 id="fnull">fnull</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">getLength</span> (<span class="hljs-params">val</span>) </span>{
<span class="hljs-keyword">return</span> val.length;
}
safeGetLength = _.fnull(getLength, []);
safeGetLength([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>]);
<span class="hljs-comment">// => 3</span>
safeGetLength(<span class="hljs-literal">null</span>);
<span class="hljs-comment">// => 0</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-12">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-12">¶</a>
</div>
<h4 id="functionalize">functionalize</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"><span class="hljs-keyword">var</span> militaryUnits = {
centuria: <span class="hljs-string">"80 men"</span>,
cohort: <span class="hljs-string">"480 men"</span>,
getDescription: <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">unitName</span>) </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>[unitName];
}
};
<span class="hljs-keyword">var</span> getDescription = _.functionalize(militaryUnits.getDescription);
<span class="hljs-keyword">var</span> rulers = {
Leonidas: <span class="hljs-string">"King of Sparta"</span>,
Augustus: <span class="hljs-string">"First Roman Emperor"</span>
};
getDescription(rulers, <span class="hljs-string">"Augustus"</span>);
<span class="hljs-comment">// => "First Roman Emperor"</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-13">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-13">¶</a>
</div>
<h4 id="mapargs">mapArgs</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">doubleNum</span> (<span class="hljs-params">x</span>) </span>{ <span class="hljs-keyword">return</span> <span class="hljs-number">2</span> * x; }
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">squareNum</span> (<span class="hljs-params">x</span>) </span>{ <span class="hljs-keyword">return</span> x * x; }
<span class="hljs-keyword">var</span> squareThenDouble = _.mapArgs(doubleNum)(squareNum);
squareThenDouble(<span class="hljs-number">3</span>);
<span class="hljs-comment">// => 18</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-14">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-14">¶</a>
</div>
<h4 id="mapargswith">mapArgsWith</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">doubleNum</span> (<span class="hljs-params">x</span>) </span>{ <span class="hljs-keyword">return</span> <span class="hljs-number">2</span> * x; }
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">squareNum</span> (<span class="hljs-params">x</span>) </span>{ <span class="hljs-keyword">return</span> x * x; }
<span class="hljs-keyword">var</span> squareArgs = _.mapArgsWith(squareNum);
<span class="hljs-keyword">var</span> squareThenDouble = squareArgs(doubleNum);
squareThenDouble(<span class="hljs-number">3</span>);
<span class="hljs-comment">// => 18</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-15">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-15">¶</a>
</div>
<h4 id="methodize">methodize</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">describe</span> (<span class="hljs-params">obj</span>) </span>{
<span class="hljs-keyword">return</span> obj.name + <span class="hljs-string">": "</span> + obj.description;
}
<span class="hljs-keyword">var</span> democritus = {
name: <span class="hljs-string">"Democritus"</span>,
description: <span class="hljs-string">"originator of the atomic hypothesis"</span>,
describe: _.methodize(describe)
};
democritus.describe();
<span class="hljs-comment">// => "Democritus: originator of the atomic hypothesis"</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-16">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-16">¶</a>
</div>
<h4 id="pipeline">pipeline</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"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">halveNum</span> (<span class="hljs-params">x</span>) </span>{ <span class="hljs-keyword">return</span> x / <span class="hljs-number">2</span>; };
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">squareNum</span> (<span class="hljs-params">x</span>) </span>{ <span class="hljs-keyword">return</span> x * x; };
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">doubleNum</span> (<span class="hljs-params">x</span>) </span>{ <span class="hljs-keyword">return</span> <span class="hljs-number">2</span> * x; };
<span class="hljs-keyword">var</span> halveSquareDouble = _.pipeline(halveNum, squareNum, doubleNum);
halveSquareDouble(<span class="hljs-number">1</span>);
<span class="hljs-comment">// => 0.5</span>
<span class="hljs-keyword">var</span> doubleSquareHalve = _.pipeline([doubleNum, squareNum, halveNum]);
doubleSquareHalve(<span class="hljs-number">1</span>);
<span class="hljs-comment">// => 2</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-17">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-17">¶</a>
</div>
<h4 id="splat">splat</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 [spread operator][spread] in
ECMAScript 6.</p>
<pre><code class="lang-javascript"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">listTwoNames</span> (<span class="hljs-params">a, b</span>) </span>{
<span class="hljs-keyword">return</span> a.name + <span class="hljs-string">" & "</span> + b.name;
}
<span class="hljs-keyword">var</span> listTwoNamesFromArray = _.splat(listTwoNames);
listTwoNamesFromArray([{ name: <span class="hljs-string">"Zeno"</span> }, { name: <span class="hljs-string">"Parmenides"</span>}]);
<span class="hljs-comment">// => "Zeno & Parmenides"</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-18">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-18">¶</a>
</div>
<h4 id="unsplat">unsplat</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 [rest parameters][rest] in ECMAScript 6.</p>
<pre><code class="lang-javascript"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">joinWith</span> (<span class="hljs-params">joiner, arr</span>) </span>{
<span class="hljs-keyword">return</span> arr.join(joiner);
}
<span class="hljs-keyword">var</span> joinArgsWith = _.unsplat(joinWith);
joinArgsWith(<span class="hljs-string">" & "</span>, <span class="hljs-string">"Plutarch"</span>, <span class="hljs-string">"Proclus"</span>);
<span class="hljs-comment">// => "Plutarch & Proclus"</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-19">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-19">¶</a>
</div>
<h4 id="unsplatl">unsplatl</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
[rest parameters][rest] in ECMAScript 6.</p>
<pre><code class="lang-javascript"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">joinWith</span> (<span class="hljs-params">arr, joiner</span>) </span>{
<span class="hljs-keyword">return</span> arr.join(joiner);
}
<span class="hljs-keyword">var</span> joinArgsWith = _.unsplat(joinWith);
joinArgsWith(<span class="hljs-string">"Olympiodorus"</span>, <span class="hljs-string">"Syrianus"</span>, <span class="hljs-string">" & "</span>);
<span class="hljs-comment">// => "Olympiodorus & Syrianus"</span>
</code></pre>
<hr>
</div>
</li>
<li id="section-20">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-20">¶</a>
</div>
</div>
</li>
</ul>
</div>
</body>
</html>