Contents | Prev | Next

Formatted Output and Parsing

It is in formatting data for output that many cultural conventions are applied. Java provides a set of flexible formatting classes that can handle both the standard locale formats and programmer defined custom formats. These formatting classes are also able to parse formatted strings back into their constituent objects.

The class Format is an abstract base class that encapsulates locale-sensitive formatting and parsing. Three main subclasses are provided: NumberFormat, DateFormat and MessageFormat. These three also provide subclasses of their own.

Note - JDK 1.0 provided the Object.toString() method, which provided very simple formatting for all Java objects. This method remains in JDK 1.1. It does not, however, handle formatting in a locale-sensitive way. Its use should be limited to producing strings which are not user visible.

Formatting Numbers

The class NumberFormat is an abstract base class for formatting and parsing numeric data. It contains a number of static factory methods for getting different kinds of locale-specific number formats. The following example shows how a currency format could be obtained and used for the German locale:

NumberFormat currencyFmt 

	= NumberFormat.getDefaultCurrency( Locale.GERMANY );

System.out.println("My salary: " + currencyFmt( 24.63 ));

Similar factory methods are provided for obtaining a locale's general purpose number format and its percent number format.

The class DecimalFormat is a concrete subclass of NumberFormat that can format decimal numbers such as are used in Western, Arabic or Indic languages. Programmers generally would not instantiate this class directly but would use the factory methods described above.

DecimalFormat has the ability to take a pattern string to specify how a number should be formatted. The pattern specifies things like the precision of the number, whether leading zeros should be printed, what currency symbols are used, etc. The pattern string can be altered if a program needs to create a custom format.

Formatting Times

The class DateFormat is an abstract base class for formatting and parsing time values. It has a number of static factory methods for getting standard time formats for a given locale. The standard formats include date only, time only, date plus time and default format.

DateFormat uses a Calendar and TimeZone object in order to interpret time values. By default, a DateFormat for a given locale will use the appropriate Calendar for that locale and the system's default TimeZone. The programmer can override these choices if desired.

The class SimpleDateFormat is a concrete subclass of DateFormat. SimpleDateFormat includes the ability to customize the time format using a pattern string. Here is an example that customizes the US locale's time format to look like "08:15 am."

DateFormat fmt

	 = DateFormat.getDateFormat( DateFormat.DEFAULT, Locale.USA );

fmt.setPattern("hh:mm a",false);

System.out.println( fmt.format(System.currentTimeMillis()) );

A complete description of pattern strings can be found in the JavaDoc for SimpleDateFormat.

Formatting Messages

Programs often need to build messages from sequences of strings, numbers and other data. To produce messages like "The disk `MyDisk' contains 3 files.", a naive program might do the following:

int numFiles = 3;

String diskName = "MyDisk";

String message = "The disk `" + diskName

					 + "` contains " + numFiles + " files.";

The above code, while easy to understand, is extremely hard to localize because it hard-codes both the strings that make up the message and the order in which they are put together. Note, for example, that a French translation of the message, "Il y a 3 fichiers sur le disque 'MyDisk'.", reverses the parameters.

The class MessageFormat provides a way to build messages in a language-neutral way. It is constructed from a pattern string. The pattern string describes the structure of the message and the substitution order for the parameters. Using a MessageFormat, the above example would look like this:

Object[] arguments = new Object[2];

arguments[0] = 3;

arguments[1] = "MyDisk";

StringBuffer message = new StringBuffer();



MessageFormat fmt

	= new MessageFormat("The disk `%0' contains %1 files.");

fmt.format(arguments, message, null);



fmt.setPattern("Il y a %1 fichiers sur le disque `%0'");

fmt.format(arguments, message, null);

The Format method formats the given arguments then substitutes the result into the pattern string to form the final message. There are several ways the MessageFormat tries to format the given arguments. An array of Format objects can be passed to the MessageFormat. If this is present, parameter n will be formatted using the nth entry of the format array. If an explicit Format has not been given for a parameter, then a default Format will be obtained. If the parameter to be formatted is a Number then NumberFormat.getDefault() is called. Otherwise, the parameter's toString() method is called.

An additional type of Format called a ChoiceFormat is available for use in formatting the parameters of a message. A ChoiceFormat allows text to be associated with a number or range of numbers. See the JavaDoc description of java.util.ChoiceFormat for details.

Contents | Prev | Next

java-intl@java.sun.com