org.apache.velocity.tools.generic

## Class MathTool

- java.lang.Object
- - org.apache.velocity.tools.generic.SafeConfig
  - - org.apache.velocity.tools.generic.LocaleConfig
    - - org.apache.velocity.tools.generic.FormatConfig
      - - org.apache.velocity.tools.generic.MathTool

All Implemented Interfaces:
  Serializable

    @DefaultKey(value="math")
     @ValidScope(value="application")
    public class MathTool
    extends FormatConfig
    implements Serializable

Tool for performing math in Velocity.

Some things should be noted here:

- This class does not have methods that take primitives. This is simply because Velocity wraps all primitives for us automagically.
- No null pointer, number format, or divide by zero exceptions are thrown here. This is because such exceptions thrown in template halt rendering. It should be sufficient debugging feedback that Velocity will render the reference literally. (e.g. $math.div(1, 0) renders as '$math.div(1, 0)')

Example tools.xml config:

     <tools>
       <toolbox scope="application">
         <tool class="org.apache.velocity.tools.generic.MathTool"/>
       </toolbox>
     </tools>

Version:
  $Revision$ $Date$
Author:
  Nathan Bubna, Leon Messerschmidt
See Also:
  Serialized Form

### Field Summary

### Fields inherited from class org.apache.velocity.tools.generic.FormatConfig

`DEFAULT_FORMAT, FORMAT_KEY`

### Fields inherited from class org.apache.velocity.tools.generic.LocaleConfig

`DEFAULT_LOCALE`

### Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

`LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY`

### Constructor Summary

Constructors
Constructor and Description
`MathTool()`

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`Number` `abs(Object num)`
`Number` `add(Object... nums)`
`Number` `add(Object num1, Object num2)`
`Number` `bitwiseAnd(Object... nums)` Bitwise And
`Number` `bitwiseAnd(Object num1, Object num2)`
`Number` `bitwiseOr(Object... nums)` Bitwise Or
`Number` `bitwiseOr(Object num1, Object num2)`
`Number` `bitwiseXOr(Object... nums)` Bitwise XOr
`Number` `bitwiseXOr(Object num1, Object num2)`
`Integer` `ceil(Object num)`
`Number` `div(Object... nums)`
`Number` `div(Object num1, Object num2)`
`Integer` `floor(Object num)`
`Number` `getAverage(Collection collection)` Get the average of the values
`Number` `getAverage(Collection collection, String field)` Get the average of the values from a list
`Number` `getAverage(double... values)` Get the average of the values in an array of double values
`Number` `getAverage(long... values)` Get the average of the values in an array of long values
`Number` `getAverage(Object... array)` Get the average of the values
`Number` `getAverage(Object[] array, String field)` Get the sum of the values from a list
`Double` `getRandom()`
`Number` `getTotal(Collection collection)` Get the sum of the values
`Number` `getTotal(Collection collection, String field)` Get the sum of the values from a list
`Number` `getTotal(double... values)` Get the sum of the values
`Number` `getTotal(long... values)` Get the sum of the values
`Number` `getTotal(Object... array)` Get the sum of the values
`Number` `getTotal(Object[] array, String field)` Get the sum of the values from a list
`protected boolean` `hasFloatingPoint(String value)`
`Integer` `idiv(Object num1, Object num2)` Does integer division on the int values of the specified numbers.
`protected Number` `matchType(double out, Number... in)` Takes the original argument(s) and returns the resulting value as an instance of the best matching type (Integer, Long, or Double).
`protected Number` `matchType(Number in, double out)`
`protected Number` `matchType(Number in1, Number in2, double out)`
`Number` `max(Object... nums)`
`Number` `max(Object num1, Object num2)`
`Number` `min(Object... nums)`
`Number` `min(Object num1, Object num2)`
`Integer` `mod(Object num1, Object num2)` Does integer modulus on the int values of the specified numbers.
`Number` `mul(Object... nums)`
`Number` `mul(Object num1, Object num2)`
`Number` `pow(Object num1, Object num2)`
`Number` `random(Object num1, Object num2)` This returns a random `Number` within the specified range.
`Integer` `round(Object num)` Rounds a number to the nearest whole Integer
`Double` `roundTo(Object decimals, Object num)` Rounds a number to the specified number of decimal places.
`Number` `sub(Object... nums)`
`Number` `sub(Object num1, Object num2)`
`Double` `toDouble(Object num)` Deprecated. use `NumberTool.toNumber(Object)`.doubleValue()
`Integer` `toInteger(Object num)` Deprecated. use `NumberTool.toNumber(Object)`.intValue()
`Long` `toLong(Object num)` Deprecated. use `NumberTool.toNumber(Object)`.longValue()
`Number` `toNumber(Object num)` Deprecated. use `NumberTool.toNumber(Object)`

