Package com.singularsys.jep.misc.overloadedfunctions

# Class AlternateFunctions

java.lang.Object
com.singularsys.jep.functions.PostfixMathCommand
com.singularsys.jep.misc.overloadedfunctions.AlternateFunctions

All Implemented Interfaces:
  `CallbackEvaluationI`, `JepComponent`, `PostfixMathCommandI`, `Serializable`

public class AlternateFunctions extends PostfixMathCommand implements CallbackEvaluationI, JepComponent
Allows function to be overloaded with multiple candidate functions chosen by the number of arguments.

For example the `atan` function can be overloaded so that it has a one argument and two argument version.

        UnaryFunction uf = new ArcTangent();
        BinaryFunction bf =new ArcTangent2();
        AlternateFunctions af = new AlternateFunctions(uf, bf);
        jep.addFunction("atan",af);
        jep.reinitializeComponents();
        Node node = jep.parse("atan(1)");
        Object res = jep.evaluate(node);
        assertEquals(Math.PI/4,(double) res,1e-9);
        Node node2 = jep.parse("atan(1,2)");
        Object res2 = jep.evaluate(node2);
        assertEquals(Math.atan2(1,2),(double) res2,1e-9);

The above resolution happens at evaluation time. If the `AlternateFunctionGrammerMatcher` is used then resolution happens at parse time.

Evaluation of overloaded functions is done by creating a temporary node with the appropriate function and evaluating this node. This means any type of function can be used, including those that implement `CallbackEvaluationI`.

Since:
  Jep 4.1
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final PostfixMathCommandI[]`
  `functions`
  `protected NodeFactory`
  `nf`
  `protected OperatorTableI`
  `ot`

  ### Fields inherited from class com.singularsys.jep.functions.PostfixMathCommand

  `curNumberOfParameters, description, name, NaN, numberOfParameters`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AlternateFunctions(PostfixMathCommandI... functions)`
  Constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `checkNumberOfParameters(int n)`
  Checks the number of parameters of the function.
  `Object`
  `evaluate(Node node, Evaluator pv)`
  Performs some special evaluation on the node.
  `String`
  `getDescription()`
  Return a description of the function from the properties file.
  `PostfixMathCommandI`
  `getFunctionForNArgs(int n)`
  Returns the function that matches the number of arguments.
  `JepComponent`
  `getLightWeightInstance()`
  Gets a light-weight instance suitable for using in multiple threads.
  `void`
  `init(Jep jep)`
  Initialize the component.

  ### Methods inherited from class com.singularsys.jep.functions.PostfixMathCommand

  `asArray, asBool, asDouble, asInt, asLong, asStrictInt, asString, asType, getDescription, getDescriptionWithType, getName, getNumberOfParameters, run, setCurNumberOfParameters, setDescription, setName, toString, toString`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### functions

    protected final PostfixMathCommandI[] functions

  - ### nf

    protected NodeFactory nf

  - ### ot

    protected OperatorTableI ot

- ## Constructor Details

  - ### AlternateFunctions

    public AlternateFunctions(PostfixMathCommandI... functions)
    Constructor. Any type of function can be used, including those that implement `CallbackEvaluationI`.
    Parameters:
      `functions` - the list of function

- ## Method Details

  - ### checkNumberOfParameters

    public boolean checkNumberOfParameters(int n)
    Description copied from class: `PostfixMathCommand`
    Checks the number of parameters of the function. Functions which set numberOfParameter=-1 should overload this method
    Specified by:
      `checkNumberOfParameters` in interface `PostfixMathCommandI`
    Overrides:
      `checkNumberOfParameters` in class `PostfixMathCommand`
    Parameters:
      `n` - number of parameters function will be called with.
    Returns:
      false if an illegal number of parameters is supplied, true otherwise.

  - ### getFunctionForNArgs

    public PostfixMathCommandI getFunctionForNArgs(int n)
    Returns the function that matches the number of arguments.
    Parameters:
      `n` - the number of arguments
    Returns:
      the function that matches the number of arguments or null if none found.

  - ### init

    public void init(Jep jep)
    Description copied from interface: `JepComponent`
    Initialize the component. This method is called whenever a component is added to Jep. Hence, it allows components to keep track of the other components they may rely on.
    Specified by:
      `init` in interface `JepComponent`
    Parameters:
      `jep` - the current Jep instance

  - ### getLightWeightInstance

    public JepComponent getLightWeightInstance()
    Description copied from interface: `JepComponent`
    Gets a light-weight instance suitable for using in multiple threads.
    Specified by:
      `getLightWeightInstance` in interface `JepComponent`
    Returns:
      either a new instance, null or 'this'.

  - ### evaluate

    public Object evaluate(Node node, Evaluator pv) throws EvaluationException
    Description copied from interface: `CallbackEvaluationI`
    Performs some special evaluation on the node. This method has the responsibility for evaluating the children of the node, and it should generally call

         pv.eval(node.jjtGetChild(i))

    for each child. The SymbolTable is not passed as an argument. This is because it is better practice to get and set variable values by using node.getVar().setValue() rather that through the SymbolTable with requires a hashtable lookup.
    Specified by:
      `evaluate` in interface `CallbackEvaluationI`
    Parameters:
      `node` - The current node
      `pv` - The visitor, can be used evaluate the children
    Returns:
      the value after evaluation. This value will be passed to other functions higher up the node tree. The value can be any type including Double or Vector<Object>
    Throws:
      `EvaluationException` - if the calculation cannot be performed
    See Also:
      - `Evaluator`

  - ### getDescription

    public String getDescription()
    Description copied from class: `PostfixMathCommand`
    Return a description of the function from the properties file. The property name is the class name followed by ".description". The property is found using the `JepMessages` class, which can be configured to add additional properties files. If `PostfixMathCommand.setDescription(String)` has been called, return the description set by that method instead.
    Specified by:
      `getDescription` in interface `PostfixMathCommandI`
    Overrides:
      `getDescription` in class `PostfixMathCommand`
    Returns:
      the description of the function