javax.microedition.global
Class Formatter

java.lang.Object
  javax.microedition.global.Formatter

public final class Formatter

extends java.lang.Object

Creates locale-specific renditions of data items. The following data items are handled:

• dates
• times
• numbers
• percentages
• currency amounts

It is also possible to construct messages that have ordered parameters.

Formatting methods MUST NOT return null. If a formatting method cannot perform the requested formatting, the return value SHOULD be the empty string. This allows applications to check if the formatting succeeded by examining the length of the return string.

Selected locale

The locale used by the formatter determines the formatting rules. The selected locale is either the value of the microedition.locale system property or the locale passed as a string parameter to the constructor.

If the selected locale is null or the empty string, formatting is locale-neutral (see below). If the selected locale is non-null and non-empty, but the formatter implementation does not support it, the constructors throw an UnsupportedLocaleException.

If the selected locale is supported, the formatting is performed according to the rules of the locale. These rules are implementation-dependent and are not exposed to application programmers.

To find out which locales are supported by the formatter implementation, call the getSupportedLocales() method.

Formatter MUST NOT perform hierarchical matching, since typically there are enough differences between locales that formatting rules cannot be reused. However, the implementation MAY internally map one locale to another one. Typically this would involve cases where there are several different variants for the same locale, such as de-DE-operator1 and de-DE-operator2.

Date and time formatting styles

This class defines a number of constants that determine the extent and style of the result when the formatDateTime method is called. The following styles are currently defined:

• short date only
• long date only
• short time only
• long time only
• short date and time
• long date and time

Mixed combinations (i.e. short date with long time and vice versa) are not supported. If both date and time components are present, their mutual order depends on the locale and is implementation-dependent.

Due to the limited amount of screen real estate available in many mobile devices, the results of date and time formatters SHOULD be compact, using numeric values whenever appropriate. However, an implementation MAY use textual elements for names of weekdays and months if appropriate.

Number and currency formatting

For floating point numbers, the descriptions of the formatting results in the method documentation concern situations where the number is normal. If the number to be formatted is negative infinity, positive infinity, or NaN, any separators, decimals or currency symbols which would normally appear MUST NOT be present in the result. The symbols used for negative and positive infinity and NaN are implementation-specific. Implementations MAY use the appropriate Unicode character (U+221F INFINITY) if applicable.

Currency formatting MUST NOT perform any currency conversions based on exchange rates. Unless specified otherwise, the amount being formatted is assumed to be in the currency associated with the locale. If a different currency is desired, it can be selected by passing an ISO 4217 currency code (see References).

Locale-neutral formatting

In locale-neutral formatting dates and times MUST conform to the Internet date/time profile for the ISO 8601 standard as defined in RFC 3339. Numbers and currencies MUST be formatted using Long.toString or Double.toString, and currency amounts MUST NOT have a currency symbol unless explicitly specified. In percentage formatting the Unicode character U+0025 PERCENT SIGN MUST be appended to the formatted number.

Locale-neutral formatting is provided because the MIDP specification allows the microedition.locale system property to be null. In such cases constructing a formatter without specifying a locale will use the locale-neutral values to avoid an exceptional condition. (Normally that would construct a formatter for the system default locale.) The application can also explicitly request locale-neutral behaviour by passing null as the locale.

References

ISO 4217:2001, Codes for the representation of currencies and funds. International Organization for Standardization, 2001.

Graham Klyne and Chris Newman, Date and Time on the Internet: Timestamps, RFC 3339. Available at http://www.ietf.org/rfc/rfc3339.txt.

Field Summary

static int	DATE_LONG Constant for the long date style.
static int	DATE_SHORT Constant for the short date style.
static int	DATETIME_LONG Constant for the long date and time style.
static int	DATETIME_SHORT Constant for the short date and time style.
static int	TIME_LONG Constant for the long time style.
static int	TIME_SHORT Constant for the short time style.

Constructor Summary

Formatter()
Constructs a formatter based on the current locale, which is the value of the microedition.locale system property.

Formatter(java.lang.String locale)
Constructs a formatter for the specified locale.

Method Summary

