Formatter


Formatter java.util

Java 5.0 closeable flushable

The Formatter class is a utility for formatting text in the style of the printf( ) method of the C programming language. Every Formatter has an associated java.lang.Appendable object (such as a StringBuilder or PrintWriter ) that is specified when the Formatter is created. format( ) is a varargs method that expects a "format string" argument followed by some number of Object arguments. The format string uses a grammar, described in detail later in the entry, to specify how the arguments that follow are to be converted to strings. After the arguments are converted, they are substituted into the format string, and the resulting text is appended to the Appendable . A variant of the format( ) method accepts a Locale object that can affect the argument conversions.

For ease of use, a Formatter never throws a java.io.IOException , even when the underlying Appendable tHRows one. When using a Formatter with a stream-based Appendable object that may throw an IOException , you can use the ioException( ) method to obtain the most recently thrown exception, or null if no exception has been thrown by the Appendable .

Formatter implements the Closeable and Flushable interfaces of the java.io package, and its close( ) and flush( ) methods call the corresponding methods on its Appendable object, if that object itself implements Closeable or Flushable . When a Formatter sends its output to a stream or similar Appendable , remember to call close( ) when you are done with it. It is always safe to call close( ) even if the underlying Appendable is not Closeable . Note that once a Formatter has been closed, no other method except ioException( ) may be called.

locale( ) returns the Locale passed to the Formatter( ) constructor or null . out( ) returns the Appendable that this Formatter sends its output to. toString( ) returns the result of calling toString( ) on that Appendable . This is useful when the Appendable is a StringBuilder , for example, as it is when the no-argument version of the Formatter( ) constructor is used. If the Appendable is a stream class, however, the toString( ) method is not typically useful.

Note that the Java 5.0 API provides a number of convenience methods that use the Formatter class, and in many cases it is unnecessary to create a Formatter object explicitly. See the static String.format( ) method and the format( ) and printf( ) methods of java.io.PrintWriter and java.io.PrintStream .

If you do need to create a Formatter object explicitly, you can choose from a number of constructors. The most general case is to pass the desired Appendable or the desired Locale and Appendable objects to the constructor. The no-argument constructor is a convenience that creates a StringBuilder to append to. Obtain this StringBuilder with out( ) or obtain its contents as a String with toString( ) . If you specify a single Locale argument, the resulting Formatter uses the specified locale with a StringBuilder .

You can use a Formatter to write formatted output to a file by specifying either the File object or filename as a String . Variants of these constructors allow you to specify the name of the charset to use for character-to-byte conversion and also a Locale . Note that these methods overwrite existing files rather than appending to them. Other constructors create an Appendable object for you based on the java.io.OutputStream or java.io.PrintStream you specify. In the OutputStream case, you may optionally specify the charset to use or the charset and a Locale .

The Format String and Format Specifiers

The API for Formatter and Formatter -based convenience methods is relatively simple. The power of these formatting methods lies in the format string that is the first argument (or second argument if a Locale is specified) to the various format( ) and printf( ) methods. The format string may contain any amount of regular text, which is printed or appended literally to the destination Appendable object. This plain text may be interspersed with format specifiers which specify how a subsequent argument is to be formatted as a string. In contrast to the simple API, the grammar for these format specifiers is surprisingly complex. Experienced C programmers will find that the grammar is largely compatible with the printf( ) format string grammar of the standard C library.

Each format specifier begins with a percent sign and ends with a one- or two-character conversion type that specifies most of the details of the conversion and formatting. In between these two are optional flags that provide additional details about how the formatting should be done. The general syntax of a format specifier is as follows . Square brackets indicate optional items:

 %[   argument   ][   flags   ][   width   ][.   precision   ]   type   

Note that the percent sign and the type are the only two required portions of a format specifier. We begin, therefore, with a listing of conversion types (see Table 16-1). A discussion of argument , flags , width , and precision follows. In the table of conversion types below, if uppercase and lowercase variants of the type specifier are listed together, the uppercase variant produces the same output as the lowercase variant except that all lowercase letters are converted to uppercase. Note that format( ) never throws NullPointerException because of null arguments following the format string. A null argument is formatted as "null" or "NULL" for all conversion characters except %b and %B , which produce "false" or "FALSE".

Table 16-1. Formatter conversion types

Conversion

Description

Simple conversions

%%

Outputs a single percent sign.This is simply an escape sequence used to embed percent signs literally in the output string. This conversion does not use an argument.

