org.apache.velocity.tools.generic
Class NumberTool

java.lang.Object
  extended by org.apache.velocity.tools.generic.SafeConfig
      extended by org.apache.velocity.tools.generic.LocaleConfig
          extended by org.apache.velocity.tools.generic.FormatConfig
              extended by org.apache.velocity.tools.generic.NumberTool

@DefaultKey(value="number")
public class NumberTool
extends FormatConfig

Tool for working with Number in Velocity templates. It is useful for accessing and formatting arbitrary Number objects. Also the tool can be used to retrieve NumberFormat instances or make conversions to and from various number types.

 Example uses:
  $myNumber                            -> 13.55
  $number.format($myNumber)   -> 13.6
  $number.currency($myNumber) -> $13.55
  $number.integer($myNumber)  -> 13

 Example tools.xml config (if you want to use this with VelocityView):
 <tools>
   <toolbox scope="application">
     <tool class="org.apache.velocity.tools.generic.MathTool"/>
   </toolbox>
 </tools>
 

This tool is entirely threadsafe, and has no instance members. It may be used in any scope (request, session, or application). As such, the methods are highly interconnected, and overriding key methods provides an easy way to create subclasses that use a non-default format or locale.

Since:
VelocityTools 1.2
Version:
$Id: NumberTool.java 671008 2008-06-24 03:37:33Z nbubna $
Author:
Nathan Bubna, Mike Kienenberger

Field Summary
static java.lang.String DEFAULT_FORMAT_KEY
          Deprecated. 
static java.lang.String DEFAULT_LOCALE_KEY
          Deprecated. 
 
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
NumberTool()
           
 
Method Summary
 java.lang.String currency(java.lang.Object obj)
          Convenience method equivalent to $number.format("currency", $foo).
 java.lang.String format(java.lang.Object obj)
          Converts the specified object to a number and formats it according to the pattern or style returned by FormatConfig.getFormat().
 java.lang.String format(java.lang.String format, java.lang.Object obj)
          Converts the specified object to a number and returns a formatted string representing that number in the locale returned by LocaleConfig.getLocale().
 java.lang.String format(java.lang.String format, java.lang.Object obj, java.util.Locale locale)
          Converts the specified object to a number and returns a formatted string representing that number in the specified Locale.
protected  java.text.NumberFormat getNumberFormat(int numberStyle, java.util.Locale locale)
          Deprecated. 
 java.text.NumberFormat getNumberFormat(java.lang.String format, java.util.Locale locale)
          Returns a NumberFormat instance for the specified format and Locale.
protected  int getStyleAsInt(java.lang.String style)
          Deprecated. 
 java.lang.String integer(java.lang.Object obj)
          Convenience method equivalent to $number.format("integer", $foo).
 java.lang.String number(java.lang.Object obj)
          Convenience method equivalent to $number.format("number", $foo).
 java.lang.String percent(java.lang.Object obj)
          Convenience method equivalent to $number.format("percent", $foo).
 java.lang.Number toNumber(java.lang.Object obj)
          Converts an object to an instance of Number using the format returned by FormatConfig.getFormat() and the Locale returned by LocaleConfig.getLocale() if the object is not already an instance of Number.
 java.lang.Number toNumber(java.lang.String format, java.lang.Object obj)
          Converts an object to an instance of Number using the specified format and the Locale returned by LocaleConfig.getLocale() if the object is not already an instance of Number.
 java.lang.Number toNumber(java.lang.String format, java.lang.Object obj, java.util.Locale locale)
          Converts an object to an instance of Number using the specified format and Localeif the object is not already an instance of 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
 

Field Detail

DEFAULT_FORMAT_KEY

@Deprecated
public static final java.lang.String DEFAULT_FORMAT_KEY
Deprecated. 
See Also:
Constant Field Values

DEFAULT_LOCALE_KEY

@Deprecated
public static final java.lang.String DEFAULT_LOCALE_KEY
Deprecated. 
See Also:
Constant Field Values
Constructor Detail

NumberTool

public NumberTool()
Method Detail

format

public java.lang.String format(java.lang.Object obj)
Converts the specified object to a number and formats it according to the pattern or style returned by FormatConfig.getFormat().

