## org.apache.mahout.math.function
Class Functions

    java.lang.Object
      org.apache.mahout.math.function.Functions

    public final class Functions

extends java.lang.Object

Function objects to be passed to generic methods. Contains the functions of `Math` as function objects, as well as a few more basic functions.

Function objects conveniently allow to express arbitrary functions in a generic manner. Essentially, a function object is an object that can perform a function on some arguments. It has a minimal interface: a method `apply` that takes the arguments, computes something and returns some result value. Function objects are comparable to function pointers in C used for call-backs.

Unary functions are of type `UnaryFunction`, binary functions of type `BinaryFunction`. All can be retrieved via `public static final` variables named after the function. Unary predicates are of type `DoubleProcedure`, binary predicates of type `DoubleDoubleProcedure`. All can be retrieved via `public static final` variables named `isXXX`.

Binary functions and predicates also exist as unary functions with the second argument being fixed to a constant. These are generated and retrieved via factory methods (again with the same name as the function). Example:

- `Functions.pow` gives the function `ab`.
- `Functions.pow.apply(2,3)==8`.
- `Functions.pow(3)` gives the function `a3`.
- `Functions.pow(3).apply(2)==8`.

More general, any binary function can be made an unary functions by fixing either the first or the second argument. See methods `bindArg1(org.apache.mahout.math.function.BinaryFunction ,double)` and `bindArg2(org.apache.mahout.math.function.BinaryFunction ,double)`. The order of arguments can be swapped so that the first argument becomes the second and vice-versa. See method `swapArgs(org.apache.mahout.math.function.BinaryFunction)`. Example:

- `Functions.pow` gives the function `ab`.
- `Functions.bindArg2(Functions.pow,3)` gives the function `x3`.
- `Functions.bindArg1(Functions.pow,3)` gives the function `3x`.
- `Functions.swapArgs(Functions.pow)` gives the function `ba`.

Even more general, functions can be chained (composed, assembled). Assume we have two unary functions `g` and `h`. The unary function `g(h(a))` applying both in sequence can be generated via `chain(org.apache.mahout.math.function.UnaryFunction , org.apache.mahout.math.function.UnaryFunction)`:

- `Functions.chain(g,h);`

Assume further we have a binary function `f`. The binary function `g(f(a,b))` can be generated via `chain(org.apache.mahout.math.function.UnaryFunction , org.apache.mahout.math.function.BinaryFunction)`:

- `Functions.chain(g,f);`

The binary function `f(g(a),h(b))` can be generated via `chain(org.apache.mahout.math.function.BinaryFunction , org.apache.mahout.math.function.UnaryFunction , org.apache.mahout.math.function.UnaryFunction)`:

- `Functions.chain(f,g,h);`

Arbitrarily complex functions can be composed from these building blocks. For example `sin(a) + cos2(b)` can be specified as follows:

- `chain(plus,sin,chain(square,cos));`

or, of course, as

     new BinaryFunction() {
        public final double apply(double a, double b) { return Math.sin(a) + Math.pow(Math.cos(b),2); }
     }

For aliasing see functions. Try this

     // should yield 1.4399560356056456 in all cases
     double a = 0.5;
     double b = 0.2;
     double v = Math.sin(a) + Math.pow(Math.cos(b),2);
     log.info(v);
     Functions F = Functions.functions;
     BinaryFunction f = F.chain(F.plus,F.sin,F.chain(F.square,F.cos));
     log.info(f.apply(a,b));
     BinaryFunction g = new BinaryFunction() {
        public double apply(double a, double b) { return Math.sin(a) + Math.pow(Math.cos(b),2); }
     };
     log.info(g.apply(a,b));

### Performance

Surprise. Using modern non-adaptive JITs such as SunJDK 1.2.2 (java -classic) there seems to be no or only moderate performance penalty in using function objects in a loop over traditional code in a loop. For complex nested function objects (e.g. `F.chain(F.abs,F.chain(F.plus,F.sin,F.chain(F.square,F.cos)))`) the penalty is zero, for trivial functions (e.g. `F.plus`) the penalty is often acceptable.

Iteration Performance [million function evaluations per second] Pentium Pro 200 Mhz, SunJDK 1.2.2, NT, java -classic,
| 30000000 iterations | 3000000 iterations (10 times less) |
`F.plus` | `a+b` | `F.chain(F.abs,F.chain(F.plus,F.sin,F.chain(F.square,F.cos)))` | `Math.abs(Math.sin(a) + Math.pow(Math.cos(b),2))` |  |
| 10.8 | 29.6 | 0.43 | 0.35 |  |