%n

Outputs the platform-specific line separator. This conversion represents the value returned by System.getProperty("line.separator") . This conversion does not use an argument.

%s, %S

Formats and outputs the argument as a string, optionally converting it to uppercase for the %S conversion. The argument may be of any type. If the argument implements Formattable , its formatTo( ) method is called to perform the formatting. Otherwise, its toString( ) method is called to convert it to a string. If the argument is null , the output string is "null" or "NULL".

%c, %C

Outputs the argument as a single character. The argument type must be Byte , Short , Character , or Integer . The argument value must represent a valid Unicode code point. (See Character.isValidCodePoint( ) .)

%b, %B

Outputs the argument value as the string "true" or "false" (or "TRUE" or "FALSE"). The argument may be of any type and any value. If it is a Boolean argument, the output reflects the argument value. Otherwise, if the argument is null , the output is "false" or "FALSE". For any other value, the output is "true" or "TRUE". Note that this differs from normal Java conversions in which boolean values are not convertible to or from any other type.

%h, %H

Outputs the hexadecimal representation of the hashcode for the argument. Arguments of any type and value are allowed. This conversion type is useful mainly for debugging.

Numeric Conversions

%d

Formats the argument as a base-10 integer. The argument must be a Byte , Short , Integer , Long , or BigInteger .

%o

Formats the argument as a base-8 octal integer. The allowed argument types are the same as for %d . For any argument type other than BigInteger , the value is treated as unsigned.

%x, %X

Formats the argument as a base-16 hexadecimal integer. The allowed argument types and values are the same as for %d . For any argument type other than BigInteger , the value is treated as unsigned.

%e, %E

Formats the argument as a base-10 floating-point number, using exponential notation. The output consists of a single digit, a locale-specific decimal point, and the number of fractional digits specified by the precision of the format specifier, or six fractional digits if no precision is specified. These digits are followed by the letter e or E and the exponent of the number.

The argument must be a Float , Double , or BigDecimal . The values NaN and Infinity are formatted as "NaN" and "Infinity" or their uppercase equivalents.

%f

Formats the argument as a floating-point number in base-10, without using exponential notation. If the number is large, this may produce quite a few digits. Because exponential notation is never used, the output will never include a letter, and there is no uppercase variant of this conversion. Legal argument types and special-case values are as for %e .

%g, %G

Formats the argument as a base-10 floating-point number, displaying no more than the number of significant digits specified by the precision of the format specifier, or no more than 6 significant digits if no precision is specified. If the value has more than the allowed number of significant digits, it is printed using exponential notation (see %e ) to limit the display to the specified number of digits. Otherwise, all digits of the value are printed explicitly as they would be with the %f conversion type. Legal argument types and special case values are as for %e .

%a, %A

Formats the argument in hexadecimal floating-point format. Legal argument types and special case values are as for %e .

Dates and Times

%t, %T

All date and time format types are two-letter codes beginning with %t or %T . The specific format types are listed below, in alphabetical order, using %t as the prefix. For uppercase, use %T instead. Upper- and lowercase variants of the second letter of a time or date format type are sometimes completely unrelated. Other times, the lowercase conversion produces an abbreviation of the value produced by the uppercase conversion.

The argument for a date or time conversion must be a Date , Calendar , or Long . In the case of Long , the value is interpreted as milliseconds since the epoch , as in System currentTimeMillis( ) .

%tA

The locale-specific full name of the day of the week.

%ta

The locale-specific abbreviation of the day of the week.

%tB

The locale-specific name of the month. See %tm .

%tb

The locale-specific abbreviation for the month.

%tC

The century: the year divided by 100, with leading zeros if necessary to produce a value from 00 to 99

%tc

The complete date and time. Equivalent to "%ta %tb %td %tT %tZ %tY".

%td

The date in a short numeric form used in the US locale. Equivalent to "%tm/%td/%ty".

%td

The day of the month, as a two-digit number between 01 and 31. See %te .

%tE

The date expressed as milliseconds since Midnight UTC on January 1st, 1970.

%te

The day of the month as a one- or two-digit number without leading zeros between 1 and 31. See %td .

%tF

The numeric date in ISO8601 format: %tY-%tm-%td.

%tH

Hour of the day using a 24- hour clock, formatted as two digits between 00 and 23. See %tI .

%th

The abbreviated month name. Same as %tb .

