• Jump To … +
    builders-examples.js.md combinators-examples.js.md walk-examples.js.md
  • ¶

    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
    • _.comparator
    • _.complement
    • _.conjoin
    • _.disjoin
    • _.flip
    • _.flip2
    • _.fnull
    • _.functionalize
    • _.juxt
    • _.mapArgs
    • _.mapArgsWith
    • _.methodize
    • _.pipeline
    • _.splat
    • _.unsplat
    • _.unsplatl

    For some more insights have a look at the tests.

    _.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

    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

    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

    // 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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    var echo3 = _.unsplatl(function (rest, penultimate, ultimate) { return [rest, penultimate, ultimate]; });
    echo3(1, 2, 3, 4) // → [[1, 2], 3, 4]