### Methods inherited from class org.apache.velocity.tools.generic.FormatConfig

`configure, getFormat, setFormat`

### Methods inherited from class org.apache.velocity.tools.generic.LocaleConfig

`getLocale, setLocale, toLocale`

### Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

`configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode`

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

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

### Constructor Detail

#### MathTool

    public MathTool()

### Method Detail

#### add

    public Number add(Object num1,
                      Object num2)

#### sub

    public Number sub(Object num1,
                      Object num2)

#### mul

    public Number mul(Object num1,
                      Object num2)

#### div

    public Number div(Object num1,
                      Object num2)

#### max

    public Number max(Object num1,
                      Object num2)

#### min

    public Number min(Object num1,
                      Object num2)

#### bitwiseOr

    public Number bitwiseOr(Object num1,
                            Object num2)

#### bitwiseAnd

    public Number bitwiseAnd(Object num1,
                             Object num2)

#### bitwiseXOr

    public Number bitwiseXOr(Object num1,
                             Object num2)

#### add

    public Number add(Object... nums)

Parameters:
  `nums` - the numbers to be added
Returns:
  the sum of the numbers or `null` if they're invalid
See Also:
  `toNumber(java.lang.Object)`

#### sub

    public Number sub(Object... nums)

Parameters:
  `nums` - the numbers to be subtracted
Returns:
  the difference of the numbers (subtracted in order) or `null` if they're invalid
See Also:
  `toNumber(java.lang.Object)`

#### mul

    public Number mul(Object... nums)

Parameters:
  `nums` - the numbers to be multiplied
Returns:
  the product of the numbers or `null` if they're invalid
See Also:
  `toNumber(java.lang.Object)`

#### div

    public Number div(Object... nums)

Parameters:
  `nums` - the numbers to be divided
Returns:
  the quotient of the numbers or `null` if they're invalid or if any denominator equals zero
See Also:
  `toNumber(java.lang.Object)`

#### pow

    public Number pow(Object num1,
                      Object num2)

Parameters:
  `num1` - the first number
  `num2` - the second number
Returns:
  the first number raised to the power of the second or `null` if they're invalid
See Also:
  `toNumber(java.lang.Object)`

#### idiv

    public Integer idiv(Object num1,
                        Object num2)

Does integer division on the int values of the specified numbers.

So, $math.idiv('5.1',3) will return '1', and $math.idiv(6,'3.9') will return '2'.

Parameters:
  `num1` - the first number
  `num2` - the second number
Returns:
  the result of performing integer division on the operands.
See Also:
  `toInteger(java.lang.Object)`

#### mod

    public Integer mod(Object num1,
                       Object num2)

Does integer modulus on the int values of the specified numbers.

So, $math.mod('5.1',3) will return '2', and $math.mod(6,'3.9') will return '0'.

Parameters:
  `num1` - the first number
  `num2` - the second number
Returns:
  the result of performing integer modulus on the operands.
See Also:
  `toInteger(java.lang.Object)`

#### bitwiseOr

    public Number bitwiseOr(Object... nums)

Bitwise Or

Parameters:
  `nums` - the numbers to be Or'ed
