_.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.
For some more insights have a look at the tests.
Returns the function property of obj
by fname
, bound to obj
.
Arguments
obj
(Object): The object that holds the property.fname
name of the property.Results
(Function): Returns a function bound to obj
.
Example
var obj = {
fun: function(b) {
return this.a + b;
},
a: 'hello ',
nofun: null
};
var f = _.bound(obj, 'fun');
f('there') // → 'hello there'
Takes a predicate-like and returns a comparator (-1, 0, 1).
Arguments
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
var lessThan = _.comparator(function(x, y) { return x < y });
lessThan(1, 2); // → -1
lessThan(3, 2); // → 1
lessThan(2, 2); // → 0
Returns a function that reverses the sense of a given predicate-like.
Arguments
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
// every value is ok except String
_.filter(['removeme', 1, true], _.complement(_.isString));
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
predicates
(Array|Object): The collection of predicates.Returns
(boolean): Rerturns true
if all elements satisfy the predicates
, false
otherwise.
Example
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
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
predicates
(Array|Object): The collection of predicates.Returns
(boolean): Returns true if any array elements satisfy any of the predicates
, false otherwise.
Example
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
Flips an arbitrary number of args of a function.
Arguments
fun
(Function): The function whose arguments will be flipped.Returns
Result of fun
applied to the arguments.
Example
var echo = function() { return Array.prototype.slice.call(arguments, 0); };
deepEqual(_.flip(echo)(1, 2, 3, 4), [4, 3, 2, 1]
Flips the first two arguments of a function.
Arguments
fun
(Function): The function whose first two arguments will be flipped.Returns
Result of fun
applied to the arguments.
Example
var div = function(n, d) { return n/d; };
_.flip2(div)(10, 2) // → 0.2
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
fun
(Function): The function that is going to be protected against non-existy values.defaults
: a collection of default valuesReturns
Result of fun
applied to the arguments, using the provided defaults if any non-existy values
are found.
Example
var a = [1, 2, 3, null, 5];
var safeMult = _.fnull(function(total, n) { return total * n; }, 1, 1);
_.reduce(a, safeMult) // → 30
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
method
(Function): A method-style function.Returns
Result of method
applied to the arguments.
Example
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
Returns a function that returns an array of the calls to each given function for some arguments.
Arguments
funs
(Array): The array of functions.Returns
(Array): containing the results of the application of each function to the passed arguments.
Example
var run = _.juxt(function(s, n) { return s.length + n; }, parseInt);
run('42', 10) // → [12, 42]
Maps the arguments of a function, takes the mapping function first so it can be used as a combinator.
// TODO
// TODO
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
func
(Function): The function which will be invoked with null
as context.Returns
Returns the result of method
applied to the arguments.
Example
function area(rect) { return rect.x * rect.y; }
var rect = {
x: 2,
y: 3,
area: _.methodize(area)
};
rect.area() // → 6
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
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
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]
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
fun
that takes varargsReturns
Result of fun
applied to the arguments.
Example
var sumArgs = function () {
return _.reduce(arguments, function (a, b) { return a + b; }, 0);
};
var sumArray = _.splat(sumArgs);
sumArray([1, 2, 3]) // → 6
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
fun
(Function): The function that will be applied.Returns
Result of fun
applied to the arguments.
Example
var echo3 = _.unsplat(function (first, second, rest) { return [first, second, rest]; });
echo3(1, 2, 3, 4) // → [1, 2, [3, 4]]
Same as unsplat, but the rest of the arguments are collected in the first parameter.
Arguments
fun
(Function): The function that will be applied.Returns
Result of fun
applied to the arguments.
Example
var echo3 = _.unsplatl(function (rest, penultimate, ultimate) { return [rest, penultimate, ultimate]; });
echo3(1, 2, 3, 4) // → [[1, 2], 3, 4]