Field Summary
`static UnaryFunction` `ABS` Function that returns `Math.abs(a)`.
`static UnaryFunction` `ACOS` Function that returns `Math.acos(a)`.
`static UnaryFunction` `ASIN` Function that returns `Math.asin(a)`.
`static UnaryFunction` `ATAN` Function that returns `Math.atan(a)`.
`static BinaryFunction` `ATAN2` Function that returns `Math.atan2(a,b)`.
`static UnaryFunction` `CEIL` Function that returns `Math.ceil(a)`.
`static BinaryFunction` `COMPARE` Function that returns `a < b ? -1 : a > b ? 1 : 0`.
`static UnaryFunction` `COS` Function that returns `Math.cos(a)`.
`static BinaryFunction` `DIV` Function that returns `a / b`.
`static BinaryFunction` `EQUALS` Function that returns `a == b ? 1 : 0`.
`static UnaryFunction` `EXP` Function that returns `Math.exp(a)`.
`static UnaryFunction` `FLOOR` Function that returns `Math.floor(a)`.
`static BinaryFunction` `GREATER` Function that returns `a > b ? 1 : 0`.
`static UnaryFunction` `IDENTITY` Function that returns its argument.
`static BinaryFunction` `IEEE_REMAINDER` Function that returns `Math.IEEEremainder(a,b)`.
`static UnaryFunction` `INV` Function that returns `1.0 / a`.
`static org.apache.mahout.math.function.DoubleDoubleProcedure` `IS_EQUAL` Function that returns `a == b`.
`static org.apache.mahout.math.function.DoubleDoubleProcedure` `IS_GREATER` Function that returns `a > b`.
`static org.apache.mahout.math.function.DoubleDoubleProcedure` `IS_LESS` Function that returns `a < b`.
`static BinaryFunction` `LESS` Function that returns `a < b ? 1 : 0`.
`static BinaryFunction` `LG` Function that returns `Math.log(a) / Math.log(b)`.
`static UnaryFunction` `LOG2` Function that returns `Math.log(a) / Math.log(2)`.
`static UnaryFunction` `LOGARITHM` Function that returns `Math.log(a)`.
`static BinaryFunction` `MAX` Function that returns `Math.max(a,b)`.
`static BinaryFunction` `MIN` Function that returns `Math.min(a,b)`.
`static BinaryFunction` `MINUS` Function that returns `a - b`.
`static BinaryFunction` `MOD` Function that returns `a % b`.
`static BinaryFunction` `MULT` Function that returns `a * b`.
`static UnaryFunction` `NEGATE` Function that returns `-a`.
`static BinaryFunction` `PLUS` Function that returns `a + b`.
`static BinaryFunction` `PLUS_ABS` Function that returns `Math.abs(a) + Math.abs(b)`.
`static BinaryFunction` `POW` Function that returns `Math.pow(a,b)`.
`static UnaryFunction` `RINT` Function that returns `Math.rint(a)`.
`static UnaryFunction` `SIGN` Function that returns `a < 0 ? -1 : a > 0 ? 1 : 0`.
`static UnaryFunction` `SIN` Function that returns `Math.sin(a)`.
`static UnaryFunction` `SQRT` Function that returns `Math.sqrt(a)`.
`static UnaryFunction` `SQUARE` Function that returns `a * a`.
`static UnaryFunction` `TAN` Function that returns `Math.tan(a)`.

