Functions
cern.jet.math

## Class Functions

• ```public class Functions
extends 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 `DoubleFunction`, binary functions of type `DoubleDoubleFunction`. 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(DoubleDoubleFunction,double)` and `bindArg2(DoubleDoubleFunction,double)`. The order of arguments can be swapped so that the first argument becomes the second and vice-versa. See method `swapArgs(DoubleDoubleFunction)`. 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(DoubleFunction,DoubleFunction)`:

• Functions.chain(g,h);
Assume further we have a binary function f. The binary function g(f(a,b)) can be generated via `chain(DoubleFunction,DoubleDoubleFunction)`:
• Functions.chain(g,f);
The binary function f(g(a),h(b)) can be generated via `chain(DoubleDoubleFunction,DoubleFunction,DoubleFunction)`:
• 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 DoubleDoubleFunction() {
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); System.out.println(v); Functions F = Functions.functions; DoubleDoubleFunction f = F.chain(F.plus,F.sin,F.chain(F.square,F.cos)); System.out.println(f.apply(a,b)); DoubleDoubleFunction g = new DoubleDoubleFunction() {    public double apply(double a, double b) { return Math.sin(a) + Math.pow(Math.cos(b),2); } }; System.out.println(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

Fields
Modifier and Type Field and Description
`static DoubleFunction` `abs`
Function that returns Math.abs(a).
`static DoubleFunction` `acos`
Function that returns Math.acos(a).
`static DoubleFunction` `asin`
Function that returns Math.asin(a).
`static DoubleFunction` `atan`
Function that returns Math.atan(a).
`static DoubleDoubleFunction` `atan2`
Function that returns Math.atan2(a,b).
`static DoubleFunction` `ceil`
Function that returns Math.ceil(a).
`static DoubleDoubleFunction` `compare`
Function that returns a < b ? -1 : a > b ? 1 : 0.
`static DoubleFunction` `cos`
Function that returns Math.cos(a).
`static DoubleDoubleFunction` `div`
Function that returns a / b.
`static DoubleDoubleFunction` `equals`
Function that returns a == b ? 1 : 0.
`static DoubleFunction` `exp`
Function that returns Math.exp(a).
`static DoubleFunction` `floor`
Function that returns Math.floor(a).
`static Functions` `functions`
Little trick to allow for "aliasing", that is, renaming this class.
`static DoubleDoubleFunction` `greater`
Function that returns a > b ? 1 : 0.
`static DoubleFunction` `identity`
Function that returns its argument.
`static DoubleDoubleFunction` `IEEEremainder`
Function that returns Math.IEEEremainder(a,b).
`static DoubleFunction` `inv`
Function that returns 1.0 / a.
`static DoubleDoubleProcedure` `isEqual`
Function that returns a == b.
`static DoubleDoubleProcedure` `isGreater`
Function that returns a > b.
`static DoubleDoubleProcedure` `isLess`
Function that returns a < b.
`static DoubleDoubleFunction` `less`
Function that returns a < b ? 1 : 0.
`static DoubleDoubleFunction` `lg`
Function that returns Math.log(a) / Math.log(b).
`static DoubleFunction` `log`
Function that returns Math.log(a).
`static DoubleFunction` `log2`
Function that returns Math.log(a) / Math.log(2).
`static DoubleDoubleFunction` `max`
Function that returns Math.max(a,b).
`static DoubleDoubleFunction` `min`
Function that returns Math.min(a,b).
`static DoubleDoubleFunction` `minus`
Function that returns a - b.
`static DoubleDoubleFunction` `mod`
Function that returns a % b.
`static DoubleDoubleFunction` `mult`
Function that returns a * b.
`static DoubleFunction` `neg`
Function that returns -a.
`static DoubleDoubleFunction` `plus`
Function that returns a + b.
`static DoubleDoubleFunction` `plusAbs`
Function that returns Math.abs(a) + Math.abs(b).
`static DoubleDoubleFunction` `pow`
Function that returns Math.pow(a,b).
`static DoubleFunction` `rint`
Function that returns Math.rint(a).
`static DoubleFunction` `sign`
Function that returns a < 0 ? -1 : a > 0 ? 1 : 0.
`static DoubleFunction` `sin`
Function that returns Math.sin(a).
`static DoubleFunction` `sqrt`
Function that returns Math.sqrt(a).
`static DoubleFunction` `square`
Function that returns a * a.
`static DoubleFunction` `tan`
Function that returns Math.tan(a).
• ### Method Summary

Methods
Modifier and Type Method and Description
`static DoubleFunction` ```between(double from, double to)```
Constructs a function that returns (from<=a && a<=to) ? 1 : 0.
`static DoubleFunction` ```bindArg1(DoubleDoubleFunction function, double c)```
Constructs a unary function from a binary function with the first operand (argument) fixed to the given constant c.
`static DoubleFunction` ```bindArg2(DoubleDoubleFunction function, double c)```
Constructs a unary function from a binary function with the second operand (argument) fixed to the given constant c.
`static DoubleDoubleFunction` ```chain(DoubleDoubleFunction f, DoubleFunction g, DoubleFunction h)```
Constructs the function f( g(a), h(b) ).
`static DoubleDoubleFunction` ```chain(DoubleFunction g, DoubleDoubleFunction h)```
Constructs the function g( h(a,b) ).
`static DoubleFunction` ```chain(DoubleFunction g, DoubleFunction h)```
Constructs the function g( h(a) ).
`static DoubleFunction` `compare(double b)`
Constructs a function that returns a < b ? -1 : a > b ? 1 : 0.
`static DoubleFunction` `constant(double c)`
Constructs a function that returns the constant c.
`static void` `demo1()`
Demonstrates usage of this class.
`static void` `demo2(int size)`
Benchmarks and demonstrates usage of trivial and complex functions.
`static DoubleFunction` `div(double b)`
Constructs a function that returns a / b.
`static DoubleFunction` `equals(double b)`
Constructs a function that returns a == b ? 1 : 0.
`static DoubleFunction` `greater(double b)`
Constructs a function that returns a > b ? 1 : 0.
`static DoubleFunction` `IEEEremainder(double b)`
Constructs a function that returns Math.IEEEremainder(a,b).
`static DoubleProcedure` ```isBetween(double from, double to)```
Constructs a function that returns from<=a && a<=to.
`static DoubleProcedure` `isEqual(double b)`
Constructs a function that returns a == b.
`static DoubleProcedure` `isGreater(double b)`
Constructs a function that returns a > b.
`static DoubleProcedure` `isLess(double b)`
Constructs a function that returns a < b.
`static DoubleFunction` `less(double b)`
Constructs a function that returns a < b ? 1 : 0.
`static DoubleFunction` `lg(double b)`
Constructs a function that returns Math.log(a) / Math.log(b).
`static DoubleFunction` `max(double b)`
Constructs a function that returns Math.max(a,b).
`static DoubleFunction` `min(double b)`
Constructs a function that returns Math.min(a,b).
`static DoubleFunction` `minus(double b)`
Constructs a function that returns a - b.
`static DoubleDoubleFunction` `minusMult(double constant)`
Constructs a function that returns a - b*constant.
`static DoubleFunction` `mod(double b)`
Constructs a function that returns a % b.
`static DoubleFunction` `mult(double b)`
Constructs a function that returns a * b.
`static DoubleFunction` `plus(double b)`
Constructs a function that returns a + b.
`static DoubleDoubleFunction` `plusMult(double constant)`
Constructs a function that returns a + b*constant.
`static DoubleFunction` `pow(double b)`
Constructs a function that returns Math.pow(a,b).
`static DoubleFunction` `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 DoubleFunction` `round(double precision)`
Constructs a function that returns the number rounded to the given precision; Math.rint(a/precision)*precision.
`static DoubleDoubleFunction` `swapArgs(DoubleDoubleFunction function)`
Constructs a function that returns function.apply(b,a), i.e.
• ### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
• ### Field Detail

• #### functions

`public static final Functions functions`
Little trick to allow for "aliasing", that is, renaming this class. Writing code like

Functions.chain(Functions.plus,Functions.sin,Functions.chain(Functions.square,Functions.cos));

is a bit awkward, to say the least. Using the aliasing you can instead write

Functions F = Functions.functions;
F.chain(F.plus,F.sin,F.chain(F.square,F.cos));

• #### abs

`public static final DoubleFunction abs`
Function that returns Math.abs(a).
• #### acos

`public static final DoubleFunction acos`
Function that returns Math.acos(a).
• #### asin

`public static final DoubleFunction asin`
Function that returns Math.asin(a).
• #### atan

`public static final DoubleFunction atan`
Function that returns Math.atan(a).
• #### ceil

`public static final DoubleFunction ceil`
Function that returns Math.ceil(a).
• #### cos

`public static final DoubleFunction cos`
Function that returns Math.cos(a).
• #### exp

`public static final DoubleFunction exp`
Function that returns Math.exp(a).
• #### floor

`public static final DoubleFunction floor`
Function that returns Math.floor(a).
• #### identity

`public static final DoubleFunction identity`
Function that returns its argument.
• #### inv

`public static final DoubleFunction inv`
Function that returns 1.0 / a.
• #### log

`public static final DoubleFunction log`
Function that returns Math.log(a).
• #### log2

`public static final DoubleFunction log2`
Function that returns Math.log(a) / Math.log(2).
• #### neg

`public static final DoubleFunction neg`
Function that returns -a.
• #### rint

`public static final DoubleFunction rint`
Function that returns Math.rint(a).
• #### sign

`public static final DoubleFunction sign`
Function that returns a < 0 ? -1 : a > 0 ? 1 : 0.
• #### sin

`public static final DoubleFunction sin`
Function that returns Math.sin(a).
• #### sqrt

`public static final DoubleFunction sqrt`
Function that returns Math.sqrt(a).
• #### square

`public static final DoubleFunction square`
Function that returns a * a.
• #### tan

`public static final DoubleFunction tan`
Function that returns Math.tan(a).
• #### atan2

`public static final DoubleDoubleFunction atan2`
Function that returns Math.atan2(a,b).
• #### compare

`public static final DoubleDoubleFunction compare`
Function that returns a < b ? -1 : a > b ? 1 : 0.
• #### div

`public static final DoubleDoubleFunction div`
Function that returns a / b.
• #### equals

`public static final DoubleDoubleFunction equals`
Function that returns a == b ? 1 : 0.
• #### greater

`public static final DoubleDoubleFunction greater`
Function that returns a > b ? 1 : 0.
• #### IEEEremainder

`public static final DoubleDoubleFunction IEEEremainder`
Function that returns Math.IEEEremainder(a,b).
• #### isEqual

`public static final DoubleDoubleProcedure isEqual`
Function that returns a == b.
• #### isLess

`public static final DoubleDoubleProcedure isLess`
Function that returns a < b.
• #### isGreater

`public static final DoubleDoubleProcedure isGreater`
Function that returns a > b.
• #### less

`public static final DoubleDoubleFunction less`
Function that returns a < b ? 1 : 0.
• #### lg

`public static final DoubleDoubleFunction lg`
Function that returns Math.log(a) / Math.log(b).
• #### max

`public static final DoubleDoubleFunction max`
Function that returns Math.max(a,b).
• #### min

`public static final DoubleDoubleFunction min`
Function that returns Math.min(a,b).
• #### minus

`public static final DoubleDoubleFunction minus`
Function that returns a - b.
• #### mod

`public static final DoubleDoubleFunction mod`
Function that returns a % b.
• #### mult

`public static final DoubleDoubleFunction mult`
Function that returns a * b.
• #### plus

`public static final DoubleDoubleFunction plus`
Function that returns a + b.
• #### plusAbs

`public static final DoubleDoubleFunction plusAbs`
Function that returns Math.abs(a) + Math.abs(b).
• #### pow

`public static final DoubleDoubleFunction pow`
Function that returns Math.pow(a,b).
• ### Method Detail

• #### between

```public static DoubleFunction 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 DoubleFunction bindArg1(DoubleDoubleFunction 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 DoubleFunction bindArg2(DoubleDoubleFunction 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 DoubleDoubleFunction chain(DoubleDoubleFunction f,
DoubleFunction g,
DoubleFunction 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 DoubleDoubleFunction chain(DoubleFunction g,
DoubleDoubleFunction 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 DoubleFunction chain(DoubleFunction g,
DoubleFunction 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 DoubleFunction 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 DoubleFunction constant(double c)`
Constructs a function that returns the constant c.
• #### demo1

`public static void demo1()`
Demonstrates usage of this class.
• #### demo2

`public static void demo2(int size)`
Benchmarks and demonstrates usage of trivial and complex functions.
• #### div

`public static DoubleFunction div(double b)`
Constructs a function that returns a / b. a is a variable, b is fixed.
• #### equals

`public static DoubleFunction equals(double b)`
Constructs a function that returns a == b ? 1 : 0. a is a variable, b is fixed.
• #### greater

`public static DoubleFunction greater(double b)`
Constructs a function that returns a > b ? 1 : 0. a is a variable, b is fixed.
• #### IEEEremainder

`public static DoubleFunction IEEEremainder(double b)`
Constructs a function that returns Math.IEEEremainder(a,b). a is a variable, b is fixed.
• #### isBetween

```public static 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 DoubleProcedure isEqual(double b)`
Constructs a function that returns a == b. a is a variable, b is fixed.
• #### isGreater

`public static DoubleProcedure isGreater(double b)`
Constructs a function that returns a > b. a is a variable, b is fixed.
• #### isLess

`public static DoubleProcedure isLess(double b)`
Constructs a function that returns a < b. a is a variable, b is fixed.
• #### less

`public static DoubleFunction less(double b)`
Constructs a function that returns a < b ? 1 : 0. a is a variable, b is fixed.
• #### lg

`public static DoubleFunction lg(double b)`
Constructs a function that returns Math.log(a) / Math.log(b). a is a variable, b is fixed.
• #### max

`public static DoubleFunction max(double b)`
Constructs a function that returns Math.max(a,b). a is a variable, b is fixed.
• #### min

`public static DoubleFunction min(double b)`
Constructs a function that returns Math.min(a,b). a is a variable, b is fixed.
• #### minus

`public static DoubleFunction minus(double b)`
Constructs a function that returns a - b. a is a variable, b is fixed.
• #### minusMult

`public static DoubleDoubleFunction minusMult(double constant)`
Constructs a function that returns a - b*constant. a and b are variables, constant is fixed.
• #### mod

`public static DoubleFunction mod(double b)`
Constructs a function that returns a % b. a is a variable, b is fixed.
• #### mult

`public static DoubleFunction mult(double b)`
Constructs a function that returns a * b. a is a variable, b is fixed.
• #### plus

`public static DoubleFunction plus(double b)`
Constructs a function that returns a + b. a is a variable, b is fixed.
• #### plusMult

`public static DoubleDoubleFunction plusMult(double constant)`
Constructs a function that returns a + b*constant. a and b are variables, constant is fixed.
• #### pow

`public static DoubleFunction pow(double b)`
Constructs a function that returns Math.pow(a,b). a is a variable, b is fixed.
• #### random

`public static DoubleFunction 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 DoubleFunction 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 DoubleDoubleFunction swapArgs(DoubleDoubleFunction 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).