%tI

Hour of the day using a 12-hour clock, formatted as two digits between 01 and 12. See %tH and %tP .

%tj

The day of the year as three digits with leading zeros if necessary: 001-366

%tk

Hour of the day on a 24-hour clock using one or two digits without a leading zero: 0-23. See %tl .

%tL

Milliseconds within the second, expressed as three digits with leading zeros: 000-999.

%tl

Hour of the day on a 12-hour clock using one or two digits without a leading zero: 1-12.

%tM

Minute within the hour as two digits with a leading zero if necessary: 00-59.

%tm

The month of the year as a two-digit number between 01 and 12, or between 01 and 13 for lunar calendars. See %tB and %tb .

%tN

Nanosecond within the second, expressed as nine digits with leading zeros if necessary. Note that platforms are not required to able to resolve times with nanosecond precision.

%tP

The locale-specific morning or afternoon indicator (such as "am" or "pm") used with 12-hour clocks. %tP uses lowercase and %TP uses uppercase.

%tp

Like %tP but uses uppercase for both %tp and %Tp variants.

%tr

The hour and minute on a 24-hour clock. Equivalent to "%tH:%tM".

%tr

The hour, minute, and second on a 12-hour clock. Equivalent to "%tI:%tM:%tS %tP" except that the am/pm indicator %tP may be in a different locale-dependent position.

%tS

Seconds within the minute, as two digits with a leading zero if necessary. The range is normally 00-59, but a value of 60 is allowed for leap seconds.

%ts

Seconds since the beginning of the epoch. See %tE .

%tT

The time in hours, minutes, and seconds using 24-hour format. Equivalent to "%tH:%tM:%tS".

%tY

The year, using at least four digits, formatted with leading zeros, if necessary.

%ty

The last two digits of the year, 00-99

%tZ

An abbreviation for the time zone.

%tz

The time zone as numeric offset from GMT.


Argument Specifier

Every format specifier in a format string except for %% and %n requires an argument that contains the value to format. These arguments follow the format string in the call to format( ) or printf( ) . By default, a format specifier uses the next unused argument. In the following printf( ) call, the first and second %s format specifiers format the second and third arguments, respectively:

 out.printf("Name: %s %s%n", first, last); 

If a format specifier includes the character < after the % , it specifies that the argument of the previous format specifier should be reused. This allows the same object (such as a date) to be formatted more than once (yielding a formatted date and time, for example):

 out.printf("Date: %tD%nTime: %<tr%n", System.currentTimeMillis( )); 

It is an error to use < in the first format specifier of a format string.

Argument numbers may also be specified absolutely . If the % sign is followed by one or more digits and a $ sign, those digits specify an argument number. For example %1$d specifies that the first argument following the format string should be formatted as an integer. Absolute argument numbers are particularly useful for localization since the different translations of a message may need to interpolate the arguments in a different order. The following example includes a format string that might be used in a locale where a person's family name is typically printed (in uppercase) before the given name. Note that the arguments are not passed in the same order that they are formatted.

 String name = String.format("%2$S, %1$s", firstname, lastname); 

Neither absolute argument indexing with a number and $ character or relative argument indexing with < affect the order in which arguments are interpolated for format specifiers that use neither $ or < . The first format specifier that has neither an absolute or relative argument specification uses the first argument following the format string, regardless of what has come before. The code above could be rewritten like this, for example:

 String name = String.format("%2$S, %s", firstname, lastname); 

Flags

Following the optional argument specifier, a format specifier may include one or more flag characters. The defined flags, their effects, and the format types for which they are legal are specified in Table 16-2:

Table 16-2. Formatter flags

Flag

Description

-

A hyphen specifies that the formatted value should be left-justified within the specified width . This flag can be used with any conversion type except %n as long as the conversion specifier also includes a width (see below). When a width is specified without this flag, the formatted string is padded on the left to produce right-justified output.

#

The # flag specifies that output should appear in an "alternate form" that depends on the type being formatted. For %o conversions, this flag specifies that the output should include a leading 0. For %x and %X conversions, it specifies that output should include a leading 0x or 0X . For the %s and %S conversions, the # flag may be used if the argument implements Formattable . In this case, the flag is passed on to the formatTo( ) method of the argument, and it is up to that formatTo( ) method to produce its output in some alternate form.

+

