The Velocity Project < Velocity Tools - Library >

Velocity Tools

Generic Tools

Tool Documentation

Other Subprojects

MathTool Reference Documentation

Tool for performing floating point math in Velocity.

A few things to note:

  • Most methods return numbers wrapped as Double which automatically render the decimal places even for whole numbers (e.g. new Double(1).toString() -> '1.0'). This is intentional. This tool is for floating point arithmetic. Integer arithmetic is already supported by the Velocity template language. If you really need '1' instead of '1.0', just call intValue() on the result.
  • No null pointer, number format, or divide by zero exceptions are thrown here. This is because such exceptions halt template 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)')
  • Class java.lang.Math is used to perform the mathematical operations.
Class
 org.apache.velocity.tools.generic.MathTool
Name
 $math (this is the recommended name of the tool in the Velocity context)
Toolbox Configuration Example
 
<tool>
  <key>math</key>
  <scope>application</scope>
  <class>org.apache.velocity.tools.generic.MathTool</class>
</tool>
Author(s)
  Nathan Bubna
Method Overview
add() Addition
sub() Subtraction
mul() Multiplication
div() Division
pow() Power of
max() Maximum of two numbers
min() Minimum of two numbers
abs() Absolute value of a number
toDouble() Converts a number into a double.
toInteger() Converts a number into an integer
roundTo() Rounds a number to the specified number of decimal places
roundToInt() Rounds a number to the nearest whole Integer
getRandom() Returns a pseudo-random number
random() Returns a pseudo-random number in a configurable range

add()

Addition

Double add(Object num1, Object num2)

Parameters
num1, num2
Operands of the addition. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the sum or null if the input paramters are not valid.


sub()

Subtraction

Double sub(Object num1, Object num2)

Parameters
num1, num2
Operands of the subtraction. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the result of the subtraction or null if the input paramters are not valid.


mul()

Multiplication

Double mul(Object num1, Object num2)

Parameters
num1, num2
Factors of the multiplication. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the result of the multiplication or null if the input paramters are not valid.


div()

Division

Double div(Object num1, Object num2)

Parameters
num1, num2
Input for the division. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the result of the division or null if the input paramters are not valid.


pow()

Power of

Double pow(Object num1, Object num2)

Parameters
num1, num2
Operands. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the first number raised to the power of the second or null if the input paramters are not valid.


max()

Maximum of two numbers

Double max(Object num1, Object num2)

Parameters
num1, num2
Operands. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the maximum of the two numbers or null if the input paramters are not valid.


min()

Minimum of two numbers

Double min(Object num1, Object num2)

Parameters
num1, num2
Operands. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the minimum of the two numbers or null if the input paramters are not valid.


abs()

Absolute value of a number

Double abs(Object num)

Parameters
num
Operand. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the absolute value of the input or null if the input paramter is not valid.


toDouble()

Converts a number into a double.

Double toDouble(Object num)

Parameters
num
Operand. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the input number or null if the input paramter is not valid.


toInteger()

Converts a number into an integer

Integer toInteger(Object num)

Parameters
num
Operand. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Integer representing the input number or null if the input paramter is not valid.


roundTo()

Rounds a number to the specified number of decimal places

Double roundTo(Object decimals, Object num)

Parameters
decimals
The number of decimal places. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
num
The number to round. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Double representing the input number rounded to the specified number of decimal places or null if the input paramter is not valid.

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



roundToInt()

Rounds a number to the nearest whole Integer

Integer roundToInt(Object num)

Parameters
num
The number to round. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Integer representing the input number rounded to nearest whole Integer or null if the input paramter is not valid.


getRandom()

Returns a pseudo-random number

Double getRandom()

Returns
A java.lang.Double greater than or equal to 0.0 and less than 1.0.


random()

Returns a pseudo-random number in a configurable range

Integer random(Object num1, Object num2)

Parameters
num1, num2
First and last number of range. Valid input is any number (primitive types or objects, Velocity automatically converts primitives types to objects) or a string representation of a number.
Returns
A java.lang.Integer greater than or equal to the first number and less than the second number or null if the input paramter is not valid.



Copyright © 1999-2003, Apache Software Foundation