setPercentageFormat

Creates a format that can be used with Percentage values.

Attributes

name

Required

Value type

EL-evaluated

No

String

Yes

Defines a name for the created format. If defined, other commands can choose to use this format by referring to it by this name.

Leaving the created format nameless declares it as the default format for Percentage values. Any command that prints out a Percentage value will then use this format, unless the command specifies a named format for itself. If a default format for Percentage values has already been set, this new format will take its place as the default.

locale

Required

Value type

EL-evaluated

No

String

Yes

Specifies a locale for this format, affecting the formatting rules. The resolved String should be an ISO-639 language code and an ISO-3166 country code, joined by a hyphen or an underscore (e.g. "en-US" or "en_US"). Alternatively the value may only specify the language code, but this may lead to unpredictable results if this format requires the country information.

If not defined, the format will follow the user's default locale.

pattern

Required

Value type

EL-evaluated

No

String

Yes

The value of this attribute is used as the pattern defining what kind of Strings this format will produce.

If not defined, a locale-dependent standard pattern will be used.

decimalSeparator

Required

Value type

EL-evaluated

No

String

Yes

Defines the decimal separator for this format.

If not defined, a locale-dependent decimal separator is used.

groupingSeparator

Required

Value type

EL-evaluated

No

String

Yes

Defines the grouping separator for the format.

If not defined, a locale-dependent default grouping separator is used.

roundingMode

Required

Value type

EL-evaluated

No

String

Yes

Defines the rounding mode for the format. The possible values are the following:

HALF_UP
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. Behaves as for UP if the discarded fraction is >= 0.5; otherwise, behaves as for DOWN. Note that this is the rounding mode commonly taught at school.
HALF_DOWN
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. Behaves as for UP if the discarded fraction is > 0.5; otherwise, behaves as for DOWN.
HALF_EVEN
Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor. Behaves as for HALF_UP if the digit to the left of the discarded fraction is odd; behaves as for HALF_DOWN if it's even. Note that this is the rounding mode that statistically minimizes cumulative error when applied repeatedly over a sequence of calculations. It is sometimes known as "Banker's rounding," and is chiefly used in the USA.
UP
Rounding mode to round away from zero. Always increments the digit prior to a non-zero discarded fraction. Note that this rounding mode never decreases the magnitude of the calculated value.
DOWN
Rounding mode to round towards zero. Never increments the digit prior to a discarded fraction (i.e., truncates). Note that this rounding mode never increases the magnitude of the calculated value.
CEILING
Rounding mode to round towards positive infinity. If the result is positive, behaves as for UP; if negative, behaves as for DOWN. Note that this rounding mode never decreases the calculated value.
FLOOR
Rounding mode to round towards negative infinity. If the result is positive, behave as for DOWN; if negative, behave as for RoundingMode.UP. Note that this rounding mode never increases the calculated value.

If not defined, the HALF_EVEN mode is used.

Examples

A typical Percentage format with two decimals and the % character following the value:

CODE

<setPercentageFormat pattern="###.00'%'">

Define the decimalSeparator attribute to set whether the separator is a comma or a dot, or something entirely different (it can be set to any String, after all). Otherwise a value could appear as "90,7" or "90.7" depending on the user's locale.