Method Summary
`static UnaryFunction` `between(double from, double to)` Constructs a function that returns `(from<=a && a<=to) ? 1 : 0`.
`static UnaryFunction` `bindArg1(BinaryFunction function, double c)` Constructs a unary function from a binary function with the first operand (argument) fixed to the given constant `c`.
`static UnaryFunction` `bindArg2(BinaryFunction function, double c)` Constructs a unary function from a binary function with the second operand (argument) fixed to the given constant `c`.
`static BinaryFunction` `chain(BinaryFunction f, UnaryFunction g, UnaryFunction h)` Constructs the function `f( g(a), h(b) )`.
`static BinaryFunction` `chain(UnaryFunction g, BinaryFunction h)` Constructs the function `g( h(a,b) )`.
`static UnaryFunction` `chain(UnaryFunction g, UnaryFunction h)` Constructs the function `g( h(a) )`.
`static UnaryFunction` `compare(double b)` Constructs a function that returns `a < b ? -1 : a > b ? 1 : 0`.
`static UnaryFunction` `constant(double c)` Constructs a function that returns the constant `c`.
`static UnaryFunction` `div(double b)` Constructs a function that returns `a / b`.
`static UnaryFunction` `equals(double b)` Constructs a function that returns `a == b ? 1 : 0`.
`static UnaryFunction` `greater(double b)` Constructs a function that returns `a > b ? 1 : 0`.
`static UnaryFunction` `IEEEremainder(double b)` Constructs a function that returns `Math.IEEEremainder(a,b)`.
`static org.apache.mahout.math.function.DoubleProcedure` `isBetween(double from, double to)` Constructs a function that returns `from<=a && a<=to`.
`static org.apache.mahout.math.function.DoubleProcedure` `isEqual(double b)` Constructs a function that returns `a == b`.
`static org.apache.mahout.math.function.DoubleProcedure` `isGreater(double b)` Constructs a function that returns `a > b`.
`static org.apache.mahout.math.function.DoubleProcedure` `isLess(double b)` Constructs a function that returns `a < b`.
`static UnaryFunction` `less(double b)` Constructs a function that returns `a < b ? 1 : 0`.
`static UnaryFunction` `lg(double b)` Constructs a function that returns ``Math.log(a) / Math.log(b)``.
`static UnaryFunction` `max(double b)` Constructs a function that returns `Math.max(a,b)`.
`static UnaryFunction` `min(double b)` Constructs a function that returns `Math.min(a,b)`.
`static UnaryFunction` `minus(double b)` Constructs a function that returns `a - b`.
`static BinaryFunction` `minusMult(double constant)` Constructs a function that returns `a - b*constant`.
`static UnaryFunction` `mod(double b)` Constructs a function that returns `a % b`.
`static UnaryFunction` `mult(double b)` Constructs a function that returns `a * b`.
`static UnaryFunction` `plus(double b)` Constructs a function that returns `a + b`.
`static BinaryFunction` `plusMult(double constant)` Constructs a function that returns `a + b*constant`.
`static UnaryFunction` `pow(double b)` Constructs a function that returns `Math.pow(a,b)`.
`static UnaryFunction` `random()` Constructs a function that returns a new uniform random number in the open unit interval `(0.0,1.0)` (excluding 0.0 and 1.0).
`static UnaryFunction` `round(double precision)` Constructs a function that returns the number rounded to the given precision; `Math.rint(a/precision)*precision`.
`static BinaryFunction` `swapArgs(BinaryFunction function)` Constructs a function that returns `function.apply(b,a)`, i.e.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### ABS

    public static final UnaryFunction ABS

  Function that returns `Math.abs(a)`.

### ACOS

    public static final UnaryFunction ACOS

  Function that returns `Math.acos(a)`.

### ASIN

    public static final UnaryFunction ASIN

  Function that returns `Math.asin(a)`.

### ATAN

    public static final UnaryFunction ATAN

  Function that returns `Math.atan(a)`.

### CEIL

    public static final UnaryFunction CEIL

  Function that returns `Math.ceil(a)`.

### COS

    public static final UnaryFunction COS

  Function that returns `Math.cos(a)`.

### EXP

    public static final UnaryFunction EXP

  Function that returns `Math.exp(a)`.

### FLOOR

    public static final UnaryFunction FLOOR

  Function that returns `Math.floor(a)`.

### IDENTITY

    public static final UnaryFunction IDENTITY

  Function that returns its argument.

### INV

    public static final UnaryFunction INV

  Function that returns `1.0 / a`.

### LOGARITHM

    public static final UnaryFunction LOGARITHM

  Function that returns `Math.log(a)`.

### LOG2

    public static final UnaryFunction LOG2

  Function that returns `Math.log(a) / Math.log(2)`.

### NEGATE

    public static final UnaryFunction NEGATE

  Function that returns `-a`.

### RINT

    public static final UnaryFunction RINT

  Function that returns `Math.rint(a)`.

### SIGN

    public static final UnaryFunction SIGN

  Function that returns `a < 0 ? -1 : a > 0 ? 1 : 0`.

### SIN

    public static final UnaryFunction SIN

  Function that returns `Math.sin(a)`.

