org.apache.velocity.tools.generic

## Class NumberTool

- 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.NumberTool

All Implemented Interfaces:
  Serializable

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

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                   -gt; 13.55
      $number.format($myNumber)   -gt; 13.6
      $number.currency($myNumber) -gt; $13.55
      $number.integer($myNumber)  -gt; 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$
Author:
  Nathan Bubna, Mike Kienenberger
See Also:
  Serialized Form

### 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, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY`

### Constructor Summary

Constructors
Constructor and Description
`NumberTool()`

### Method Summary

All Methods Instance Methods Concrete Methods
`String` `currency(Object obj)` Convenience method equivalent to $number.format("currency", $foo).
`String` `format(Object obj)` Converts the specified object to a number and formats it according to the pattern or style returned by `FormatConfig.getFormat()`.
`String` `format(String format, Object obj)` Converts the specified object to a number and returns a formatted string representing that number in the locale returned by `LocaleConfig.getLocale()`.
`String` `format(String format, Object obj, Locale locale)` Converts the specified object to a number and returns a formatted string representing that number in the specified `Locale`.
`NumberFormat` `getNumberFormat(String format, Locale locale)` Returns a `NumberFormat` instance for the specified format and `Locale`.
`String` `integer(Object obj)` Convenience method equivalent to $number.format("integer", $foo).
`String` `number(Object obj)` Convenience method equivalent to $number.format("number", $foo).
`String` `percent(Object obj)` Convenience method equivalent to $number.format("percent", $foo).
`Number` `toNumber(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.
`Number` `toNumber(String format, 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.
`Number` `toNumber(String format, Object obj, 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 org.apache.velocity.tools.generic.FormatConfig

`configure, getFormat, setFormat`

### Methods inherited from class org.apache.velocity.tools.generic.LocaleConfig

`getLocale, setLocale, toLocale`

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

`configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### NumberTool

    public NumberTool()

### Method Detail

#### format

    public String format(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 String currency(Object obj)

Convenience method equivalent to $number.format("currency", $foo).

Parameters:
  `obj` - the number object to be formatted
Returns:
  the specified number formatted as a currency
Since:
  VelocityTools 1.3

#### integer

    public String integer(Object obj)

Convenience method equivalent to $number.format("integer", $foo).

Parameters:
  `obj` - the number object to be formatted
Returns:
  the specified number formatted as an integer
Since:
  VelocityTools 1.3

#### number

    public String number(Object obj)

Convenience method equivalent to $number.format("number", $foo).

Parameters:
  `obj` - the number object to be formatted
Returns:
  the specified number formatted as a number
Since:
  VelocityTools 1.3

#### percent

    public String percent(Object obj)

Convenience method equivalent to $number.format("percent", $foo).

Parameters:
  `obj` - the number object to be formatted
Returns:
  the specified number formatted as a percentage
Since:
  VelocityTools 1.3

#### format

    public String format(String format,
                         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 String format(String format,
                         Object obj,
                         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 NumberFormat getNumberFormat(String format,
                                        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`

#### toNumber

    public Number toNumber(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 Number toNumber(String format,
                           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 Number toNumber(String format,
                           Object obj,
                           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.

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