org.apache.velocity.tools.generic
Class NumberTool

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('currency',$myNumber) -> $13.55
  $number.format('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>
 </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 71982 2004-02-18 20:11:07Z nbubna $

Author:

Nathan Bubna, Mike Kienenberger

Field Summary

static java.lang.String	DEFAULT_FORMAT The default format to be used when none is specified.
private static int	STYLE_CURRENCY
private static int	STYLE_INTEGER
private static int	STYLE_NUMBER
private static int	STYLE_PERCENT

Constructor Summary

NumberTool()
Default constructor.

Method Summary

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

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

Constructor Detail

NumberTool

public NumberTool()

Default constructor.

Method Detail

getLocale

public java.util.Locale getLocale()

This implementation returns the 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

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.

NOTE: At some point in the future it may be feasible to configure this value via the toolbox definition, but at present, it is not possible to specify custom tool configurations there. For now you should just override this in a subclass to have a different default.

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)

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)