javax.microedition.global
Class Formatter

java.lang.Object
  extended by 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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.