### SQRT

    public static final UnaryFunction SQRT

  Function that returns `Math.sqrt(a)`.

### SQUARE

    public static final UnaryFunction SQUARE

  Function that returns `a * a`.

### TAN

    public static final UnaryFunction TAN

  Function that returns `Math.tan(a)`.

### ATAN2

    public static final BinaryFunction ATAN2

  Function that returns `Math.atan2(a,b)`.

### COMPARE

    public static final BinaryFunction COMPARE

  Function that returns `a < b ? -1 : a > b ? 1 : 0`.

### DIV

    public static final BinaryFunction DIV

  Function that returns `a / b`.

### EQUALS

    public static final BinaryFunction EQUALS

  Function that returns `a == b ? 1 : 0`.

### GREATER

    public static final BinaryFunction GREATER

  Function that returns `a > b ? 1 : 0`.

### IEEE_REMAINDER

    public static final BinaryFunction IEEE_REMAINDER

  Function that returns `Math.IEEEremainder(a,b)`.

### IS_EQUAL

    public static final org.apache.mahout.math.function.DoubleDoubleProcedure IS_EQUAL

  Function that returns `a == b`.

### IS_LESS

    public static final org.apache.mahout.math.function.DoubleDoubleProcedure IS_LESS

  Function that returns `a < b`.

### IS_GREATER

    public static final org.apache.mahout.math.function.DoubleDoubleProcedure IS_GREATER

  Function that returns `a > b`.

### LESS

    public static final BinaryFunction LESS

  Function that returns `a < b ? 1 : 0`.

### LG

    public static final BinaryFunction LG

  Function that returns `Math.log(a) / Math.log(b)`.

### MAX

    public static final BinaryFunction MAX

  Function that returns `Math.max(a,b)`.

### MIN

    public static final BinaryFunction MIN

  Function that returns `Math.min(a,b)`.

### MINUS

    public static final BinaryFunction MINUS

  Function that returns `a - b`.

### MOD

    public static final BinaryFunction MOD

  Function that returns `a % b`.

### MULT

    public static final BinaryFunction MULT

  Function that returns `a * b`.

### PLUS

    public static final BinaryFunction PLUS

  Function that returns `a + b`.

### PLUS_ABS

    public static final BinaryFunction PLUS_ABS

  Function that returns `Math.abs(a) + Math.abs(b)`.

### POW

    public static final BinaryFunction POW

  Function that returns `Math.pow(a,b)`.

Method Detail

### between

    public static UnaryFunction between(double from,
                                        double to)

  Constructs a function that returns `(from<=a && a<=to) ? 1 : 0`. `a` is a variable, `from` and `to` are fixed.

### bindArg1

    public static UnaryFunction bindArg1(BinaryFunction function,
                                         double c)

  Constructs a unary function from a binary function with the first operand (argument) fixed to the given constant `c`. The second operand is variable (free).

  Parameters:
    `function` - a binary function taking operands in the form `function.apply(c,var)`.
  Returns:
    the unary function `function(c,var)`.

### bindArg2

    public static UnaryFunction bindArg2(BinaryFunction function,
                                         double c)

  Constructs a unary function from a binary function with the second operand (argument) fixed to the given constant `c`. The first operand is variable (free).

  Parameters:
    `function` - a binary function taking operands in the form `function.apply(var,c)`.
  Returns:
    the unary function `function(var,c)`.

### chain

    public static BinaryFunction chain(BinaryFunction f,
                                       UnaryFunction g,
                                       UnaryFunction h)

  Constructs the function `f( g(a), h(b) )`.

  Parameters:
    `f` - a binary function.
    `g` - a unary function.
    `h` - a unary function.
  Returns:
    the binary function `f( g(a), h(b) )`.

### chain

    public static BinaryFunction chain(UnaryFunction g,
                                       BinaryFunction h)

  Constructs the function `g( h(a,b) )`.

  Parameters:
    `g` - a unary function.
    `h` - a binary function.
  Returns:
    the unary function `g( h(a,b) )`.

### chain

    public static UnaryFunction chain(UnaryFunction g,
                                      UnaryFunction h)

  Constructs the function `g( h(a) )`.

  Parameters:
    `g` - a unary function.
    `h` - a unary function.
  Returns:
    the unary function `g( h(a) )`.

### compare

    public static UnaryFunction compare(double b)

  Constructs a function that returns `a < b ? -1 : a > b ? 1 : 0`. `a` is a variable, `b` is fixed.

