mondrian.util
Class Format

java.lang.Object
  mondrian.util.Format

public class Format
extends Object

Format formats numbers, strings and dates according to the same specification as Visual Basic's format() function. This function is described in more detail here. We have made the following enhancements to this specification:

• if the international currency symbol (¤) occurs in a format string, it is translated to the locale's currency symbol.
• the format string "Currency" is translated to the locale's currency format string. Negative currency values appear in parentheses.
• the string "USD" (abbreviation for U.S. Dollars) may occur in a format string.

One format object can be used to format multiple values, thereby amortizing the time required to parse the format string. Example:

 double[] values;
 Format format = new Format("##,##0.###;(##,##0.###);;Nil");
 for (int i = 0; i < values.length; i++) {
   System.out.println("Value #" + i + " is " + format.format(values[i]));
 }
 

Still to be implemented:

• String formatting (upper-case, lower-case, fill from left/right)
• Use client's timezone for printing times.

Author:

jhyde

Nested Class Summary

(package private) static class	Format.AlternateFormat AlternateFormat is an implementation of Format.BasicFormat which allows a different format to be used for different kinds of values.
(package private) static class	Format.BasicFormat BasicFormat is the interface implemented by the classes which do all the work.
(package private) static class	Format.CompoundFormat CompoundFormat is an implementation of Format.BasicFormat where each value is formatted by applying a sequence of format elements.
(package private) static class	Format.DateFormat DateFormat is an element of a Format.CompoundFormat which has a value when applied to a Calendar object.
(package private) static class	Format.FallbackFormat FallbackFormat catches un-handled datatypes and prints the original format string.
(package private) static class	Format.FDBigInt
(package private) static class	Format.FloatingDecimal Copied from java.lang.FloatingDecimal.
static class	Format.FormatLocale A FormatLocale contains all information necessary to format objects based upon the locale of the end-user.
(package private) static class	Format.JavaFormat JavaFormat is an implementation of Format.BasicFormat which prints values using Java's default formatting for their type.
(package private) static class	Format.LiteralFormat LiteralFormat is an implementation of Format.BasicFormat which prints a constant value, regardless of the value to be formatted.
static interface	Format.LocaleFormatFactory Locates a Format.FormatLocale for a given locale.
(package private) static class	Format.MacroToken
(package private) static class	Format.NumericFormat NumericFormat is an implementation of Format.BasicFormat which prints numbers with a given number of decimal places, leading zeroes, in exponential notation, etc.
(package private) static class	Format.Token

Field Summary

static int	CacheLimit Maximum number of entries in the format cache used by get(String, java.util.Locale).
(package private) static String	currencyFormat_en
(package private) static String	currencySymbol_en
(package private) static String	dateSeparator_en
(package private) static String[]	daysOfWeekLong_en
(package private) static String[]	daysOfWeekShort_en
(package private) static char	decimalPlaceholder_en
(package private) static char[]	digits
(package private) static char	intlCurrencySymbol
(package private) static int	LEFT_OF_POINT
(package private) static Format.FormatLocale	locale_US Locale for US English, also the default for English and for all locales.
(package private) static String[]	monthsLong_en
(package private) static String[]	monthsShort_en
(package private) static int	NOT_IN_A_NUMBER
(package private) static int	RIGHT_OF_EXP
(package private) static int	RIGHT_OF_POINT
(package private) static char	thousandSeparator_en
(package private) static String	timeSeparator_en
(package private) static Format.Token[]	tokens

Constructor Summary

Format(String formatString, Format.FormatLocale locale)
Constructs a Format in a specific locale.

Format(String formatString, Locale locale)
Constructs a Format in a specific locale.

Method Summary

static Format.FormatLocale	createLocale(char thousandSeparator, char decimalPlaceholder, String dateSeparator, String timeSeparator, String currencySymbol, String currencyFormat, String[] daysOfWeekShort, String[] daysOfWeekLong, String[] monthsShort, String[] monthsLong, Locale locale) Create a Format.FormatLocale object characterized by the given properties.
static Format.FormatLocale	createLocale(Locale locale)
String	format(Object o)
(package private) static String	format(Object o, String formatString, Locale locale) Formats an object using a format string, according to a given locale.
static Format	get(String formatString, Locale locale) Constructs a Format in a specific locale, or retrieves one from the cache if one already exists.
static Format.FormatLocale	getBestFormatLocale(Locale locale) Returns the best Format.FormatLocale for a given Locale.
static Format.FormatLocale	getFormatLocale(Locale locale) Returns the Format.FormatLocale which precisely matches Locale, if any, or null if there is none.
String	getFormatString()
static List<Format.Token>	getTokenList()
static Format.FormatLocale	registerFormatLocale(Format.FormatLocale formatLocale, Locale locale) Registers a Format.FormatLocale to a given Locale.

Methods inherited from class java.lang.Object

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

Field Detail

CacheLimit

public static final int CacheLimit

Maximum number of entries in the format cache used by get(String, java.util.Locale).

See Also:

Constant Field Values

digits

