com.eteks.parser
Interface Function

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

CompiledFunction

public interface Function

extends java.io.Serializable

Interface of functions defined by user. These functions may be of one the two following types :

• Functions parsed the compileFunction () method of a instance of FunctionParser : This method returns an instance of CompiledFunction that implements the Function interface.
• Any instance of a class that implements the Function interface : This enables to create some functions with a variable number of parameters (like the function AND () of Jeks spreadsheet), that may run faster than functions of class CompiledFunction and that may use parameters of special type (like arrays of values for the SUM () method of Jeks spreadsheet).

In both cases, a function must be returned by the getFunction () method of the syntax of a parser, if you want to call it in the definition of an other function or an expression.
Note that although this interface requires a JDK 1.1 library to compile because it extends the Serializable, com.eteks.parser classes can run on a JVM 1.0 (as long as you don't process any serialization of course).

Since:

Jeks 1.0

Version:

1.0

Author:

Emmanuel Puybaret

See Also:

FunctionParser, Syntax

Method Summary

java.lang.Object	computeFunction(Interpreter interpreter, java.lang.Object[] parametersValue) Returns the result of this function computed with the value of its parameters parametersValue.
java.lang.String	getName() Returns the name of this function.
boolean	isValidParameterCount(int count) Returns true if the number of parameters count required at runtime by this function is valid.

Method Detail

getName

public java.lang.String getName()

Returns the name of this function.

Returns:

The public name that may be supported by a syntax to call this function in expressions parsed with instances of FunctionParser or ExpressionParser.

See Also:

Syntax.getFunction(java.lang.String)

isValidParameterCount

public boolean isValidParameterCount(int count)

Returns true if the number of parameters count required at runtime by this function is valid. This method is called by the parser to check if the call to a function has the good parameter count.

Parameters:

count - Number of parameters (may be equal to 0).

computeFunction

public java.lang.Object computeFunction(Interpreter interpreter,
                                        java.lang.Object[] parametersValue)

Returns the result of this function computed with the value of its parameters parametersValue. The type of the parameters and of the returned value depends on the interpreter used at runtime. This allows to apply computations on a wide range of parameter types, from number types (with the classes Long, Double,...) to strings (with the String class) and also booleans (Boolean). Other classes like java.math.BigDecimal or javax.vecmath.GVector and javax.vecmath.GMatrix can be also used.
Depending on some implementations of this interface, this method may throw a runtime exception (generally an instance of IllegalArgumentException) if its parameters have a wrong type to perform the resquested function.
If this method is implemented in a user function class, it may compute basic operations with the methods of the current interpreter or with Java code. For example, an AVERAGE () function that computes the average value of a variable number of parameters can be implemented in either following ways :

 class FunctionAverage implements Function
 {
   public String getName ()
   {
     return "AVERAGE";
   }

   public boolean isValidParameterCount (int parameterCount)
   {
     return parameterCount > 0; // At least one parameter
   }

   public Object computeFunction (Interpreter interpreter, Object [] parametersValue)
   {
     Object sum = parametersValue [0];
     for (int i = 1; i < parametersValue.length; i++)
       // Add the parameters value with the binary operator ADD of the interpreter
       sum = interpreter.getBinaryOperatorValue (Syntax.OPERATOR_ADD,
                                                 sum, parametersValue [i]);

     // Get the value of the literal parametersValue.length in the type used by interpreter
     Object parameterCount = interpreter.getLiteralValue (new Integer (parametersValue.length));
     // Divide the sum by parameterCount with the binary operator DIVIDE  of the interpreter
     return interpreter.getBinaryOperatorValue (Syntax.OPERATOR_DIVIDE,
                                                sum, parameterCount);
   }
 }

or

 class FunctionAverage implements Function
 {
   public String getName ()
   {
     return "AVERAGE";
   }

   public boolean isValidParameterCount (int parameterCount)
   {
     return parameterCount > 0; // At least one parameter
   }

   public Object computeFunction (Interpreter interpreter, Object [] parametersValue)
   {
     double sum = 0;
     for (int i = 0; i < parametersValue.length; i++)
       if (parametersValue [i] instanceof Number)
         // Add all numbers parametersValue [i]
         sum += ((Number)parametersValue [i]).doubleValue ();
       else
         throw new IllegalArgumentException (String.valueOf (parametersValue [i]) + " not a number");

     return new Double (sum / parametersValue.length);
   }
 }

Note that the second way is faster but is less generic because it supports only Number parameters. According to the implementation of interpreter, the first way may accept and return different type of values.

Parameters:

interpreter - the runtime interpreter to perform the operations of Syntax.

parametersValue - the value of parameters (already evaluated if they are expressions).

Returns:

the result of the operation of this function.

See Also:

Syntax, Interpreter