java.lang.String	formatCurrency(double number) Formats a currency amount using locale-specific rules.
java.lang.String	formatCurrency(double number, java.lang.String currencyCode) Formats a currency amount using the locale-specific rules but using the symbol of the specified currency.
java.lang.String	formatDateTime(java.util.Calendar dateTime, int style) Formats a date/time instance using locale-specific rules.
static java.lang.String	formatMessage(java.lang.String template, java.lang.String[] params) Formats a message with a variable number of ordered parameters.
java.lang.String	formatNumber(double number) Formats a decimal number using locale-specific rules.
java.lang.String	formatNumber(double number, int decimals) Formats a decimal number using locale-specific rules, with the specified number of decimals.
java.lang.String	formatNumber(long number) Formats an integer using locale-specific rules.
java.lang.String	formatPercentage(float value, int decimals) Formats a percentage with the specified number of decimals using locale-specific rules.
java.lang.String	formatPercentage(long value) Formats an integral percentage value using locale-specific rules.
java.lang.String	getLocale() Gets the locale of this formatter.
static java.lang.String[]	getSupportedLocales() Gets the list of the locales supported by the formatter, as an array of valid microedition.locale values.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DATE_LONG

public static final int DATE_LONG

Constant for the long date style.

See Also:

Constant Field Values

DATE_SHORT

public static final int DATE_SHORT

Constant for the short date style.

See Also:

Constant Field Values

DATETIME_LONG

public static final int DATETIME_LONG

Constant for the long date and time style.

See Also:

Constant Field Values

DATETIME_SHORT

public static final int DATETIME_SHORT

Constant for the short date and time style.

See Also:

Constant Field Values

TIME_LONG

public static final int TIME_LONG

Constant for the long time style.

See Also:

Constant Field Values

TIME_SHORT

public static final int TIME_SHORT

Constant for the short time style.

See Also:

Constant Field Values

Constructor Detail

Formatter

public Formatter()

Constructs a formatter based on the current locale, which is the value of the microedition.locale system property.

If the system property value is null, locale neutral formatting rules are used. If the implementation does not support the current locale, an UnsupportedLocaleException is thrown.

Throws:

UnsupportedLocaleException - if the current locale is not supported by the implementation

Formatter

public Formatter(java.lang.String locale)

Constructs a formatter for the specified locale.

If the specified locale is null, locale neutral formatting rules are used. If the implementation does not support the specified locale, an UnsupportedLocaleException is thrown.

Parameters:

locale - the locale identifier (null to get locale-neutral behaviour)

Throws:

UnsupportedLocaleException - if the specified locale is not supported by the implementation

java.lang.IllegalArgumentException - if the specified locale is not valid according to the MIDP 2.0 specification

Method Detail

formatCurrency

public java.lang.String formatCurrency(double number)

Formats a currency amount using locale-specific rules. This method assumes that the amount is in the locale's currency. The result uses the locale-specific decimal separator and may include grouping separators. The number of decimals is also locale-specific.

This method MUST NOT perform any currency conversions based on exchange rates.

Parameters:

number - the currency amount to format

Returns:

the formatted currency amount

formatCurrency

public java.lang.String formatCurrency(double number,
                                       java.lang.String currencyCode)

Formats a currency amount using the locale-specific rules but using the symbol of the specified currency. The currency is specified using its ISO 4217 three-letter code, such as "USD", "EUR" or "GBP". If there is a currency symbol attached to the ISO 4217 code in the implementation, that symbol MUST be used instead of the locale's currency symbol. If the implementation does not provide a currency symbol for a given ISO 4217 code, the code MUST be used as such.

The result MAY include a locale-specific decimal separator and grouping separators. The number of decimals is also locale-specific.

This method MUST NOT perform any currency conversions based on exchange rates.

Parameters:

number - the currency amount to format

currencyCode - the ISO 4217 currency code to use

Returns:

the formatted currency amount

Throws:

java.lang.IllegalArgumentException - if currencyCode is not a syntactically valid ISO 4217 code (three uppercase Latin letters)

java.lang.NullPointerException - if currencyCode is null

See Also:

formatCurrency(double)

formatDateTime

public java.lang.String formatDateTime(java.util.Calendar dateTime,
                                       int style)

Formats a date/time instance using locale-specific rules. The style parameter determines the extent and style of the result.

Parameters:

dateTime - the date and time to format

style - the formatting style to use

Returns:

the date and/or time formatted as a string

Throws:

java.lang.NullPointerException - if dateTime is null

java.lang.IllegalArgumentException - if style is not one of those defined in this class

See Also:

DATE_SHORT, DATE_LONG, TIME_SHORT, TIME_LONG, DATETIME_SHORT, DATETIME_LONG, Calendar, TimeZone