static final char[] digits

thousandSeparator_en

static final char thousandSeparator_en

See Also:

Constant Field Values

decimalPlaceholder_en

static final char decimalPlaceholder_en

See Also:

Constant Field Values

dateSeparator_en

static final String dateSeparator_en

See Also:

Constant Field Values

timeSeparator_en

static final String timeSeparator_en

See Also:

Constant Field Values

currencySymbol_en

static final String currencySymbol_en

See Also:

Constant Field Values

currencyFormat_en

static final String currencyFormat_en

See Also:

Constant Field Values

daysOfWeekShort_en

static final String[] daysOfWeekShort_en

daysOfWeekLong_en

static final String[] daysOfWeekLong_en

monthsShort_en

static final String[] monthsShort_en

monthsLong_en

static final String[] monthsLong_en

intlCurrencySymbol

static final char intlCurrencySymbol

See Also:

Constant Field Values

locale_US

static final Format.FormatLocale locale_US

Locale for US English, also the default for English and for all locales.

tokens

static final Format.Token[] tokens

NOT_IN_A_NUMBER

static final int NOT_IN_A_NUMBER

See Also:

Constant Field Values

LEFT_OF_POINT

static final int LEFT_OF_POINT

See Also:

Constant Field Values

RIGHT_OF_POINT

static final int RIGHT_OF_POINT

See Also:

Constant Field Values

RIGHT_OF_EXP

static final int RIGHT_OF_EXP

See Also:

Constant Field Values

Constructor Detail

Format

public Format(String formatString,
              Locale locale)

Constructs a Format in a specific locale.

Parameters:

formatString - the format string; see this description for more details

locale - The locale

Format

public Format(String formatString,
              Format.FormatLocale locale)

Constructs a Format in a specific locale.

See Also:

Format.FormatLocale, createLocale(char, char, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String[], java.lang.String[], java.lang.String[], java.lang.String[], java.util.Locale)

Method Detail

format

static String format(Object o,
                     String formatString,
                     Locale locale)

Formats an object using a format string, according to a given locale.

If you need to format many objects using the same format string, create a formatter object using Format(String, java.util.Locale).

getTokenList

public static final List<Format.Token> getTokenList()

get

public static Format get(String formatString,
                         Locale locale)

Constructs a Format in a specific locale, or retrieves one from the cache if one already exists.

If the number of entries in the cache exceeds CacheLimit, replaces the eldest entry in the cache.

Parameters:

formatString - the format string; see this description for more details

createLocale

public static Format.FormatLocale createLocale(char thousandSeparator,
                                               char decimalPlaceholder,
                                               String dateSeparator,
                                               String timeSeparator,
                                               String currencySymbol,
                                               String currencyFormat,
                                               String[] daysOfWeekShort,
                                               String[] daysOfWeekLong,
                                               String[] monthsShort,
                                               String[] monthsLong,
                                               Locale locale)

Create a Format.FormatLocale object characterized by the given properties.

Parameters:

thousandSeparator - the character used to separate thousands in numbers, or ',' by default. For example, 12345 is '12,345 in English, '12.345 in French.

decimalPlaceholder - the character placed between the integer and the fractional part of decimal numbers, or '.' by default. For example, 12.34 is '12.34' in English, '12,34' in French.

dateSeparator - the character placed between the year, month and day of a date such as '12/07/2001', or '/' by default.

timeSeparator - the character placed between the hour, minute and second value of a time such as '1:23:45 AM', or ':' by default.

daysOfWeekShort - Short forms of the days of the week. The array is 1-based, because position Calendar.SUNDAY (= 1) must hold Sunday, etc. The array must have 8 elements. For example {"", "Sun", "Mon", ..., "Sat"}.

daysOfWeekLong - Long forms of the days of the week. The array is 1-based, because position Calendar.SUNDAY must hold Sunday, etc. The array must have 8 elements. For example {"", "Sunday", ..., "Saturday"}.

monthsShort - Short forms of the months of the year. The array is 0-based, because position Calendar.JANUARY (= 0) holds January, etc. For example {"Jan", ..., "Dec", ""}.

monthsLong - Long forms of the months of the year. The array is 0-based, because position Calendar.JANUARY (= 0) holds January, etc. For example {"January", ..., "December", ""}.

locale - if this is not null, register that the constructed FormatLocale is the default for locale

createLocale

public static Format.FormatLocale createLocale(Locale locale)

getFormatLocale

public static Format.FormatLocale getFormatLocale(Locale locale)

Returns the Format.FormatLocale which precisely matches Locale, if any, or null if there is none.

getBestFormatLocale

public static Format.FormatLocale getBestFormatLocale(Locale locale)

Returns the best Format.FormatLocale for a given Locale. Never returns null, even if locale is null.

registerFormatLocale

public static Format.FormatLocale registerFormatLocale(Format.FormatLocale formatLocale,
                                                       Locale locale)

Registers a Format.FormatLocale to a given Locale. Returns the previous mapping.

format

public String format(Object o)

getFormatString

public String getFormatString()