This flag specifies that numeric output should always include a sign: a value that is nonnegative will have "+" added in front of it. This flag may be used with any numeric conversion that may yield a signed result. This includes %d , %e , %f , %g , %a , and their uppercase variants. It also includes %o , %x , and %X conversions applied to BigInteger arguments.

 

The space character is a (hard-to-read) flag that specifies that non-negative values should be prefixed with a space. This flag may be used with the same conversion and argument types as the + flag, and is useful when aligning positive and negative numbers in a column

(

This flag specifies that negative numbers should be enclosed in parentheses, as is commonly done in financial statements, for example. This flag may be used with the same format and argument types as the + flag, except that it may not be used with %a conversions.

The digit zero, used as a flag, specifies that numeric values should be padded on the left (after the sign character, if any) with zeros. This flag may be used only if a width is specified, and may not be used in conjunction with the - flag.

,

This flag specifies that numbers should be formatted using the locale-specific grouping separator. In the US locale, for example, a comma would appear every three digits to separate the number into thousands, millions, and so on. This flag may be used with %d , %e , %E , %f , %g , and %G conversions only.


Width

The width portion of a format specifier is one or more digits that specify the minimum number of characters to be produced. If the formatted value is narrower than the specified width, (by default) it is padded on the left with spaces, producing a right-justified value. The - and flags can be used to specify left-justification or padding with zeros instead.

A width may be specified with any format type except %n .

Precision

The precision portion of a format specifier is one or more digits following a decimal point. The meaning of this number depends on which format type it is used with:

  • For %e , %E , and %f , the precision specifies the number of digits to appear after the decimal point. Zeros are appended on the right, if necessary. The default precision is 6.

  • For %g and %G format types, the precision specifies the total number of significant digits to be displayed. As a corollary, it specifies the largest and smallest values that can be displayed without resorting to exponential notation. The default precision is 6. If a precision of 0 is specified, it is treated as a precision of 1.

  • For %s , %h and %b format types, and their uppercase variants, the precision specifies the maximum number of characters to be output. If no precision is specified, there is no maximum. If the formatted output would exceed the precision of characters, it is truncated. If precision is smaller than width , the formatted value is first truncated as necessary and then padded within the specified width .

  • Specifying a precision for any other conversion type causes an exception at runtime.

Synopsis

Figure 16-21. java.util.Formatter

 public final class  Formatter  implements java.io.Closeable, java.io.Flushable {  // Public Constructors  public  Formatter  ( );        public  Formatter  (java.io.PrintStream  ps  );        public  Formatter  (java.io.OutputStream  os  );        public  Formatter  (java.io.File  file  ) throws java.io.FileNotFoundException;        public  Formatter  (String  fileName  ) throws java.io.FileNotFoundException;        public  Formatter  (Locale  l  );        public  Formatter  (Appendable  a  );        public  Formatter  (java.io.OutputStream  os  , String  csn  )          throws java.io.UnsupportedEncodingException;        public  Formatter  (java.io.File  file  , String  csn  )          throws java.io.FileNotFoundException, java.io.UnsupportedEncodingException;        public  Formatter  (Appendable  a  , Locale  l  );        public  Formatter  (String  fileName  , String  csn  )          throws java.io.FileNotFoundException, java.io.UnsupportedEncodingException;        public  Formatter  (String  fileName  , String  csn  , Locale  l  )          throws java.io.FileNotFoundException, java.io.UnsupportedEncodingException;        public  Formatter  (java.io.File  file  , String  csn  , Locale  l  )          throws java.io.FileNotFoundException, java.io.UnsupportedEncodingException;        public  Formatter  (java.io.OutputStream  os  , String  csn  , Locale  l  )          throws java.io.UnsupportedEncodingException;  // Nested Types  public enum  BigDecimalLayoutForm  ;  // Public Instance Methods  public java.util.Formatter  format  (String  format  , Object...  args  );        public java.util.Formatter  format  (Locale  l  , String  format  , Object...  args  );        public java.io.IOException  ioException  ( );        public Locale  locale  ( );        public Appendable  out  ( );  // Methods Implementing Closeable  public void  close  ( );  // Methods Implementing Flushable  public void  flush  ( );  // Public Methods Overriding Object  public String  toString  ( );   } 

Passed To

Formattable.formatTo( )



Java In A Nutshell
Java In A Nutshell, 5th Edition
ISBN: 0596007736
EAN: 2147483647
Year: 2004
Pages: 1220

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net