Package com.singularsys.jep.misc.overloadedfunctions

# Class OverloadedFunctionByStructure

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

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

public class OverloadedFunctionByStructure extends PostfixMathCommand implements CallbackEvaluationI, JepComponent
Allows function to be overloaded with two candidate functions and a predicate that tests the structure of the parse tree to see which function should be applied.

For example in the extensions package the dot operator can be overloaded with a custom function ChainingOpPfmc that allows a method chaining syntax so a syntax like `[1..10] . map(x->x^2)`. This is used when the second argument is a ChainedFunctionI. Otherwise the regular dot product function is used.

      Operator dot_op = jep.getOperatorTable().getDot();
      dot_op.setPFMC(new OverloadedFunctionByStructure(
              new ChainingOpPfmc(),
              new Dot(),
              n -> n.jjtGetChild(1).getPFMC() instanceof ChainedFunctionI));
      jep.reinitializeComponents();

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 Predicate<Node>`
  `argTest`
  `protected final PostfixMathCommandI`
  `function1`
  `protected final PostfixMathCommandI`
  `function2`
  `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
  `OverloadedFunctionByStructure(PostfixMathCommandI function1, PostfixMathCommandI function2, Predicate<Node> argTest)`
  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`
  `getFunction1()`
  `PostfixMathCommandI`
  `getFunction2()`
  `PostfixMathCommandI`
  `getFunctionFor(Node node)`
  Get the actual function that will be used for a given node.
  `JepComponent`
  `getLightWeightInstance()`
  Gets a light-weight instance suitable for using in multiple threads.
  `int`
  `getNumberOfParameters()`
  Calculates the possible number of parameters.
  `Predicate<Node>`
  `getPredicate()`
  `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, 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

  - ### function1

    protected final PostfixMathCommandI function1

  - ### function2

    protected final PostfixMathCommandI function2

  - ### argTest

    protected final Predicate<Node> argTest

  - ### nf

    protected NodeFactory nf

  - ### ot

    protected OperatorTableI ot

- ## Constructor Details

  - ### OverloadedFunctionByStructure

    public OverloadedFunctionByStructure(PostfixMathCommandI function1, PostfixMathCommandI function2, Predicate<Node> argTest)
    Constructor. Any type of function can be used, including those that implement `CallbackEvaluationI`.
    Parameters:
      `function1` - the first function
      `function2` - the second function
      `argTest` - a predicate that tests the structure of the parse tree, the first function is used if this returns true.

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

  - ### getNumberOfParameters

    public int getNumberOfParameters()
    Calculates the possible number of parameters. If both functions have the same number of parameters then return than, otherwise return -1.
    Specified by:
      `getNumberOfParameters` in interface `PostfixMathCommandI`
    Overrides:
      `getNumberOfParameters` in class `PostfixMathCommand`
    Returns:
      the possible number of parameters

  - ### 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`

  - ### getFunctionFor

    public PostfixMathCommandI getFunctionFor(Node node)
    Get the actual function that will be used for a given node.
    Parameters:
      `node` - the node to test
    Returns:
      either function1 or function2 depending on the test

  - ### 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'.

  - ### getFunction1

    public PostfixMathCommandI getFunction1()

  - ### getFunction2

    public PostfixMathCommandI getFunction2()

  - ### getPredicate

    public Predicate<Node> getPredicate()

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