JSTL Format Library — <fmt:formatNumber> Tag

Formats a numeric value in a locale-sensitive or customized manner as a number, currency, or percentage.

Syntax 1: without a body

<fmt:formatNumber value=”numericValue
            [type=”{number|currency|percent}”]
            [pattern=” customPattern”]
            [currencyCode=” currencyCode”]
            [currencySymbol=” currencySymbol”]
            [groupingUsed=”{true|false}”]
            [maxIntegerDigits=” maxIntegerDigits”]
            [minIntegerDigits=” minIntegerDigits”]
            [maxFractionDigits=” maxFractionDigits”]
            [minFractionDigits=” minFractionDigits”]
            [var=” varName”]
            [scope=”{page|request|session|application}”]/>

Syntax 2: with a body to specify the numeric value to be formatted

<fmt:formatNumber [type=”{number|currency|percent}”]
            [pattern=” customPattern”]
            [currencyCode=” currencyCode”]
            [currencySymbol=” currencySymbol”]
            [groupingUsed=”{true|false}”]
            [maxIntegerDigits=” maxIntegerDigits”]
            [minIntegerDigits=” minIntegerDigits”]
            [maxFractionDigits=” maxFractionDigits”]
            [minFractionDigits=” minFractionDigits”]
            [var=” varName”]
            [scope=”{page|request|session|application}”]>
     numeric value to be formatted
</fmt:formatNumber>

Body Content

JSP. The JSP container processes the body content, then the action trims it and processes it further.

Attributes

value
Numeric value to be formatted.
type
Specifies whether the value is to be formatted as number, currency, or percentage.
pattern
Custom formatting pattern.
currencyCode
ISO 4217 currency code. Applied only when formatting currencies (i.e. if type is equal to "currency"); ignored otherwise.
currencySymbol
Currency symbol. Applied only when formatting currencies (i.e. if type is equal to "currency"); ignored otherwise.
groupingUsed
Specifies whether the formatted output will contain any grouping separators.
maxIntegerDigits
Maximum number of digits in the integer portion of the formatted output.
minIntegerDigits
Minimum number of digits in the integer portion of the formatted output.
maxFractionDigits
Maximum number of digits in the fractional portion of the formatted output.
minFractionDigits
Minimum number of digits in the fractional portion of the formatted output.
var
Name of the exported scoped variable which stores the formatted result as a String.
scope
Scope of var.

Constraints

Null and Error Handling

Description

The numeric value to be formatted may be specified via the value attribute; if missing, it is read from the tag’s body content.

The formatting pattern may be specified via the pattern attribute, or is looked up in a locale-dependent fashion.

A pattern string specified via the pattern attribute must follow the pattern syntax specified by the class java.text.DecimalFormat.

If looked up in a locale-dependent fashion, the formatting pattern is determined via a combination of the formatting locale, which is determined according to Section 9.2 of the JSTL specification, and the type attribute. Depending on the value of the type attribute, the given numeric value is formatted as a number, currency, or percentage. The locale's default formatting pattern for numbers, currencies, or percentages is determined by calling the java.text.NumberFormat method getNumberInstance, getCurrencyInstance , or getPercentInstance, respectively, with the formatting locale.

The pattern attribute takes precedence over type. In either case, the formatting symbols (such as decimal separator and grouping separator) are given by the formatting locale.

The (specified or locale-dependent) formatting pattern may be further fine-tuned using the formatting options described below.

If the numeric value is given as a string literal, it is first parsed into a java.lang.Number. If the string does not contain any decimal point, it is parsed using java.lang.Long.valueOf(), or java.lang.Double.valueOf() otherwise.

The formatted result is output to the current JspWriter object, unless the var attribute is given, in which case it is stored in the named scoped variable.

Formatting Options

The groupingUsed attribute specifies whether the formatted ouput will contain any grouping separators. See the java.text.NumberFormat method setGroupingUsed() for more information.

The minimum and maximum number of digits in the integer and fractional portions of the formatted output may be given via the minIntegerDigits, maxIntegerDigits, minFractionDigits, and maxFractionDigits attributes, respectively. See the java.text.NumberFormat methods setMinimumIntegerDigits(), setMaximumIntegerDigits(), setMinimumFractionDigits(), and setMaximumFractionDigits() for more information.

Formatting Currencies

When formatting currencies using the specified or locale-dependent formatting pattern for currencies, the currency symbol of the formatting locale is used by default. It can be overridden by using the currencySymbol or currencyCode attributes, which specify the currency symbol or currency code, respectively, of the currency to use.

If both currencyCode and currencySymbol are present, currencyCode takes precedence over currencySymbol if the java.util.Currency class is defined in the container’s runtime (that is, if the container’s runtime is J2SE 1.4 or greater), and currencySymbol takes precendence otherwise. If only currencyCode is given, it is used as a currency symbol if java.util.Currency is not defined.


About the JSTL Tag Library in JDeveloper
Reference: JavaServer Pages Standard Tag Library (JSTL)