The MathTool viewtool provides methods to perform floating point math in Velocity. It utilizes the java.lang.Math class to perform calculations.
The following example shows how the ListTool is mapped in the toolbox.xml file:
<tool>
<key>math</key>
<scope>application</scope>
<class>org.apache.velocity.tools.generic.MathTool</class>
</tool>
Important Notes
Number Format
Most methods in this tool return numbers wrapped as Double, which automatically render the decimal places, even for whole numbers. For example, the call $math.add(1, 2).toString() returns “3.0” rather than just “3”.
- This is intentional.
- The MathTool tool is intended for floating point arithmetic.
- Integer arithmetic is already supported directly by the Velocity template language.
- If you need to convert the result of a MathTool method to an integer, use the
$math.toInteger()method or call the built-in VelocityintValue()method on the result; for example:$math.toInteger($math.add(1, 2)) $math.add(1, 2).intValue()
Exception Handling
None of the MathTool methods throw exceptions for null pointers, number formats, or divide by zero.
- This is intentional (the methods are designed to intentionally fail silently), because throwing these exceptions would halt HTML rendering.
- However even though no exceptions are thrown, you can identify errors, because when an error occurs Velocity will render the reference literally (e.g.
$math.div(1, 0)renders as “$math.div(1, 0)“).
Methods and Usage
The MathTool supports the following methods:
| Method | Operation | Return Value |
|---|---|---|
$math.add( x, y ) | Addition | x plus y. |
$math.sub( x, y ) | Subtraction | x minus y. |
$math.mul( x, y ) | Multiplication | x multiplied by y. |
$math.div( x, y ) | Division | x divided by y. |
$math.mod( x, y ) | Modulus | The integer remainder of integer x divided by integer y. |
$math.pow( x, y ) | Power (Exponent) | x raised to the power of y. |
$math.abs( x ) | Absolute value | The absolute value of x. |
$math.max( x, y ) | Maximum | The maximum of x and y.Note: This method accepts a maximum of 2 arguments. |
$math.min( x, y ) | Minimum | The minimum of x and y.Note: This method accepts a maximum of 2 arguments. |
$math.ceil( x ) | Ceiling | The smallest integer greater than or equal to x. |
$math.floor( x ) | Floor | The integer portion of x. |
$math.round( x ) | Rounding | x rounded to the nearest whole integer. |
$math.roundTo( x, y ) | Rounding | x rounded to y decimal places. |
$math.getAverage( l ) | Average | The average of all values in list or collection 'l'. See Parameters, below |
$math.getTotal( l ) | Total (Sum) | The sum of all values in list or collection 'l'. See Parameters, below |
$math.getRandom() | Random number | A pseudo-random number in the range from 0 to 1. |
$math.random( x, y ) | Random number in range | A pseudo-random number in the range from x to y. |
$math.toDouble( x ) | Double conversion | x converted to a double.See Parameters, below. |
$math.toInteger( x ) | Integer conversion | x converted to an integer.See Parameters, below. |
Parameters
With the exception of the methods listed below, all arguments supplied to all methods must be numbers. Integer arguments will be automatically converted to floating point numbers when supplied as arguments.
Methods accepting arguments other than numbers:
| Method | Parameter Type(s) | Example |
|---|---|---|
| getAverage() | A list or collection containing only numbers. | $math.getAverage( [ 1, 2, 3 ] ) |
| getTotal() | A list or collection containing only numbers. | $math.getTotal( [ 1, 2, 3 ] ) |
| getRandom() | Does not take any arguments. | getRandom() |
| toDouble() | Either a number or a string containing a numeric format. | $math.toDouble( 5 )$math.toDouble( "5.6" ) |
| toInteger() | Either a number or a string containing a numeric format. | $math.toInteger( 5.6 )$math.toInteger( "5" ) |
Math in Velocity
If you are performing only simple mathematical operations, you may be able to perform them without using the MathTool. Velocity supports simple math through the use of the #set() directive, including addition, subtraction, multiplication, division and modulus. The following table shows how to use #set directive mathematical operations, in comparison to using the MathTool:
| Operator | MathTool | Velocity |
|---|---|---|
| Addition | #set($result = $math.add($value1, 1)) | #set($result = $value1 + 1) |
| Subtraction | #set($result = $math.sub($value1, 2)) | #set($result = $value1 - 2) |
| Multiplication | #set($result = $math.mul($value1, 3)) | #set($result = $value1 * 3) |
| Division | #set($result = $math.div($value1, 4)) | #set($result = $value1 / 4) |
| Modulus | #set($result = $math.mod($value1, 5)) | #set($result = $value1 % 5) |
Note: The Velocity #set directive can perform mathematical operations on both integers and floating point numbers. However operations on floating point numbers are not precise, and may contain errors in far decomal places, so if calculation accuracy is important, you should use the MathTool instead of Velocity.
