org.apache.commons.jexl3

## Class JexlArithmetic

- java.lang.Object
- - org.apache.commons.jexl3.JexlArithmetic

-     public class JexlArithmetic
      extends Object

  Perform arithmetic, implements JexlOperator methods.

  This is the class to derive to implement new operator behaviors.

  The 5 base arithmetic operators (+, - , *, /, %) follow the same evaluation rules regarding their arguments.

  1. If both are null, result is 0
  2. If either is a BigDecimal, coerce both to BigDecimal and perform operation
  3. If either is a floating point number, coerce both to Double and perform operation
  4. Else treat as BigInteger, perform operation and attempt to narrow result:
     1. if both arguments can be narrowed to Integer, narrow result to Integer
     2. if both arguments can be narrowed to Long, narrow result to Long
     3. Else return result as BigInteger
  Note that the only exception thrown by JexlArithmetic is and must be ArithmeticException.
  Since:
    2.0
  See Also:
    `JexlOperator`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `JexlArithmetic.ArrayBuilder` Helper interface used when creating an array literal.
    `static interface` | `JexlArithmetic.MapBuilder` Helper interface used when creating a map literal.
    `static class` | `JexlArithmetic.NullOperand` Marker class for null operand exceptions.
    `static interface` | `JexlArithmetic.SetBuilder` Helper interface used when creating a set literal.
    `static interface` | `JexlArithmetic.Uberspect` The interface that uberspects JexlArithmetic classes.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Pattern` | `FLOAT_PATTERN` The float regular expression pattern.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JexlArithmetic(boolean astrict)` Creates a JexlArithmetic.
    `JexlArithmetic(boolean astrict, MathContext bigdContext, int bigdScale)` Creates a JexlArithmetic.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `add(Object left, Object right)` Add two values together.
    `Object` | `and(Object left, Object right)` Performs a bitwise and.
    `JexlArithmetic.ArrayBuilder` | `arrayBuilder(int size)` Called by the interpreter when evaluating a literal array.
    `Object` | `bitwiseAnd(Object lhs, Object rhs)` Deprecated.
    `Object` | `bitwiseOr(Object lhs, Object rhs)` Deprecated.
    `Object` | `bitwiseXor(Object lhs, Object rhs)` Deprecated.
    `Object` | `complement(Object val)` Performs a bitwise complement.
    `Boolean` | `contains(Object container, Object value)` Test if left contains right (right matches/in left).
    `Iterable<?>` | `createRange(Object from, Object to)` Creates a literal range.
    `Object` | `divide(Object left, Object right)` Divide the left value by the right.
    `Boolean` | `empty(Object object)` Check for emptiness of various types: Number, Collection, Array, Map, String.
    `Boolean` | `endsWith(Object left, Object right)` Test if left ends with right.
    `boolean` | `equals(Object left, Object right)` Test if left and right are equal.
    `MathContext` | `getMathContext()` The MathContext instance used for +,-,/,*,% operations on big decimals.
    `int` | `getMathScale()` The BigDecimal scale used for comparison and coericion operations.
    `boolean` | `greaterThan(Object left, Object right)` Test if left > right.
    `boolean` | `greaterThanOrEqual(Object left, Object right)` Test if left >= right.
    `Boolean` | `isEmpty(Object object)` Check for emptiness of various types: Number, Collection, Array, Map, String.
    `Boolean` | `isEmpty(Object object, Boolean def)` Check for emptiness of various types: Number, Collection, Array, Map, String.
    `boolean` | `isNegateStable()` Whether negate called with a given argument will always return the same result.
    `boolean` | `isPositivizeStable()` Whether positivize called with a given argument will always return the same result.
    `boolean` | `isStrict()` Checks whether this JexlArithmetic instance strictly considers null as an error when used as operand unexpectedly.
    `boolean` | `lessThan(Object left, Object right)` Test if left < right.
    `boolean` | `lessThanOrEqual(Object left, Object right)` Test if left <= right.
    `Object` | `logicalNot(Object arg)` Deprecated.
    `JexlArithmetic.MapBuilder` | `mapBuilder(int size)` Called by the interpreter when evaluating a literal map.
    `Object` | `matches(Object lhs, Object rhs)` Deprecated.
    `Object` | `mod(Object left, Object right)` left value modulo right.
    `Object` | `multiply(Object left, Object right)` Multiply the left value by the right.
    `Number` | `narrow(Number original)` Given a Number, return back the value using the smallest type the result will fit into.
    `boolean` | `narrowArguments(Object[] args)` Replace all numbers in an arguments array with the smallest type that will fit.
    `Number` | `narrowNumber(Number original, Class<?> narrow)` Given a Number, return back the value attempting to narrow it to a target class.
    `Object` | `negate(Object val)` Negates a value (unary minus for numbers).
    `Object` | `not(Object val)` Performs a logical not.
    `JexlArithmetic` | `options(JexlContext context)` Apply options to this arithmetic which eventually may create another instance.
    `JexlArithmetic` | `options(JexlEngine.Options options)` Deprecated. 3.2
    `JexlArithmetic` | `options(JexlOptions options)` Apply options to this arithmetic which eventually may create another instance.
    `Object` | `or(Object left, Object right)` Performs a bitwise or.
    `Object` | `positivize(Object val)` Positivize value (unary plus for numbers).
    `JexlArithmetic.SetBuilder` | `setBuilder(int size)` Called by the interpreter when evaluating a literal set.
    `Integer` | `size(Object object)` Calculate the `size` of various types: Collection, Array, Map, String.
    `Integer` | `size(Object object, Integer def)` Calculate the `size` of various types: Collection, Array, Map, String.
    `Boolean` | `startsWith(Object left, Object right)` Test if left starts with right.
    `Object` | `subtract(Object left, Object right)` Subtract the right value from the left.
    `BigDecimal` | `toBigDecimal(Object val)` Coerce to a BigDecimal.
    `BigInteger` | `toBigInteger(Object val)` Coerce to a BigInteger.
    `boolean` | `toBoolean(Object val)` Coerce to a primitive boolean.
    `double` | `toDouble(Object val)` Coerce to a primitive double.
    `int` | `toInteger(Object val)` Coerce to a primitive int.
    `long` | `toLong(Object val)` Coerce to a primitive long.
    `String` | `toString(Object val)` Coerce to a string.
    `Object` | `xor(Object left, Object right)` Performs a bitwise xor.

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

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### FLOAT_PATTERN

          public static final Pattern FLOAT_PATTERN

      The float regular expression pattern.

      The decimal and exponent parts are optional and captured allowing to determine if the number is a real by checking whether one of these 2 capturing groups is not empty.

  - ### Constructor Detail

    - #### JexlArithmetic

          public JexlArithmetic(boolean astrict)

      Creates a JexlArithmetic.

      If you derive your own arithmetic, implement the other constructor that may be needed when dealing with options.

      Parameters:
        `astrict` - whether this arithmetic is strict or lenient

    - #### JexlArithmetic

          public JexlArithmetic(boolean astrict,
                                MathContext bigdContext,
                                int bigdScale)

      Creates a JexlArithmetic.

      The constructor to define in derived classes.

      Parameters:
        `astrict` - whether this arithmetic is lenient or strict
        `bigdContext` - the math context instance to use for +,-,/,*,% operations on big decimals.
        `bigdScale` - the scale used for big decimals.

  - ### Method Detail

    - #### options

          public JexlArithmetic options(JexlOptions options)

      Apply options to this arithmetic which eventually may create another instance.
      Parameters:
        `options` - the `JexlEngine.Options` to use
      Returns:
        an arithmetic with those options set
      See Also:
        `createWithOptions(boolean, java.math.MathContext, int)`

    - #### options

          @Deprecated
          public JexlArithmetic options(JexlEngine.Options options)

      Deprecated. 3.2
      Apply options to this arithmetic which eventually may create another instance.
      Parameters:
        `options` - the `JexlEngine.Options` to use
      Returns:
        an arithmetic with those options set
      See Also:
        `createWithOptions(boolean, java.math.MathContext, int)`

    - #### options

          public JexlArithmetic options(JexlContext context)

      Apply options to this arithmetic which eventually may create another instance.
      Parameters:
        `context` - the context that may extend `JexlContext.OptionsHandle` to use
      Returns:
        a new arithmetic instance or this
      Since:
        3.1
      See Also:
        `createWithOptions(boolean, java.math.MathContext, int)`

    - #### arrayBuilder

          public JexlArithmetic.ArrayBuilder arrayBuilder(int size)

      Called by the interpreter when evaluating a literal array.
      Parameters:
        `size` - the number of elements in the array
      Returns:
        the array builder

    - #### setBuilder

          public JexlArithmetic.SetBuilder setBuilder(int size)

      Called by the interpreter when evaluating a literal set.
      Parameters:
        `size` - the number of elements in the set
      Returns:
        the array builder

    - #### mapBuilder

          public JexlArithmetic.MapBuilder mapBuilder(int size)

      Called by the interpreter when evaluating a literal map.
      Parameters:
        `size` - the number of elements in the map
      Returns:
        the map builder

    - #### createRange

          public Iterable<?> createRange(Object from,
                                         Object to)
                                  throws ArithmeticException

      Creates a literal range.

      The default implementation only accepts integers and longs.

      Parameters:
        `from` - the included lower bound value (null if none)
        `to` - the included upper bound value (null if none)
      Returns:
        the range as an iterable
      Throws:
        `ArithmeticException` - as an option if creation fails

    - #### isStrict

          public boolean isStrict()

      Checks whether this JexlArithmetic instance strictly considers null as an error when used as operand unexpectedly.
      Returns:
        true if strict, false if lenient

    - #### getMathContext

          public MathContext getMathContext()

      The MathContext instance used for +,-,/,*,% operations on big decimals.
      Returns:
        the math context

    - #### getMathScale

          public int getMathScale()

      The BigDecimal scale used for comparison and coericion operations.
      Returns:
        the scale

    - #### narrow

          public Number narrow(Number original)

      Given a Number, return back the value using the smallest type the result will fit into.

      This works hand in hand with parameter 'widening' in java method calls, e.g. a call to substring(int,int) with an int and a long will fail, but a call to substring(int,int) with an int and a short will succeed.

      Parameters:
        `original` - the original number.
      Returns:
        a value of the smallest type the original number will fit into.

    - #### narrowNumber

          public Number narrowNumber(Number original,
                                     Class<?> narrow)

      Given a Number, return back the value attempting to narrow it to a target class.
      Parameters:
        `original` - the original number
        `narrow` - the attempted target class
      Returns:
        the narrowed number or the source if no narrowing was possible

    - #### narrowArguments

          public boolean narrowArguments(Object[] args)

      Replace all numbers in an arguments array with the smallest type that will fit.
      Parameters:
        `args` - the argument array
      Returns:
        true if some arguments were narrowed and args array is modified, false if no narrowing occurred and args array has not been modified

    - #### add

          public Object add(Object left,
                            Object right)

      Add two values together.

      If any numeric add fails on coercion to the appropriate type, treat as Strings and do concatenation.

      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        left + right.

    - #### divide

          public Object divide(Object left,
                               Object right)

      Divide the left value by the right.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        left / right
      Throws:
        `ArithmeticException` - if right == 0

    - #### mod

          public Object mod(Object left,
                            Object right)

      left value modulo right.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        left % right
      Throws:
        `ArithmeticException` - if right == 0.0

    - #### multiply

          public Object multiply(Object left,
                                 Object right)

      Multiply the left value by the right.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        left * right.

    - #### subtract

          public Object subtract(Object left,
                                 Object right)

      Subtract the right value from the left.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        left - right.

    - #### negate

          public Object negate(Object val)

      Negates a value (unary minus for numbers).
      Parameters:
        `val` - the value to negate
      Returns:
        the negated value

    - #### isNegateStable

          public boolean isNegateStable()

      Whether negate called with a given argument will always return the same result.

      This is used to determine whether negate results on number literals can be cached. If the result on calling negate with the same constant argument may change between calls, which means the function is not deterministic, this method must return false.

      Returns:
        true if negate is idempotent, false otherwise
      See Also:
        `isNegateStable()`

    - #### positivize

          public Object positivize(Object val)

      Positivize value (unary plus for numbers).

      C/C++/C#/Java perform integral promotion of the operand, ie cast to int if type can represented as int without loss of precision.

      Parameters:
        `val` - the value to positivize
      Returns:
        the positive value
      See Also:
        `isPositivizeStable()`

    - #### isPositivizeStable

          public boolean isPositivizeStable()

      Whether positivize called with a given argument will always return the same result.

      This is used to determine whether positivize results on number literals can be cached. If the result on calling positivize with the same constant argument may change between calls, which means the function is not deterministic, this method must return false.

      Returns:
        true if positivize is idempotent, false otherwise

    - #### contains

          public Boolean contains(Object container,
                                  Object value)

      Test if left contains right (right matches/in left).

      Beware that this method arguments are the opposite of the operator arguments. 'x in y' means 'y contains x'.

      Parameters:
        `container` - the container
        `value` - the value
      Returns:
        test result or null if there is no arithmetic solution

    - #### endsWith

          public Boolean endsWith(Object left,
                                  Object right)

      Test if left ends with right.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        left $= right if there is no arithmetic solution

    - #### startsWith

          public Boolean startsWith(Object left,
                                    Object right)

      Test if left starts with right.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        left ^= right or null if there is no arithmetic solution

    - #### empty

          public Boolean empty(Object object)

      Check for emptiness of various types: Number, Collection, Array, Map, String.

      Override or overload this method to add new signatures to the size operators.

      Parameters:
        `object` - the object to check the emptiness of
      Returns:
        the boolean or false if object is not null
      Since:
        3.2

    - #### isEmpty

          public Boolean isEmpty(Object object)

      Check for emptiness of various types: Number, Collection, Array, Map, String.
      Parameters:
        `object` - the object to check the emptiness of
      Returns:
        the boolean or null if there is no arithmetic solution

    - #### isEmpty

          public Boolean isEmpty(Object object,
                                 Boolean def)

      Check for emptiness of various types: Number, Collection, Array, Map, String.
      Parameters:
        `object` - the object to check the emptiness of
        `def` - the default value if object emptyness can not be determined
      Returns:
        the boolean or null if there is no arithmetic solution

    - #### size

          public Integer size(Object object)

      Calculate the `size` of various types: Collection, Array, Map, String.
      Parameters:
        `object` - the object to get the size of
      Returns:
        the size of object, 0 if null, 1 if there is no better solution

    - #### size

          public Integer size(Object object,
                              Integer def)

      Calculate the `size` of various types: Collection, Array, Map, String.
      Parameters:
        `object` - the object to get the size of
        `def` - the default value if object size can not be determined
      Returns:
        the size of object or null if there is no arithmetic solution

    - #### and

          public Object and(Object left,
                            Object right)

      Performs a bitwise and.
      Parameters:
        `left` - the left operand
        `right` - the right operator
      Returns:
        left & right

    - #### or

          public Object or(Object left,
                           Object right)

      Performs a bitwise or.
      Parameters:
        `left` - the left operand
        `right` - the right operator
      Returns:
        left | right

    - #### xor

          public Object xor(Object left,
                            Object right)

      Performs a bitwise xor.
      Parameters:
        `left` - the left operand
        `right` - the right operator
      Returns:
        left ^ right

    - #### complement

          public Object complement(Object val)

      Performs a bitwise complement.
      Parameters:
        `val` - the operand
      Returns:
        ~val

    - #### not

          public Object not(Object val)

      Performs a logical not.
      Parameters:
        `val` - the operand
      Returns:
        !val

    - #### equals

          public boolean equals(Object left,
                                Object right)

      Test if left and right are equal.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        the test result

    - #### lessThan

          public boolean lessThan(Object left,
                                  Object right)

      Test if left < right.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        the test result

    - #### greaterThan

          public boolean greaterThan(Object left,
                                     Object right)

      Test if left > right.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        the test result

    - #### lessThanOrEqual

          public boolean lessThanOrEqual(Object left,
                                         Object right)

      Test if left <= right.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        the test result

    - #### greaterThanOrEqual

          public boolean greaterThanOrEqual(Object left,
                                            Object right)

      Test if left >= right.
      Parameters:
        `left` - left argument
        `right` - right argument
      Returns:
        the test result

    - #### toBoolean

          public boolean toBoolean(Object val)

      Coerce to a primitive boolean.

      Double.NaN, null, "false" and empty string coerce to false.

      Parameters:
        `val` - value to coerce
      Returns:
        the boolean value if coercion is possible, true if value was not null.

    - #### toInteger

          public int toInteger(Object val)

      Coerce to a primitive int.

      Double.NaN, null and empty string coerce to zero.

      Boolean false is 0, true is 1.

      Parameters:
        `val` - value to coerce
      Returns:
        the value coerced to int
      Throws:
        `ArithmeticException` - if val is null and mode is strict or if coercion is not possible

    - #### toLong

          public long toLong(Object val)

      Coerce to a primitive long.

      Double.NaN, null and empty string coerce to zero.

      Boolean false is 0, true is 1.

      Parameters:
        `val` - value to coerce
      Returns:
        the value coerced to long
      Throws:
        `ArithmeticException` - if value is null and mode is strict or if coercion is not possible

    - #### toBigInteger

          public BigInteger toBigInteger(Object val)

      Coerce to a BigInteger.

      Double.NaN, null and empty string coerce to zero.

      Boolean false is 0, true is 1.

      Parameters:
        `val` - the object to be coerced.
      Returns:
        a BigDecimal
      Throws:
        `ArithmeticException` - if val is null and mode is strict or if coercion is not possible

    - #### toBigDecimal

          public BigDecimal toBigDecimal(Object val)

      Coerce to a BigDecimal.

      Double.NaN, null and empty string coerce to zero.

      Boolean false is 0, true is 1.

      Parameters:
        `val` - the object to be coerced.
      Returns:
        a BigDecimal.
      Throws:
        `ArithmeticException` - if val is null and mode is strict or if coercion is not possible

    - #### toDouble

          public double toDouble(Object val)

      Coerce to a primitive double.

      Double.NaN, null and empty string coerce to zero.

      Boolean false is 0, true is 1.

      Parameters:
        `val` - value to coerce.
      Returns:
        The double coerced value.
      Throws:
        `ArithmeticException` - if val is null and mode is strict or if coercion is not possible

    - #### toString

          public String toString(Object val)

      Coerce to a string.

      Double.NaN coerce to the empty string.

      Parameters:
        `val` - value to coerce.
      Returns:
        The String coerced value.
      Throws:
        `ArithmeticException` - if val is null and mode is strict or if coercion is not possible

    - #### bitwiseAnd

          @Deprecated
          public final Object bitwiseAnd(Object lhs,
                                                     Object rhs)

      Deprecated.
      Use or overload and() instead.
      Parameters:
        `lhs` - left hand side
        `rhs` - right hand side
      Returns:
        lhs & rhs
      See Also:
        `and(java.lang.Object, java.lang.Object)`

    - #### bitwiseOr

          @Deprecated
          public final Object bitwiseOr(Object lhs,
                                                    Object rhs)

      Deprecated.
      Use or overload or() instead.
      Parameters:
        `lhs` - left hand side
        `rhs` - right hand side
      Returns:
        lhs | rhs
      See Also:
        `or(java.lang.Object, java.lang.Object)`

    - #### bitwiseXor

          @Deprecated
          public final Object bitwiseXor(Object lhs,
                                                     Object rhs)

      Deprecated.
      Use or overload xor() instead.
      Parameters:
        `lhs` - left hand side
        `rhs` - right hand side
      Returns:
        lhs ^ rhs
      See Also:
        `xor(java.lang.Object, java.lang.Object)`

    - #### logicalNot

          @Deprecated
          public final Object logicalNot(Object arg)

      Deprecated.
      Use or overload not() instead.
      Parameters:
        `arg` - argument
      Returns:
        !arg
      See Also:
        `not(java.lang.Object)`

    - #### matches

          @Deprecated
          public final Object matches(Object lhs,
                                                  Object rhs)

      Deprecated.
      Use or overload contains() instead.
      Parameters:
        `lhs` - left hand side
        `rhs` - right hand side
      Returns:
        contains(rhs, lhs)
      See Also:
        `contains(java.lang.Object, java.lang.Object)`

Copyright © 2001–2021 The Apache Software Foundation. All rights reserved.