Returns:
  the bitwise Or of the numbers or `null` if they're invalid
See Also:
  `toInteger(java.lang.Object)`

#### bitwiseAnd

    public Number bitwiseAnd(Object... nums)

Bitwise And

Parameters:
  `nums` - the numbers to be And'ed
Returns:
  the bitwise And of the numbers or `null` if they're invalid
See Also:
  `toInteger(java.lang.Object)`

#### bitwiseXOr

    public Number bitwiseXOr(Object... nums)

Bitwise XOr

Parameters:
  `nums` - the numbers to be XOr'ed
Returns:
  the bitwise XOr of the numbers or `null` if they're invalid
See Also:
  `toInteger(java.lang.Object)`

#### max

    public Number max(Object... nums)

Parameters:
  `nums` - the numbers to be searched
Returns:
  the largest of the numbers or `null` if they're invalid
See Also:
  `toNumber(java.lang.Object)`

#### min

    public Number min(Object... nums)

Parameters:
  `nums` - the numbers to be searched
Returns:
  the smallest of the numbers or `null` if they're invalid
See Also:
  `toNumber(java.lang.Object)`

#### abs

    public Number abs(Object num)

Parameters:
  `num` - the number
Returns:
  the absolute value of the number or `null` if it's invalid
See Also:
  `toDouble(java.lang.Object)`

#### ceil

    public Integer ceil(Object num)

Parameters:
  `num` - the number
Returns:
  the smallest integer that is not less than the given number

#### floor

    public Integer floor(Object num)

Parameters:
  `num` - the number
Returns:
  the integer portion of the number

#### round

    public Integer round(Object num)

Rounds a number to the nearest whole Integer

Parameters:
  `num` - the number to round
Returns:
  the number rounded to the nearest whole Integer or `null` if it's invalid
See Also:
  `Math.rint(double)`

#### roundTo

    public Double roundTo(Object decimals,
                          Object num)

Rounds a number to the specified number of decimal places. This is particulary useful for simple display formatting. If you want to round an number to the nearest integer, it is better to use `round(java.lang.Object)`, as that will return an `Integer` rather than a `Double`.

Parameters:
  `decimals` - the number of decimal places
  `num` - the number to round
Returns:
  the value rounded to the specified number of decimal places or `null` if it's invalid
See Also:
  `toNumber(java.lang.Object)`

#### getRandom

    public Double getRandom()

Returns:
  a pseudo-random `Double` greater than or equal to 0.0 and less than 1.0
See Also:
  `Math.random()`

#### random

    public Number random(Object num1,
                         Object num2)

This returns a random `Number` within the specified range. The returned value will be greater than or equal to the first number and less than the second number. If both arguments are whole numbers then the returned number will also be, otherwise a `Double` will be returned.

Parameters:
  `num1` - the first number
  `num2` - the second number
Returns:
  a pseudo-random `Number` greater than or equal to the first number and less than the second
See Also:
  `Math.random()`

#### toInteger

    @Deprecated
    public Integer toInteger(Object num)

Deprecated. use `NumberTool.toNumber(Object)`.intValue()
Converts an object with a numeric value into an Integer Valid formats are `Number` or a `String` representation of a number

Parameters:
  `num` - the number to be converted
Returns:
  a `Integer` representation of the number or `null` if it's invalid

#### toLong

    @Deprecated
    public Long toLong(Object num)

Deprecated. use `NumberTool.toNumber(Object)`.longValue()
Converts an object with a numeric value into a Long integer Valid formats are `Number` or a `String` representation of a number

Parameters:
  `num` - the number to be converted
Returns:
  a `Long` integer representation of the number or `null` if it's invalid

#### toDouble

    @Deprecated
    public Double toDouble(Object num)

Deprecated. use `NumberTool.toNumber(Object)`.doubleValue()
Converts an object with a numeric value into a Double Valid formats are `Number` or a `String` representation of a number

Parameters:
  `num` - the number to be converted
Returns:
  a `Double` representation of the number or `null` if it's invalid