formatMessage

public static java.lang.String formatMessage(java.lang.String template,
                                             java.lang.String[] params)

Formats a message with a variable number of ordered parameters. The template argument is a string that may contain placeholders for the parameters. The placeholders are of the form {n} or {nn} where n is a digit 0...9. This allows parameters numbered from 0 to 99. Leading zeros in parameter numbers below 10 are accepted. If there is only one parameter, it is specified as {0} (or {00}). The placeholders MAY occur in arbitrary order, and they determine the final order of the actual parameters in the result string. Not all parameters have to be used in the template, but any parameter MAY occur an arbitrary number of times.

The parameters are passed as an array of strings. This method does not actually format dates, times, and other data; the items must be already formatted and the strings placed in the parameter array. This method then performs a simple string substitution.

If you need to include the { character in the template, it MUST be escaped using {{, so that it is not mistaken for the initial delimiter of a placeholder.

The length of the params array determines the upper bound of the {nn} parameters in the template. If the template contains references to parameter numbers higher than params.length - 1, this method throws an IllegalArgumentException.

Parameters:

template - the string template

params - the parameter strings to insert

Returns:

the formatted message

Throws:

java.lang.IllegalArgumentException - if the template refers to parameter numbers larger than params.length - 1

java.lang.NullPointerException - if the template or the parameter array is null

formatNumber

public java.lang.String formatNumber(double number)

Formats a decimal number using locale-specific rules. The result MAY include a locale-specific decimal separator and grouping separators.

Parameters:

number - the number to format

Returns:

the formatted decimal number

formatNumber

public java.lang.String formatNumber(double number,
                                     int decimals)

Formats a decimal number using locale-specific rules, with the specified number of decimals. The result MAY include a locale-specific decimal separator and grouping separators.

The number of decimals MUST be between 1 and 15. The formatted result MUST have exactly the specified number of decimals, even if some of the trailing digits are zeroes.

Parameters:

number - the number to format

decimals - the number of decimals to use (1 <= decimals <= 15)

Returns:

the formatted decimal number

Throws:

java.lang.IllegalArgumentException - if the number of decimals is not between 1 and 15, inclusive

See Also:

formatNumber(double)

formatNumber

public java.lang.String formatNumber(long number)

Formats an integer using locale-specific rules. The result MAY include grouping separators.

Parameters:

number - the number to format

Returns:

the formatted number

formatPercentage

public java.lang.String formatPercentage(float value,
                                         int decimals)

Formats a percentage with the specified number of decimals using locale-specific rules. This method places the locale-specific percent sign at the correct position in relation to the number, with the appropriate amount of space (possibly none) between the sign and the number.

A percentage is expressed as a decimal number, with the value 0.0 interpreted as 0% and the value 1.0 as 100%. Percentages larger than 100% are expressed as values greater than 1.0. Negative percentages are allowed, and expressed as values smaller than 0.0. The percentage is rounded to the specified number of decimals.

The number of decimals MUST be between 1 and 15. The formatted result MUST have exactly the specified number of decimals, even if some of the trailing digits are zeroes.

Parameters:

value - the percentage to format, expressed as a positive or negative number

decimals - the number of decimals to use (1 <= decimals <= 15)

Returns:

the formatted percentage string

Throws:

java.lang.IllegalArgumentException - if the number of decimals is not between 1 and 15, inclusive

formatPercentage

public java.lang.String formatPercentage(long value)

Formats an integral percentage value using locale-specific rules. This method places the locale-specific percent sign at the correct position in relation to the number, with the appropriate number of space (possibly none) between the sign and the number.

A percentage is expressed as an integer value. Negative percentages are allowed.

Parameters:

value - the percentage to format

Returns:

the formatted percentage string

See Also:

formatNumber(long)

getLocale

public java.lang.String getLocale()

Gets the locale of this formatter. The return value is null if this formatter is using locale-neutral formatting.

Returns:

the locale, or null if using locale-neutral formatting

getSupportedLocales

public static java.lang.String[] getSupportedLocales()

Gets the list of the locales supported by the formatter, as an array of valid microedition.locale values.

If no locales are supported, the list MUST be empty. It MUST NOT be null. As the value null is not technically a valid locale, but a special value to trigger locale-neutral formatting, it MUST NOT appear in the array.

Returns:

an array of strings containing the locale values