Package com.singularsys.jep.functions

# Interface ZeroLengthBehaviourI

All Superinterfaces:
  `Serializable`

All Known Subinterfaces:
  `ZeroLengthBehaviourI.DefaultZeroLengthBehaviourI`

All Known Implementing Classes:
  `ArrayFunctionBase`, `Average`, `BigDecVSum`, `ElementOf`, `Get`, `MinMax`, `VSum`, `ZeroLengthBehaviourI.ZeroLengthHelper`

public interface ZeroLengthBehaviourI extends Serializable
Interface for functions which can be configured to respond to zero length array arguments with either an exception, NaN or a value.

A standard template for implementing classes is

    public class MyFunction extends UnaryFunction implements ZeroLengthBehaviourI {
        ZeroLengthErrorBehaviour zeroLengthErrorBehaviour = ZeroLengthErrorBehaviour.EXCEPTION;
        Object zeroLengthValue = null;

        @Override
        public ZeroLengthErrorBehaviour getZeroLengthErrorBehaviour() {
            return zeroLengthErrorBehaviour;
        }
        @Override
        public void setZeroLengthErrorBehaviour(
            ZeroLengthErrorBehaviour zeroLengthErrorBehaviour) {
            this.zeroLengthErrorBehaviour = zeroLengthErrorBehaviour;
         }
         @Override
         public Object getZeroLengthValue() {
             return zeroLengthValue;
         }
         @Override
         public void setZeroLengthValue(Object zeroLengthValue) {
             this.zeroLengthValue = zeroLengthValue;
         }

         @Override
         public Object eval(Object arg) throws EvaluationException {
             boolean empty;
             Object res;
             // code to calculate result, sets the empty flag and the res value
             if(empty) {
                 return zeroLengthResultOrException(getName());
             }
             return res;
         }
     }

Alternatively if you use an Optional:

    @Override
    public Object eval(Object arg) throws EvaluationException {
        Optional<Object> res = doCalc(arg);
        return getValueOrException(getName(), res);
    }

Which will return the value if present, or if not present, either return the zero length values or throws an exception

The `ZeroLengthBehaviourI.DefaultZeroLengthBehaviourI` simplifies the implementation of implementing classes by delegating the zero length behaviour to a `ZeroLengthBehaviourI.ZeroLengthHelper` class.

    public class MyFunction extends UnaryFunction implements JepComponent, DefaultZeroLengthBehaviourI {
        ZeroLengthHelper zeroLengthHelper = new ZeroLengthHelper();
        @Override
        public ZeroLengthBehaviourI getZeroLengthHelper() {
            return zeroLengthHelper;
        }

         @Override
         public Object eval(Object arg) throws EvaluationException {
             Optional<Object> res = doCalc(arg);
             return getValueOrException(getName(), res);
         }

         @Override
         public JepComponent getLightWeightInstance() {
             var res = new MyFunction();
             res.zeroLengthHelper.setZeroLengthBehaviourAndValue(zeroLengthHelper);
             return res;
         }
     }

Since:
  Jep 4.1

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `ZeroLengthBehaviourI.DefaultZeroLengthBehaviourI`
  Interface for classes which implement `ZeroLengthBehaviourI` by delegating to a helper class.
  `static enum`
  `ZeroLengthBehaviourI.ZeroLengthErrorBehaviour`
  How to respond to a zero length array as argument
  `static class`
  `ZeroLengthBehaviourI.ZeroLengthHelper`
  Helper class which implements the zero length behaviour.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default String`
  `getErrorMessage(String functionName)`
  Gets the zero length error message.
  `default Object`
  `getValueOrException(String functionName, Optional<Object> value)`
  Either return the optional's value or, if not present, either return the zero length values or throws an exception depending on the zero length error behaviour flag.
  `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`
  `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.
  `default Object`
  `zeroLengthResultOrException(String functionName)`
  Either return the value for zero length array or throws an exception depending on the zero length error behaviour flag.

- ## Method Details

  - ### getZeroLengthErrorBehaviour

    ZeroLengthBehaviourI.ZeroLengthErrorBehaviour getZeroLengthErrorBehaviour()
    Gets how to respond to arguments with zero length arrays.
    Returns:
      either EXCEPTION, NAN or VALUE

  - ### setZeroLengthErrorBehaviour

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

  - ### getZeroLengthValue

    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.
    Returns:
      the value, null by default

  - ### setZeroLengthValue

    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. The `setZeroLengthErrorBehaviour(ZeroLengthErrorBehaviour)` method should be used to set the zero length error behaviour to VALUE.
    Parameters:
      `zeroLengthValue` - the value to return when a zero length array is passed

  - ### zeroLengthResultOrException

    default Object zeroLengthResultOrException(String functionName) throws EvaluationException
    Either return the value for zero length array or throws an exception depending on the zero length error behaviour flag.
    Parameters:
      `functionName` -
    Returns:
      either NaN, the value set by setZeroLengthValue
    Throws:
      `EvaluationException` - if the zero length error behaviour is set to EXCEPTION

  - ### getErrorMessage

    default String getErrorMessage(String functionName)
    Gets the zero length error message. The default implementation format a string using the `functions.AtLestOneArgumentIsRequired` property.
    Parameters:
      `functionName` - name of the function passed into `zeroLengthResultOrException(String)`
    Returns:
      the error message.

  - ### getValueOrException

    default Object getValueOrException(String functionName, Optional<Object> value) throws EvaluationException
    Either return the optional's value or, if not present, either return the zero length values or throws an exception depending on the zero length error behaviour flag.
    Parameters:
      `functionName` - name of function used in exception message if thrown
      `value` - the value to return if present
    Returns:
      the optional value, or default value
    Throws:
      `EvaluationException` - if value is not present and the zero length error behaviour is set to EXCEPTION