### constant

    public static UnaryFunction constant(double c)

  Constructs a function that returns the constant `c`.

### div

    public static UnaryFunction div(double b)

  Constructs a function that returns `a / b`. `a` is a variable, `b` is fixed.

### equals

    public static UnaryFunction equals(double b)

  Constructs a function that returns `a == b ? 1 : 0`. `a` is a variable, `b` is fixed.

### greater

    public static UnaryFunction greater(double b)

  Constructs a function that returns `a > b ? 1 : 0`. `a` is a variable, `b` is fixed.

### IEEEremainder

    public static UnaryFunction IEEEremainder(double b)

  Constructs a function that returns `Math.IEEEremainder(a,b)`. `a` is a variable, `b` is fixed.

### isBetween

    public static org.apache.mahout.math.function.DoubleProcedure isBetween(double from,
                                                                            double to)

  Constructs a function that returns `from<=a && a<=to`. `a` is a variable, `from` and `to` are fixed.

### isEqual

    public static org.apache.mahout.math.function.DoubleProcedure isEqual(double b)

  Constructs a function that returns `a == b`. `a` is a variable, `b` is fixed.

### isGreater

    public static org.apache.mahout.math.function.DoubleProcedure isGreater(double b)

  Constructs a function that returns `a > b`. `a` is a variable, `b` is fixed.

### isLess

    public static org.apache.mahout.math.function.DoubleProcedure isLess(double b)

  Constructs a function that returns `a < b`. `a` is a variable, `b` is fixed.

### less

    public static UnaryFunction less(double b)

  Constructs a function that returns `a < b ? 1 : 0`. `a` is a variable, `b` is fixed.

### lg

    public static UnaryFunction lg(double b)

  Constructs a function that returns ``Math.log(a) / Math.log(b)``. `a` is a variable, `b` is fixed.

### max

    public static UnaryFunction max(double b)

  Constructs a function that returns `Math.max(a,b)`. `a` is a variable, `b` is fixed.

### min

    public static UnaryFunction min(double b)

  Constructs a function that returns `Math.min(a,b)`. `a` is a variable, `b` is fixed.

### minus

    public static UnaryFunction minus(double b)

  Constructs a function that returns `a - b`. `a` is a variable, `b` is fixed.

### minusMult

    public static BinaryFunction minusMult(double constant)

  Constructs a function that returns `a - b*constant`. `a` and `b` are variables, `constant` is fixed.

### mod

    public static UnaryFunction mod(double b)

  Constructs a function that returns `a % b`. `a` is a variable, `b` is fixed.

### mult

    public static UnaryFunction mult(double b)

  Constructs a function that returns `a * b`. `a` is a variable, `b` is fixed.

### plus

    public static UnaryFunction plus(double b)

  Constructs a function that returns `a + b`. `a` is a variable, `b` is fixed.

### plusMult

    public static BinaryFunction plusMult(double constant)

  Constructs a function that returns `a + b*constant`. `a` and `b` are variables, `constant` is fixed.

### pow

    public static UnaryFunction pow(double b)

  Constructs a function that returns `Math.pow(a,b)`. `a` is a variable, `b` is fixed.

### random

    public static UnaryFunction random()

  Constructs a function that returns a new uniform random number in the open unit interval `(0.0,1.0)` (excluding 0.0 and 1.0). Currently the engine is `MersenneTwister` and is seeded with the current time.

  Note that any random engine derived from `RandomEngine` and any random distribution derived from `AbstractDistribution` are function objects, because they implement the proper interfaces. Thus, if you are not happy with the default, just pass your favourite random generator to function evaluating methods.

### round

    public static UnaryFunction round(double precision)

  Constructs a function that returns the number rounded to the given precision; `Math.rint(a/precision)*precision`. Examples:

       precision = 0.01 rounds 0.012 --> 0.01, 0.018 --> 0.02
       precision = 10   rounds 123   --> 120 , 127   --> 130

### swapArgs

    public static BinaryFunction swapArgs(BinaryFunction function)

  Constructs a function that returns `function.apply(b,a)`, i.e. applies the function with the first operand as second operand and the second operand as first operand.

  Parameters:
    `function` - a function taking operands in the form `function.apply(a,b)`.
  Returns:
    the binary function `function(b,a)`.

Copyright © 2008-2010 The Apache Software Foundation. All Rights Reserved.