#### toNumber

    @Deprecated
    public Number toNumber(Object num)

Deprecated. use `NumberTool.toNumber(Object)`
Converts an object with a numeric value into a Number Valid formats are `Number` or a `String` representation of a number. Note that this does not handle localized number formats. Use the `NumberTool` to handle such conversions.

Parameters:
  `num` - the number to be converted
Returns:
  a `Number` representation of the number or `null` if it's invalid

#### matchType

    protected Number matchType(Number in,
                               double out)

Parameters:
  `in` - instance of wanted Number class
  `out` - input number
Returns:
  wanted Number
See Also:
  `matchType(double,Number...)`

#### matchType

    protected Number matchType(Number in1,
                               Number in2,
                               double out)

Parameters:
  `in1` - instance #1 of wanted Number class
  `in2` - instance #1 of wanted Number class
  `out` - input number
Returns:
  wanted Number
See Also:
  `matchType(double,Number...)`

#### matchType

    protected Number matchType(double out,
                               Number... in)

Takes the original argument(s) and returns the resulting value as an instance of the best matching type (Integer, Long, or Double). If either an argument or the result is not an integer (i.e. has no decimal when rendered) the result will be returned as a Double. If not and the result is < -2147483648 or > 2147483647, then a Long will be returned. Otherwise, an Integer will be returned.

Parameters:
  `out` - target number value
  `in` - wanted Number classes
Returns:
  wanted Number

#### hasFloatingPoint

    protected boolean hasFloatingPoint(String value)

Parameters:
  `value` - target value
Returns:
  wether it contains a decimal separator (non locale-aware for now - TODO)

#### getTotal

    public Number getTotal(Collection collection,
                           String field)

Get the sum of the values from a list

Parameters:
  `collection` - A collection containing Java beans
  `field` - A Java Bean field for the objects in collection that will return a number.
Returns:
  The sum of the values in collection.

#### getAverage

    public Number getAverage(Collection collection,
                             String field)

Get the average of the values from a list

Parameters:
  `collection` - A collection containing Java beans
  `field` - A Java Bean field for the objects in collection that will return a number.
Returns:
  The average of the values in collection.

#### getTotal

    public Number getTotal(Object[] array,
                           String field)

Get the sum of the values from a list

Parameters:
  `array` - An array containing Java beans
  `field` - A Java Bean field for the objects in array that will return a number.
Returns:
  The sum of the values in array.

#### getAverage

    public Number getAverage(Object[] array,
                             String field)

Get the sum of the values from a list

Parameters:
  `array` - A collection containing Java beans
  `field` - A Java Bean field for the objects in array that will return a number.
Returns:
  The sum of the values in array.

#### getTotal

    public Number getTotal(Collection collection)

Get the sum of the values

Parameters:
  `collection` - A collection containing numeric values
Returns:
  The sum of the values in collection.

#### getAverage

    public Number getAverage(Collection collection)

Get the average of the values

Parameters:
  `collection` - A collection containing number values
Returns:
  The average of the values in collection.

#### getTotal

    public Number getTotal(Object... array)

Get the sum of the values

Parameters:
  `array` - An array containing number values
Returns:
  The sum of the values in array.

#### getAverage

    public Number getAverage(Object... array)

Get the average of the values

Parameters:
  `array` - An array containing number values
Returns:
  The sum of the values in array.

#### getTotal

    public Number getTotal(double... values)

Get the sum of the values

Parameters:
  `values` - The list of double values to add up.
Returns:
  The sum of the arrays

#### getAverage

    public Number getAverage(double... values)

Get the average of the values in an array of double values

Parameters:
  `values` - The list of double values
Returns:
  The average of the array of values

#### getTotal

    public Number getTotal(long... values)

Get the sum of the values

Parameters:
  `values` - The list of long values to add up.
Returns:
  The sum of the arrays

#### getAverage

    public Number getAverage(long... values)

Get the average of the values in an array of long values

Parameters:
  `values` - The list of long values
Returns:
  The average of the array of values