javax.microedition.global
Class Formatter

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

public final class Formatter
extends Object

This implementation of the Formatter class supports only locale-neutral formatting at this time.

Since:

BlackBerry API 4.3.0

Field Summary
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	DATE_LONG Constant for the long date style.
static int	DATE_SHORT Constant for the short date 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(String locale)
Constructs a formatter for the specified locale.

Method Summary
String	formatCurrency(double number) Formats a currency amount using locale-specific rules.
String	formatCurrency(double number, String currencyCode) Formats a currency amount using the locale-specific rules but using the symbol of the specified currency.
String	formatDateTime(Calendar dateTime, int style) Formats a date/time instance using locale-specific rules.
static String	formatMessage(String template, String[] params) Formats a message with a variable number of ordered parameters.
String	formatNumber(double number) Formats a decimal number using locale-specific rules.
String	formatNumber(double number, int decimals) Formats a decimal number using locale-specific rules, with the specified number of decimals.
String	formatNumber(long number) Formats an integer using locale-specific rules.
String	formatPercentage(float value, int decimals) Formats a percentage with the specified number of decimals using locale-specific rules.
String	formatPercentage(long value) Formats an integral percentage value using locale-specific rules.
String	getLocale() Gets the locale of this formatter.
static 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

Since:

BlackBerry API 4.3.0

DATE_SHORT

public static final int DATE_SHORT

Constant for the short date style.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

DATETIME_LONG

public static final int DATETIME_LONG

Constant for the long date and time style.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

DATETIME_SHORT

public static final int DATETIME_SHORT

Constant for the short date and time style.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

TIME_LONG

public static final int TIME_LONG

Constant for the long time style.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

TIME_SHORT

public static final int TIME_SHORT

Constant for the short time style.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

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

Since:

BlackBerry API 4.3.0

Formatter

public Formatter(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 current locale is not supported by the implementation

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

Since:

BlackBerry API 4.3.0

Method Detail

formatCurrency

public 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

Since:

BlackBerry API 4.3.0

formatCurrency

public String formatCurrency(double number,
                             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:

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

NullPointerException - if currencyCode is null

Since:

BlackBerry API 4.3.0

formatDateTime

public String formatDateTime(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:

NullPointerException - if dateTime is null

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

Since:

BlackBerry API 4.3.0

formatMessage

public static String formatMessage(String template,
                                   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:

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

NullPointerException - if the template or the parameter array is null

Since:

BlackBerry API 4.3.0

formatNumber

public 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

Since:

BlackBerry API 4.3.0

formatNumber

public 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:

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

Since:

BlackBerry API 4.3.0

formatNumber

public 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

Since:

BlackBerry API 4.3.0

formatPercentage

public 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:

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

Since:

BlackBerry API 4.3.0

formatPercentage

public 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

Since:

BlackBerry API 4.3.0

getLocale

public 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

Since:

BlackBerry API 4.3.0

getSupportedLocales

public static 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

Since:

BlackBerry API 4.3.0