java.lang.Object
- org.apache.velocity.tools.generic.NumberTool

```
public class NumberTool
extends java.lang.Object
```
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 toolbox.xml config (if you want to use this with VelocityView):
 <tool>
   <key>number</key>
   <scope>application</scope>
   <class>org.apache.velocity.tools.generic.NumberTool</class>
   <parameter name="format" value="#0.0"/>
 </tool>
 
```
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 509841 2007-02-21 01:00:28Z nbubna $

Author:

Nathan Bubna, Mike Kienenberger

Field Summary

Fields
Modifier and Type	Field	Description
`private boolean`	`configLocked`
`static java.lang.String`	`DEFAULT_FORMAT`	The default format to be used when none is specified.
`static java.lang.String`	`DEFAULT_FORMAT_KEY`	The key used for specifying a default format via toolbox params.
`static java.lang.String`	`DEFAULT_LOCALE_KEY`	The key used for specifying a default locale via toolbox params.
`private java.lang.String`	`format`
`private java.util.Locale`	`locale`
`static java.lang.String`	`LOCK_CONFIG_KEY`	The key used for specifying whether or not to prevent templates from reconfiguring this tool.
`private static int`	`STYLE_CURRENCY`
`private static int`	`STYLE_INTEGER`
`private static int`	`STYLE_NUMBER`
`private static int`	`STYLE_PERCENT`

Constructor Summary

Constructors
Constructor Description

NumberTool()

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`configure(java.util.Map params)`	Looks for configuration values in the given params.
`protected void`	`configure(ValueParser values)`	Does the actual configuration.
`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 `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 `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`.
`java.lang.String`	`getFormat()`	Return the pattern or style to be used for formatting numbers when none is specified.
`private java.text.NumberFormat`	`getIntegerInstance(java.util.Locale locale)`	Since we wish to continue supporting Java 1.3, for the present we cannot use Java 1.4's NumberFormat.getIntegerInstance(Locale) method.
`java.util.Locale`	`getLocale()`	This implementation returns the configured default locale.
`protected java.text.NumberFormat`	`getNumberFormat(int numberStyle, java.util.Locale locale)`	Returns a `NumberFormat` instance for the specified number style and `Locale`.
`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)`	Checks a string to see if it matches one of the standard NumberFormat style patterns: NUMBER, CURRENCY, PERCENT, INTEGER, or DEFAULT.
`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).
`protected void`	`setFormat(java.lang.String format)`	Sets the default format for this instance.
`protected void`	`setLocale(java.util.Locale locale)`	Sets the default locale for this instance.
`java.lang.Number`	`toNumber(java.lang.Object obj)`	Converts an object to an instance of `Number` using the format returned by `getFormat()` and the `Locale` returned by `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 `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 `Locale`if the object is not already an instance of Number.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_FORMAT
```
public static final java.lang.String DEFAULT_FORMAT
```
    The default format to be used when none is specified.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_FORMAT_KEY
```
public static final java.lang.String DEFAULT_FORMAT_KEY
```
    The key used for specifying a default format via toolbox params.
    
    Since:
    
    VelocityTools 1.4
    
    See Also:
    
    Constant Field Values
  - DEFAULT_LOCALE_KEY
```
public static final java.lang.String DEFAULT_LOCALE_KEY
```
    The key used for specifying a default locale via toolbox params.
    
    Since:
    
    VelocityTools 1.4
    
    See Also:
    
    Constant Field Values
  - LOCK_CONFIG_KEY
```
public static final java.lang.String LOCK_CONFIG_KEY
```
    The key used for specifying whether or not to prevent templates from reconfiguring this tool. The default is true.
    
    Since:
    
    VelocityTools 1.4
    
    See Also:
    
    Constant Field Values
  - STYLE_NUMBER
```
private static final int STYLE_NUMBER
```
    See Also:
    
    Constant Field Values
  - STYLE_CURRENCY
```
private static final int STYLE_CURRENCY
```
    See Also:
    
    Constant Field Values
  - STYLE_PERCENT
```
private static final int STYLE_PERCENT
```
    See Also:
    
    Constant Field Values
  - STYLE_INTEGER
```
private static final int STYLE_INTEGER
```
    See Also:
    
    Constant Field Values
  - format
```
private java.lang.String format
```
  - locale
```
private java.util.Locale locale
```
  - configLocked
```
private boolean configLocked
```
- Constructor Detail
  - NumberTool
```
public NumberTool()
```
- Method Detail
  - configure
```
public void configure(java.util.Map params)
```
    Looks for configuration values in the given params.
    
    Since:
    
    VelocityTools 1.4
  - configure
```
protected void configure(ValueParser values)
```
    Does the actual configuration. This is protected, so subclasses may share the same ValueParser and call configure at any time, while preventing templates from doing so when configure(Map) is locked.
    
    Since:
    
    VelocityTools 1.4
  - getLocale
```
public java.util.Locale getLocale()
```
    This implementation returns the configured default locale. Subclasses may override this to return alternate locales. Please note that doing so will affect all formatting methods where no locale is specified in the parameters.
    
    Returns:
    
    the default Locale
  - setLocale
```
protected void setLocale(java.util.Locale locale)
```
    Sets the default locale for this instance. This is protected, because templates ought not to be using it; that would not be threadsafe so far as templates are concerned.
    
    Since:
    
    VelocityTools 1.4
  - getFormat
```
public java.lang.String getFormat()
```
    Return the pattern or style to be used for formatting numbers when none is specified. This implementation gives a 'default' number format. Subclasses may override this to provide a different default format.
  - setFormat
```
protected void setFormat(java.lang.String format)
```
    Sets the default format for this instance. This is protected, because templates ought not to be using it; that would not be threadsafe so far as templates are concerned.
    
    Since:
    
    VelocityTools 1.4
  - 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 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 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
```
protected java.text.NumberFormat getNumberFormat(int numberStyle,
                                                 java.util.Locale locale)
```
    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
  - getIntegerInstance
```
private java.text.NumberFormat getIntegerInstance(java.util.Locale locale)
```
    Since we wish to continue supporting Java 1.3, for the present we cannot use Java 1.4's NumberFormat.getIntegerInstance(Locale) method. This method mimics that method (at least as of JDK1.4.2_01). It is private so that it can be removed later without a deprecation period.
  - getStyleAsInt
```
protected int getStyleAsInt(java.lang.String style)
```
    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 getFormat() and the Locale returned by 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 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)

Class NumberTool

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_FORMAT

DEFAULT_FORMAT_KEY

DEFAULT_LOCALE_KEY

LOCK_CONFIG_KEY

STYLE_NUMBER

STYLE_CURRENCY

STYLE_PERCENT

STYLE_INTEGER

format

locale

configLocked

Constructor Detail

NumberTool

Method Detail

configure

configure

getLocale

setLocale

getFormat

setFormat

format

currency

integer

number

percent

format

format

getNumberFormat

getNumberFormat

getIntegerInstance

getStyleAsInt

toNumber

toNumber

toNumber