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

@DefaultKey(value="math")
public class MathTool
extends FormatConfig

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: 696463 $ $Date: 2008-09-17 14:39:04 -0700 (Wed, 17 Sep 2008) $

Author:

Nathan Bubna, Leon Messerschmidt

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, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY

Constructor Summary

MathTool()

Method Summary

java.lang.Number	abs(java.lang.Object num)
java.lang.Number	add(java.lang.Object... nums)
java.lang.Number	add(java.lang.Object num1, java.lang.Object num2)
java.lang.Integer	ceil(java.lang.Object num)
java.lang.Number	div(java.lang.Object... nums)
java.lang.Number	div(java.lang.Object num1, java.lang.Object num2)
java.lang.Integer	floor(java.lang.Object num)
java.lang.Number	getAverage(java.util.Collection collection) Get the average of the values
java.lang.Number	getAverage(java.util.Collection collection, java.lang.String field) Get the average of the values from a list
java.lang.Number	getAverage(double... values) Get the average of the values in an array of double values
java.lang.Number	getAverage(long... values) Get the average of the values in an array of long values
java.lang.Number	getAverage(java.lang.Object... array) Get the average of the values
java.lang.Number	getAverage(java.lang.Object[] array, java.lang.String field) Get the sum of the values from a list
java.lang.Double	getRandom()
java.lang.Number	getTotal(java.util.Collection collection) Get the sum of the values
java.lang.Number	getTotal(java.util.Collection collection, java.lang.String field) Get the sum of the values from a list
java.lang.Number	getTotal(double... values) Get the sum of the values
java.lang.Number	getTotal(long... values) Get the sum of the values
java.lang.Number	getTotal(java.lang.Object... array) Get the sum of the values
java.lang.Number	getTotal(java.lang.Object[] array, java.lang.String field) Get the sum of the values from a list
protected boolean	hasFloatingPoint(java.lang.String value)
java.lang.Integer	idiv(java.lang.Object num1, java.lang.Object num2) Does integer division on the int values of the specified numbers.
protected java.lang.Number	matchType(double out, java.lang.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 java.lang.Number	matchType(java.lang.Number in, double out)
protected java.lang.Number	matchType(java.lang.Number in1, java.lang.Number in2, double out)
java.lang.Number	max(java.lang.Object... nums)
java.lang.Number	max(java.lang.Object num1, java.lang.Object num2)
java.lang.Number	min(java.lang.Object... nums)
java.lang.Number	min(java.lang.Object num1, java.lang.Object num2)
java.lang.Integer	mod(java.lang.Object num1, java.lang.Object num2) Does integer modulus on the int values of the specified numbers.
java.lang.Number	mul(java.lang.Object... nums)
java.lang.Number	mul(java.lang.Object num1, java.lang.Object num2)
protected java.lang.Number	parseNumber(java.lang.String value) Deprecated.
java.lang.Number	pow(java.lang.Object num1, java.lang.Object num2)
java.lang.Number	random(java.lang.Object num1, java.lang.Object num2) This returns a random Number within the specified range.
java.lang.Integer	round(java.lang.Object num) Rounds a number to the nearest whole Integer
java.lang.Double	roundTo(java.lang.Object decimals, java.lang.Object num) Rounds a number to the specified number of decimal places.
java.lang.Number	sub(java.lang.Object... nums)
java.lang.Number	sub(java.lang.Object num1, java.lang.Object num2)
java.lang.Double	toDouble(java.lang.Object num) Converts an object with a numeric value into a Double Valid formats are Number or a String representation of a number
java.lang.Integer	toInteger(java.lang.Object num) Converts an object with a numeric value into an Integer Valid formats are Number or a String representation of a number
java.lang.Number	toNumber(java.lang.Object num) Converts an object with a numeric value into a Number Valid formats are Number or a String representation of a number.

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

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

configure, 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 java.lang.Number add(java.lang.Object num1,
                            java.lang.Object num2)

sub

public java.lang.Number sub(java.lang.Object num1,
                            java.lang.Object num2)

mul

public java.lang.Number mul(java.lang.Object num1,
                            java.lang.Object num2)

div

public java.lang.Number div(java.lang.Object num1,
                            java.lang.Object num2)

max

public java.lang.Number max(java.lang.Object num1,
                            java.lang.Object num2)

min

public java.lang.Number min(java.lang.Object num1,
                            java.lang.Object num2)

add

public java.lang.Number add(java.lang.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 java.lang.Number sub(java.lang.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 java.lang.Number mul(java.lang.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 java.lang.Number div(java.lang.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 java.lang.Number pow(java.lang.Object num1,
                            java.lang.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 java.lang.Integer idiv(java.lang.Object num1,
                              java.lang.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 java.lang.Integer mod(java.lang.Object num1,
                             java.lang.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)

max

public java.lang.Number max(java.lang.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 java.lang.Number min(java.lang.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 java.lang.Number abs(java.lang.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 java.lang.Integer ceil(java.lang.Object num)

Parameters:

num - the number

Returns:

the smallest integer that is not less than the given number

floor

public java.lang.Integer floor(java.lang.Object num)

Parameters:

num - the number

Returns:

the integer portion of the number

round

public java.lang.Integer round(java.lang.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 java.lang.Double roundTo(java.lang.Object decimals,
                                java.lang.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 java.lang.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 java.lang.Number random(java.lang.Object num1,
                               java.lang.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

public java.lang.Integer toInteger(java.lang.Object num)

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

toDouble

public java.lang.Double toDouble(java.lang.Object num)

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

public java.lang.Number toNumber(java.lang.Object num)

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 java.lang.Number matchType(java.lang.Number in,
                                     double out)

See Also:

matchType(double,Number...)

matchType

protected java.lang.Number matchType(java.lang.Number in1,
                                     java.lang.Number in2,
                                     double out)

See Also:

matchType(double,Number...)

matchType

protected java.lang.Number matchType(double out,
                                     java.lang.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.

hasFloatingPoint

protected boolean hasFloatingPoint(java.lang.String value)

parseNumber

@Deprecated
protected java.lang.Number parseNumber(java.lang.String value)

Deprecated.

getTotal

public java.lang.Number getTotal(java.util.Collection collection,
                                 java.lang.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 java.lang.Number getAverage(java.util.Collection collection,
                                   java.lang.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 java.lang.Number getTotal(java.lang.Object[] array,
                                 java.lang.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 java.lang.Number getAverage(java.lang.Object[] array,
                                   java.lang.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 java.lang.Number getTotal(java.util.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 java.lang.Number getAverage(java.util.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 java.lang.Number getTotal(java.lang.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 java.lang.Number getAverage(java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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