MathTool (VelocityTools 3.0 API)

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: 1842514 $ $Date: 2018-10-01 18:09:11 +0200 (Mon, 01 Oct 2018) $

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()

Constructors
Constructor and Description
`MathTool()`

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`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

Class MathTool

Field Summary

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

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

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

Constructor Summary

Method Summary

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

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

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

Methods inherited from class java.lang.Object

Constructor Detail

MathTool

Method Detail

add

sub

mul

div

max

min

bitwiseOr

bitwiseAnd

bitwiseXOr

add

sub

mul

div

pow

idiv

mod

bitwiseOr

bitwiseAnd

bitwiseXOr

max

min

abs

ceil

floor

round

roundTo

getRandom

random

toInteger

toLong

toDouble

toNumber

matchType

matchType

matchType

hasFloatingPoint

getTotal

getAverage

getTotal

getAverage

getTotal

getAverage

getTotal

getAverage

getTotal

getAverage

getTotal

getAverage