Parameters:
obj - the number object to be formatted
Returns:
the specified number formatted as a string
See Also:
format(String format, Object obj, Locale locale)

currency

public java.lang.String currency(java.lang.Object obj)
Convenience method equivalent to $number.format("currency", $foo).

Since:
VelocityTools 1.3

integer

public java.lang.String integer(java.lang.Object obj)
Convenience method equivalent to $number.format("integer", $foo).

Since:
VelocityTools 1.3

number

public java.lang.String number(java.lang.Object obj)
Convenience method equivalent to $number.format("number", $foo).

Since:
VelocityTools 1.3

percent

public java.lang.String percent(java.lang.Object obj)
Convenience method equivalent to $number.format("percent", $foo).

Since:
VelocityTools 1.3

format

public java.lang.String format(java.lang.String format,
                               java.lang.Object obj)
Converts the specified object to a number and returns a formatted string representing that number in the locale returned by LocaleConfig.getLocale().

Parameters:
format - the formatting instructions
obj - the number object to be formatted
Returns:
a formatted string for this locale representing the specified number or null if the parameters are invalid
See Also:
format(String format, Object obj, Locale locale)

format

public java.lang.String format(java.lang.String format,
                               java.lang.Object obj,
                               java.util.Locale locale)
Converts the specified object to a number and returns a formatted string representing that number in the specified Locale.

Parameters:
format - the custom or standard pattern to be used
obj - the number object to be formatted
locale - the Locale to be used when formatting
Returns:
a formatted string representing the specified number or null if the parameters are invalid

getNumberFormat

public java.text.NumberFormat getNumberFormat(java.lang.String format,
                                              java.util.Locale locale)
Returns a NumberFormat instance for the specified format and Locale. If the format specified is a standard style pattern, then a number instance will be returned with the number style set to the specified style. If it is a custom format, then a customized NumberFormat will be returned.

Parameters:
format - the custom or standard formatting pattern to be used
locale - the Locale to be used
Returns:
an instance of NumberFormat
See Also:
NumberFormat

getNumberFormat

@Deprecated
protected java.text.NumberFormat getNumberFormat(int numberStyle,
                                                            java.util.Locale locale)
Deprecated. 

Returns a NumberFormat instance for the specified number style and Locale.

Parameters:
numberStyle - the number style (number will be ignored if this is less than zero or the number style is not recognized)
locale - the Locale to be used
Returns:
an instance of NumberFormat or null if an instance cannot be constructed with the given parameters

getStyleAsInt

@Deprecated
protected int getStyleAsInt(java.lang.String style)
Deprecated. 

Checks a string to see if it matches one of the standard NumberFormat style patterns: NUMBER, CURRENCY, PERCENT, INTEGER, or DEFAULT. if it does it will return the integer constant for that pattern. if not, it will return -1.

Parameters:
style - the string to be checked
Returns:
the int identifying the style pattern
See Also:
NumberFormat

toNumber

public java.lang.Number toNumber(java.lang.Object obj)
Converts an object to an instance of Number using the format returned by FormatConfig.getFormat() and the Locale returned by LocaleConfig.getLocale() if the object is not already an instance of Number.

Parameters:
obj - the number to convert
Returns:
the object as a Number or null if no conversion is possible

toNumber

public java.lang.Number toNumber(java.lang.String format,
                                 java.lang.Object obj)
Converts an object to an instance of Number using the specified format and the Locale returned by LocaleConfig.getLocale() if the object is not already an instance of Number.

Parameters:
format - - the format the number is in
obj - - the number to convert
Returns:
the object as a Number or null if no conversion is possible
See Also:
toNumber(String format, Object obj, Locale locale)

toNumber

public java.lang.Number toNumber(java.lang.String format,
                                 java.lang.Object obj,
                                 java.util.Locale locale)
Converts an object to an instance of Number using the specified format and Localeif the object is not already an instance of Number.

Parameters:
format - - the format the number is in
obj - - the number to convert
locale - - the Locale
Returns:
the object as a Number or null if no conversion is possible
See Also:
NumberFormat.parse(java.lang.String, java.text.ParsePosition)


Copyright (c) 2003-2007 Apache Software Foundation