Package com.singularsys.jep.functions

# Class ArrayFunctionBase

java.lang.Object
com.singularsys.jep.functions.PostfixMathCommand
com.singularsys.jep.functions.ArrayFunctionBase

All Implemented Interfaces:
  `ZeroLengthBehaviourI`, `PostfixMathCommandI`, `Serializable`

Direct Known Subclasses:
  `Average`, `BigDecVSum`, `ElementOf`, `MinMax`, `VSum`

public abstract class ArrayFunctionBase extends PostfixMathCommand implements ZeroLengthBehaviourI
Base class for functions that operate on arrays such as Average, MinMax, and VSum. The shared functionality such as array flattening is implemented here. In the run() method, before calling calc(), Vectors and nested Vectors are flattened so `1,[2,[3, 4]]` becomes `[1, 2, 3, 4]` which is passed in to the calc method as a List<Object>.

Since:
  3.4.0
See Also:
  - Serialized Form

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface com.singularsys.jep.functions.ZeroLengthBehaviourI

  `ZeroLengthBehaviourI.DefaultZeroLengthBehaviourI, ZeroLengthBehaviourI.ZeroLengthErrorBehaviour, ZeroLengthBehaviourI.ZeroLengthHelper`

- ## Field Summary

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

  `curNumberOfParameters, description, name, NaN, numberOfParameters`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `ArrayFunctionBase()`
  Default the number of parameters to any number of params (-1).
  `protected`
  `ArrayFunctionBase(ZeroLengthBehaviourI.ZeroLengthErrorBehaviour zeroLengthErrorBehaviour)`
  Constructor with a specified zero length error behaviour.
  `protected`
  `ArrayFunctionBase(Object zeroLengthValue)`
  Constructor with a specified value to return for zero length arrays.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `addToArray(List<Object> l, Object val)`
  Adds a value `val` to the array `l`.
  `protected abstract Object`
  `calc(List<Object> l)`
  Abstract method for performing the array calculation.
  `boolean`
  `checkNumberOfParameters(int n)`
  Must have one or more parameter
  `ZeroLengthBehaviourI.ZeroLengthErrorBehaviour`
  `getZeroLengthErrorBehaviour()`
  Gets how to respond to arguments with zero length arrays.
  `Object`
  `getZeroLengthValue()`
  Gets the value to be returned when a zero length array is passed as an argument and the zero length error behaviour is set to VALUE.
  `void`
  `run(Stack<Object> stack)`
  Calls the calc method after concatenating all elements into list.
  `void`
  `setZeroLengthErrorBehaviour(ZeroLengthBehaviourI.ZeroLengthErrorBehaviour zeroLengthErrorBehaviour)`
  Sets how to respond to arguments with zero length arrays.
  `void`
  `setZeroLengthValue(Object zeroLengthValue)`
  Sets the value to be returned when a zero length array is passed and the zero length error behaviour is set to VALUE.
  `protected void`
  `throwAtLeastOneExcep()`
  Throws an exception indicating that at least one argument is required.

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

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

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

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

  ### Methods inherited from interface com.singularsys.jep.functions.ZeroLengthBehaviourI

  `getErrorMessage, getValueOrException, zeroLengthResultOrException`

- ## Constructor Details

  - ### ArrayFunctionBase

    public ArrayFunctionBase()
    Default the number of parameters to any number of params (-1).

  - ### ArrayFunctionBase

    protected ArrayFunctionBase(ZeroLengthBehaviourI.ZeroLengthErrorBehaviour zeroLengthErrorBehaviour)
    Constructor with a specified zero length error behaviour.
    Parameters:
      `zeroLengthErrorBehaviour` -

  - ### ArrayFunctionBase

    protected ArrayFunctionBase(Object zeroLengthValue)
    Constructor with a specified value to return for zero length arrays. Sets the zero length error behaviour to VALUE.
    Parameters:
      `zeroLengthValue` - the value to return when a zero length array is passed

- ## Method Details

  - ### checkNumberOfParameters

    public boolean checkNumberOfParameters(int n)
    Must have one or more parameter
    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.

  - ### run

    public void run(Stack<Object> stack) throws EvaluationException
    Calls the calc method after concatenating all elements into list. Subclasses are responsible for implementing the calc method and handling the zero length array case.
    Specified by:
      `run` in interface `PostfixMathCommandI`
    Overrides:
      `run` in class `PostfixMathCommand`
    Parameters:
      `stack` - arguments for function
    Throws:
      `EvaluationException` - if function cannot be evaluated

  - ### addToArray

    protected void addToArray(List<Object> l, Object val)
    Adds a value `val` to the array `l`. This method flattens Vectors and nested Vectors so `1,[2,[3, 4]]` becomes `[1, 2, 3, 4]`.
    Parameters:
      `l` - The list to which to add `a`.
      `val` - The value to be added (can be a Vector).

  - ### calc

    protected abstract Object calc(List<Object> l) throws EvaluationException
    Abstract method for performing the array calculation.
    Parameters:
      `l` - The list to operate on. Note this is in reverse order of the arguments of the function.
    Returns:
      The result of the calculation.
    Throws:
      `EvaluationException` - if the calculation cannot be performed

  - ### throwAtLeastOneExcep

    protected void throwAtLeastOneExcep() throws EvaluationException
    Throws an exception indicating that at least one argument is required.
    Throws:
      `EvaluationException`

  - ### getZeroLengthErrorBehaviour

    public ZeroLengthBehaviourI.ZeroLengthErrorBehaviour getZeroLengthErrorBehaviour()
    Description copied from interface: `ZeroLengthBehaviourI`
    Gets how to respond to arguments with zero length arrays.
    Specified by:
      `getZeroLengthErrorBehaviour` in interface `ZeroLengthBehaviourI`
    Returns:
      either EXCEPTION, NAN or VALUE

  - ### setZeroLengthErrorBehaviour

    public void setZeroLengthErrorBehaviour(ZeroLengthBehaviourI.ZeroLengthErrorBehaviour zeroLengthErrorBehaviour)
    Description copied from interface: `ZeroLengthBehaviourI`
    Sets how to respond to arguments with zero length arrays. Either an Exception is thrown or NaN is returned.
    Specified by:
      `setZeroLengthErrorBehaviour` in interface `ZeroLengthBehaviourI`
    Parameters:
      `zeroLengthErrorBehaviour` - either EXCEPTION, NAN or VALUE

  - ### getZeroLengthValue

    public Object getZeroLengthValue()
    Description copied from interface: `ZeroLengthBehaviourI`
    Gets the value to be returned when a zero length array is passed as an argument and the zero length error behaviour is set to VALUE.
    Specified by:
      `getZeroLengthValue` in interface `ZeroLengthBehaviourI`
    Returns:
      the value, null by default

  - ### setZeroLengthValue

    public void setZeroLengthValue(Object zeroLengthValue)
    Description copied from interface: `ZeroLengthBehaviourI`
    Sets the value to be returned when a zero length array is passed and the zero length error behaviour is set to VALUE. The `ZeroLengthBehaviourI.setZeroLengthErrorBehaviour(ZeroLengthErrorBehaviour)` method should be used to set the zero length error behaviour to VALUE.
    Specified by:
      `setZeroLengthValue` in interface `ZeroLengthBehaviourI`
    Parameters:
      `zeroLengthValue` - the value to return when a zero length array is passed