Package org.apache.velocity.tools.generic

Class MathTool

  • All Implemented Interfaces:
    java.io.Serializable
    @DefaultKey("math")
@ValidScope("application")
public class MathTool
extends FormatConfig
implements java.io.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

    • Constructor Summary

      Constructors 
      Constructor Description
      MathTool()  

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      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.Number bitwiseAnd​(java.lang.Object... nums)
      Bitwise And
      java.lang.Number bitwiseAnd​(java.lang.Object num1, java.lang.Object num2)  
      java.lang.Number bitwiseOr​(java.lang.Object... nums)
      Bitwise Or
      java.lang.Number bitwiseOr​(java.lang.Object num1, java.lang.Object num2)  
      java.lang.Number bitwiseXOr​(java.lang.Object... nums)
      Bitwise XOr
      java.lang.Number bitwiseXOr​(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​(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.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.Double getRandom()  
      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
      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
      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)  
      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)
      Deprecated.
      use NumberTool.toNumber(Object).doubleValue()
      java.lang.Integer toInteger​(java.lang.Object num)
      Deprecated.
      use NumberTool.toNumber(Object).intValue()
      java.lang.Long toLong​(java.lang.Object num)
      Deprecated.
      use NumberTool.toNumber(Object).longValue()
      java.lang.Number toNumber​(java.lang.Object num)
      Deprecated.
      use NumberTool.toNumber(Object)

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

      • bitwiseOr

        public java.lang.Number bitwiseOr​(java.lang.Object num1,
                                  java.lang.Object num2)

      • bitwiseAnd

        public java.lang.Number bitwiseAnd​(java.lang.Object num1,
                                   java.lang.Object num2)

      • bitwiseXOr

        public java.lang.Number bitwiseXOr​(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)

      • bitwiseOr

        public java.lang.Number bitwiseOr​(java.lang.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 java.lang.Number bitwiseAnd​(java.lang.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 java.lang.Number bitwiseXOr​(java.lang.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 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

        @Deprecated
public java.lang.Integer toInteger​(java.lang.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 java.lang.Long toLong​(java.lang.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 java.lang.Double toDouble​(java.lang.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 java.lang.Number toNumber​(java.lang.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 java.lang.Number matchType​(java.lang.Number in,
                                     double out)
        Parameters:
        in - instance of wanted Number class
        out - input number
        Returns:
        wanted Number
        See Also:
        matchType(double,Number...)

      • matchType

        protected java.lang.Number matchType​(java.lang.Number in1,
                                     java.lang.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 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.
        Parameters:
        out - target number value
        in - wanted Number classes
        Returns:
        wanted Number

      • hasFloatingPoint

        protected boolean hasFloatingPoint​(java.lang.String value)
        Parameters:
        value - target value
        Returns:
        wether it contains a decimal separator (non locale-aware for now - TODO)

      • 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