lodash-contrib
Version:
The brass buckles on lodash's utility belt
439 lines (286 loc) • 9.37 kB
Markdown
Examples for combinator functions
==============================
`_.function.combinators.js` contains functions that allow to build blocks of logic via
the application of smaller functions.
Each section gives use cases showing how a given function could be used.
* [_.bound](#_boundobj-fname)
* [_.comparator](#_comparatorfun)
* [_.complement](#_complementpred)
* [_.conjoin](#_conjoinpredicates)
* [_.disjoin](#_disjoinpredicates)
* [_.flip](#_flipfun)
* [_.flip2](#_flip2fun)
* [_.fnull](#_fnullfun--defaults)
* [_.functionalize](#_functionalizemethod)
* [_.juxt](#_juxtfuns)
* [_.mapArgs](#_mapargs)
* [_.mapArgsWith](#_mapargswith)
* [_.methodize](#_methodizefunc)
* [_.pipeline](#_pipelinefunctions)
* [_.splat](#_splatfun)
* [_.unsplat](#_unsplatfun)
* [_.unsplatl](#_unsplatlfun)
For some more insights have a look at [the tests](https://github.com/node4good/lodash-contrib/blob/master/test/function.combinators.js).
_.bound(obj, fname)
-------------------
Returns the function property of `obj` by `fname`, bound to `obj`.
**Arguments**
1. `obj` (Object): The object that holds the property.
2. `fname` name of the property.
**Results**
(Function): Returns a function bound to `obj`.
**Example**
```javascript
var obj = {
fun: function(b) {
return this.a + b;
},
a: 'hello ',
nofun: null
};
var f = _.bound(obj, 'fun');
f('there') // → 'hello there'
```
_.comparator(fun)
-----------------
Takes a predicate-like and returns a comparator (-1, 0, 1).
**Arguments**
1. `fun` (Function): The function from which we the comparator get created.
**Returns**
(integer): Returns `-1` if `fun(x, y)` evaluates to a truthy value, `1` if `fun(y, x)` evaluates
to a falsy value, 0 otherwise.
**Example**
```javascript
var lessThan = _.comparator(function(x, y) { return x < y });
lessThan(1, 2); // → -1
lessThan(3, 2); // → 1
lessThan(2, 2); // → 0
```
_.complement(pred)
-----------------
Returns a function that reverses the sense of a given predicate-like.
**Arguments**
1. `pred` (Function): Predicate that will be reverted and applied to the arguments.
**Returns**
(boolean): Returns the negation of the result that `pred` would have returned.
**Example**
```javascript
// every value is ok except String
_.filter(['removeme', 1, true], _.complement(_.isString));
```
_.conjoin(predicates)
---------------------------
Composes a bunch of predicates into a single predicate that
checks all elements of an array for conformance to all of the
original predicates.
**Arguments**
1. `predicates` (Array|Object): The collection of predicates.
**Returns**
(boolean): Rerturns `true` if all elements satisfy the `predicates`, `false` otherwise.
**Example**
```javascript
function isBlue(o) { return o.color == 'blue' }
function isSquare(o) { return o.shape == 'square' }
var blueSquares = _.conjoin(isBlue, isSquare);
var objects = [{
color: 'red',
shape: 'square',
location: 'kitchen'
}, {
color: 'blue',
shape: 'square',
location: 'garden'
}];
blueSquares(objects) // → false
blueSquares([objects[1]]) // → true
```
_.disjoin(predicates)
------------------------------
Composes a bunch of predicates into a single predicate that
checks all elements of an array for conformance to any of the
original predicates.
**Arguments**
1. `predicates` (Array|Object): The collection of predicates.
**Returns**
(boolean): Returns true if any array elements satisfy any of the `predicates`, false otherwise.
**Example**
```javascript
function isBlue(o) { return o.color == 'blue' }
function isSquare(o) { return o.shape == 'square' }
var blueSquares = _.conjoin(isBlue, isSquare);
var objects = [{
color: 'red',
shape: 'square',
location: 'kitchen'
}, {
color: 'blue',
shape: 'square',
location: 'garden'
}];
blueSquares(objects) // → true
```
_.flip(fun)
-----------
Flips an arbitrary number of args of a function.
**Arguments**
1. `fun` (Function): The function whose arguments will be flipped.
**Returns**
Result of `fun` applied to the arguments.
**Example**
```javascript
var echo = function() { return Array.prototype.slice.call(arguments, 0); };
deepEqual(_.flip(echo)(1, 2, 3, 4), [4, 3, 2, 1]
```
_.flip2(fun)
------------
Flips the first two arguments of a function.
**Arguments**
1. `fun` (Function): The function whose first two arguments will be flipped.
**Returns**
Result of `fun` applied to the arguments.
**Example**
```javascript
var div = function(n, d) { return n/d; };
_.flip2(div)(10, 2) // → 0.2
```
_.fnull(fun [, defaults])
----------------------------
Returns a function that protects a given function from receiving non-existy values.
Each subsequent value provided to `fnull` acts as the default to the original function
should a call receive non-existy values in the defaulted arg slots.
**Arguments**
1. `fun` (Function): The function that is going to be protected against non-existy values.
2. `defaults`: a collection of default values
**Returns**
Result of `fun` applied to the arguments, using the provided defaults if any non-existy values
are found.
**Example**
```javascript
var a = [1, 2, 3, null, 5];
var safeMult = _.fnull(function(total, n) { return total * n; }, 1, 1);
_.reduce(a, safeMult) // → 30
```
_.functionalize(method)
-----------------------
Takes a method-style function (one which uses `this`) and pushes
`this` 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.
**Arguments**
1. `method` (Function): A method-style function.
**Returns**
Result of `method` applied to the arguments.
**Example**
```javascript
var rect = {
x: 2,
y: 3,
area: function() {return this.x * this.y;},
extrude: function(z) {return _.merge(this, {z: z});}
};
var areaFunc = _.functionalize(rect.area),
extrudeFunc = _.functionalize(rect.extrude);
areaFunc(rect) // → 6
```
_.juxt(funs)
------------------
Returns a function that returns an array of the calls to each given function for some arguments.
**Arguments**
1. `funs` (Array): The array of functions.
**Returns**
(Array): containing the results of the application of each function to the passed arguments.
**Example**
```javascript
var run = _.juxt(function(s, n) { return s.length + n; }, parseInt);
run('42', 10) // → [12, 42]
```
_.mapArgs()
---------------
Maps the arguments of a function, takes the mapping function first so it can be used as a combinator.
// TODO
_.mapArgsWith()
---------------
// TODO
_.methodize(func)
-----------------
Takes a function and pulls the first argument out of the argument
list and into `this` position. The returned function calls the original
with its receiver (`this`) prepending the argument list. The original
is called with a receiver of `null`.
**Arguments**
1. `func` (Function): The function which will be invoked with `null` as context.
**Returns**
Returns the result of `method` applied to the arguments.
**Example**
```javascript
function area(rect) { return rect.x * rect.y; }
var rect = {
x: 2,
y: 3,
area: _.methodize(area)
};
rect.area() // → 6
```
_.pipeline(functions)
---------------------------
Takes some number of functions, either as an array or variadically
and returns a function that takes some value as its first argument
and runs it through a pipeline of the original functions given.
**Aliases**
`_.t`
**Arguments**
1. `functions` (Array|Object): The collection of functions, either in an array or passed one by one.
**Returns**
(Object): Returns the result of the pipelined application of all `functions`.
**Example**
```javascript
var double = function(arr) { return _.map(arr, function(n) { return 2 * n }); }
var filterOdd = function(arr) {
return _.filter(arr, _.isOdd);
};
var doubleOdd = _.pipeline(filterOdd, double);
doubleOdd([1,2,3,4]); // → [2, 6]
```
_.splat(fun)
------------
Takes a function expecting varargs and returns a function that takes an array and
uses its elements as the args to the original function
**Arguments**
1. `fun` that takes varargs
**Returns**
Result of `fun` applied to the arguments.
**Example**
```javascript
var sumArgs = function () {
return _.reduce(arguments, function (a, b) { return a + b; }, 0);
};
var sumArray = _.splat(sumArgs);
sumArray([1, 2, 3]) // → 6
```
_.unsplat(fun)
--------------
Takes a function expecting an array and returns a function that takes varargs and wraps all
in an array that is passed to the original function.
**Aliases**
`_.unsplatr`
**Arguments**
1. `fun` (Function): The function that will be applied.
**Returns**
Result of `fun` applied to the arguments.
**Example**
```javascript
var echo3 = _.unsplat(function (first, second, rest) { return [first, second, rest]; });
echo3(1, 2, 3, 4) // → [1, 2, [3, 4]]
```
_.unsplatl(fun)
---------------
Same as unsplat, but the rest of the arguments are collected in the first parameter.
**Arguments**
1. `fun` (Function): The function that will be applied.
**Returns**
Result of `fun` applied to the arguments.
**Example**
```javascript
var echo3 = _.unsplatl(function (rest, penultimate, ultimate) { return [rest, penultimate, ultimate]; });
echo3(1, 2, 3, 4) // → [[1, 2], 3, 4]
```