Translation_java_Formatter

java.util
Class Formatter

java.lang.Objectjava.util.Formatter

All Implemented Interfaces:

Closeable,Flushable

---

public final classFormatter

extendsObject implementsCloseable,Flushable

Aninterpreter(转意)for printf-style format strings. This class providessupport(支持)forlayout(布局)justification(正规的)andalignment(排列),common(普遍的)formats for numeric, string, and date/time data, andlocale-specific(特殊地方)output. Common Java types such asbyte,BigDecimal, andCalendar(日期)are supported.Limited(限制)formattingcustomization(自定义)forarbitrary(任意)user types is provided through theFormattableinterface.

一种转义字符传的格式，这个类提供了布局和排列，普遍的格式数字，字符串和日期时间；

然后输出在特殊的地方。通常java的类型像字节，BigDecimal，和日期是支持的，

自定义格式是被限制的，任何使用类型通过实现formattable接口被支持的

Formatters are not necessarily safe for multithreaded access. Thread safety isoptional(可选择的)and is theresponsibility(可靠的)of users of methods in this class.

格式是不需要多线程安全的访问，线程安全是可选择的，和使用的方法是可靠的在这个类中

Formatted printing for the Java language is heavilyinspired(受..影响)by C'sprintf. Although the format strings are similar to C, somecustomizations(自定义)have been made toaccommodate(适应)the Java language andexploit(开发)some of itsfeatures(特征). Also, Java formatting is more strict than C's; for example, if a conversion isincompatible(不符合)with aflag(标志), an exception will be thrown. In C inapplicable flags are silently ignored. The format strings arethus(结果)intended(打算)to berecognizable(可认的)to Cprogrammers(程序员)but not necessarilycompletely(完全的)compatible(兼容的)with those in C.

Java语言的格式打印受C的printf，尽管格式字符传是同C相同的，但是为了适应

Java语言已经作出了一些自定义改变，和开发了一些自己的特征。Java格式化严格比C；

例如，假如一个转换是不符合，例题将会被抛出。在C中是被忽略的。

Java格式字符给C程序员认识的，但不完全兼容给C用

Examples of expected usage:

StringBuilder sb = new StringBuilder(); // Send all output to the Appendable object sb Formatter formatter = new Formatter(sb, Locale.US); //Explicit(详细的)argument(参数)indices may be used to re-order output. formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d") // -> " d c b a" // Optional locale as the first argument can be used to get // locale-specific formatting of numbers. Theprecision(精确)and width can be // given to round and align the value. formatter.format(Locale.FRANCE, "e = %+10.4f", Math.E); // -> "e = +2,7183" // The '(' numeric flag may be used to format negative numbers with // parentheses rather than a minus sign. Group separators are // automatically inserted. formatter.format("Amount gained or lost since last statement: $ %(,.2f", balanceDelta); // -> "Amount gained or lost since last statement: $ (6,217.58)"

Convenience(便利)methods for common(普遍的) formatting requests exist asillustrated(说明)by the following invocations:

一些比较便利常用的格式化，都被下面说明了

// Writes a formatted string to System.out. System.out.format("Local time: %tT", Calendar.getInstance()); // -> "Local time: 13:34:18" // Writes formatted output to System.err. System.err.printf("Unable to open file '%1$s': %2$s", fileName, exception.getMessage()); // -> "Unable to open file 'food': No such file or directory"

Like C'ssprintf(3), Strings may be formatted using the static methodString.format:

// Format a string containing a date. import java.util.Calendar; import java.util.GregorianCalendar; import static java.util.Calendar.*; Calendar c = new GregorianCalendar(1995, MAY, 23); String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c); // -> s == "Duke's Birthday: May 23, 1995"

Organization

Thisspecification(规定)isdivided(分)into twosections(部分). The firstsection,Summary(总结), covers the basic formattingconcepts(概念). Thissectionisintended(为..打算)for users who want to get started quickly and arefamiliar(熟悉)with formatted printing in other programming languages. The second section,Details, covers the specificimplementation(执行操作)details. It isintendedfor users who want moreprecise(规格)specificationof formattingbehavior(作用).

它的规定分为两部分，第一部分总结包含了基本的格式概念。这部分的目的是为用户快速开始，

和熟悉格式化输出在其他编程语言中；

这第二部分，包含它的详细执行，它的目的是为了让用户得到更多关于格式化规范

Summary

Thissectionisintended(目的)to provide abrief(短暂的)overview(概述)of formattingconcepts(概念). For precise behavioral details, refer to theDetailssection.

这章的目的是提供一个简短的格式化概念，参考详细资料

Format StringSyntax(语法)

Every method whichproduces(产生)formatted output requires(需要)aformat stringand anargument list. The format string is aStringwhich may contain fixed text and one or moreembedded(嵌入)formatspecifiers(区分符). Consider the following example:

每个格式化输出的方法需要一个格式化字符串和一个对象列表

Calendar c = ...; String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);

This format string is the first argument to theformatmethod. It contains three formatspecifiers"%1$tm", "%1$te", and "%1$tY" whichindicate(指示)how the arguments should beprocessed(加工)and where they should be inserted in the text. Theremaining(剩余的)portions(部分)of the format string are fixed text including"Dukes Birthday: "and any other spaces orpunctuation(字符). The argument listconsists(由..决定)of all arguments passed to the method after the format string. In theabove(上)example, the argument list is of size one and consists of theCalendarobjectc.

这格式化字符串是第一个对象给这格式方法，它包含了三个格式化区分符：%1$tm,%1$te,和%1$tY；

它表示那个参数可以被修改和它们被嵌入到这文本中，这剩余的部分是固定的

包含：Dukes Birthday和任何空格或标点符号，参数列表由传过来的方法参数决定在格式化字符后。

在上面的例子中，

• The format specifiers for general, character, and numeric types have the following syntax:

  %[argument_index$][flags][width][.precision]conversion

  The optionalargument_indexis adecimal integerindicating(标志)theposition(位置)of the argument in the argument list. The first argument is referenced by "1$", the second by "2$", etc.

  这个参数索引是一个十进制的整数，它标志在参数列表中的位置。这第一个引用的是‘1$;
• 第二个‘2$’

• Theoptional(选择)flagsis a set of characters that modify the output format. The set ofvalid(有效的)flags depends on theconversion.

  选择标志的是一堆字符集，它被格式化修改输出的；这些有效的标志决定了转换

  The optionalwidthis anon-negative(非负)decimal integerindicating(表示)the minimum number of characters to be written to the output.

  它的宽度是一个非负数的十进制的整数，表示最小写入到输出的

  The optionalprecisionis a non-negative decimal integer usually used torestrict(限制)the number of characters. The specificbehavior(作用)depends on the conversion.

  The requiredconversionis a character indicating how the argument should be formatted. The set of valid conversions for a given argument depends on the argument's data type.

• The format specifiers for types which are used to represents dates and times have the following syntax:
• 
  

  %[argument_index$][flags][width]conversion

  The optionalargument_index,flagsandwidthare defined as above.

  The requiredconversionis a two character sequence. The first character is't'or'T'. The second character indicates the format to be used. These characters are similar to but not completely identical to those defined by GNUdateand POSIXstrftime(3c).

• The format specifiers which do not correspond to arguments have the following syntax:

  %[flags][width]conversion

  The optionalflagsandwidthis defined as above.

  The requiredconversionis a character indicating content to be inserted in the output.

Conversions

Conversions are divided into the following categories:

1. General- may be applied to any argument type
2. Character- may be applied to basic types which represent Unicode characters:char,Character,byte,Byte,short, andShort. This conversion may also be applied to the typesintandIntegerwhenCharacter.isValidCodePoint(int)returnstrue
3. Numeric
   1. Integral- may be applied to Java integral types:byte,Byte,short,Short,intandInteger,long,Long, andBigInteger
   2. Floating Point- may be applied to Java floating-point types:float,Float,double,Double, andBigDecimal
4. Date/Time- may be applied to Java types which are capable of encoding a date or time:long,Long,Calendar, andDate.
5. Percent- produces a literal'%'('\u0025')
6. Line Separator- produces the platform-specific line separator

The following table summarizes the supported conversions. Conversions denoted by an upper-case character (i.e.'B','H','S','C','X','E','G','A', and'T') are the same as those for the corresponding lower-case conversion characters except that the result is converted to upper case according to the rules of the prevailingLocale. The result is equivalent to the following invocation ofString.toUpperCase()

out.toUpperCase()

Conversion	Argument Category	Description
'b','B'	general	If the argumentargisnull, then the result is "false". Ifargis abooleanorBoolean, then the result is the string returned byString.valueOf(). Otherwise, the result is "true".
'h','H'	general	If the argumentargisnull, then the result is "null". Otherwise, the result is obtained by invokingInteger.toHexString(arg.hashCode()).
's','S'	general	If the argumentargisnull, then the result is "null". IfargimplementsFormattable, thenarg.formatTois invoked. Otherwise, the result is obtained by invokingarg.toString().
'c','C'	character	The result is a Unicode character
'd'	integral	The result is formatted as a decimal integer
'o'	integral	The result is formatted as an octal integer
'x','X'	integral	The result is formatted as a hexadecimal integer
'e','E'	floating point	The result is formatted as a decimal number in computerized scientific notation
'f'	floating point	The result is formatted as a decimal number
'g','G'	floating point	The result is formatted using computerized scientific notation or decimal format, depending on the precision and the value after rounding.
'a','A'	floating point	The result is formatted as a hexadecimal floating-point number with a significand and an exponent
't','T'	date/time	Prefix for date and time conversion characters. SeeDate/Time Conversions.
'%'	percent	The result is a literal'%'('\u0025')
'n'	line separator	The result is the platform-specific line separator

Any characters not explicitly defined as conversions are illegal and are reserved for future extensions.

Date/Time Conversions

The following date and time conversion suffix characters are defined for the't'and'T'conversions. The types are similar to but not completely identical to those defined by GNUdateand POSIXstrftime(3c). Additional conversion types are provided to access Java-specific functionality (e.g.'L'for milliseconds within the second).

The following conversion characters are used for formatting times:

'H'	Hour of the day for the 24-hour clock, formatted as two digits with a leading zero as necessary i.e.00 - 23.
'I'	Hour for the 12-hour clock, formatted as two digits with a leading zero as necessary, i.e.01 - 12.
'k'	Hour of the day for the 24-hour clock, i.e.0 - 23.
'l'	Hour for the 12-hour clock, i.e.1 - 12.
'M'	Minute within the hour formatted as two digits with a leading zero as necessary, i.e.00 - 59.
'S'	Seconds within the minute, formatted as two digits with a leading zero as necessary, i.e.00 - 60("60" is a special value required to support leap seconds).
'L'	Millisecond within the second formatted as three digits with leading zeros as necessary, i.e.000 - 999.
'N'	Nanosecond within the second, formatted as nine digits with leading zeros as necessary, i.e.000000000 - 999999999.
'p'	Locale-specificmorning or afternoonmarker in lower case, e.g."am" or "pm". Use of the conversion prefix'T'forces this output to upper case.
'z'	RFC822style numeric time zone offset from GMT, e.g.-0800.
'Z'	A string representing the abbreviation for the time zone. The Formatter's locale will supersede the locale of the argument (if any).
's'	Seconds since the beginning of the epoch starting at 1 January 197000:00:00UTC, i.e.Long.MIN_VALUE/1000toLong.MAX_VALUE/1000.
'Q'	Milliseconds since the beginning of the epoch starting at 1 January 197000:00:00UTC, i.e.Long.MIN_VALUEtoLong.MAX_VALUE.

The following conversion characters are used for formatting dates:

'B'	Locale-specificfull month name, e.g."January","February".
'b'	Locale-specificabbreviated month name, e.g."Jan","Feb".
'h'	Same as'b'.
'A'	Locale-specific full name of theday of the week, e.g."Sunday","Monday"
'a'	Locale-specific short name of theday of the week, e.g."Sun","Mon"
'C'	Four-digit year divided by100, formatted as two digits with leading zero as necessary, i.e.00 - 99
'Y'	Year, formatted as at least four digits with leading zeros as necessary, e.g.0092equals92CE for the Gregorian calendar.
'y'	Last two digits of the year, formatted with leading zeros as necessary, i.e.00 - 99.
'j'	Day of year, formatted as three digits with leading zeros as necessary, e.g.001 - 366for the Gregorian calendar.
'm'	Month, formatted as two digits with leading zeros as necessary, i.e.01 - 13.
'd'	Day of month, formatted as two digits with leading zeros as necessary, i.e.01 - 31
'e'	Day of month, formatted as two digits, i.e.1 - 31.

The following conversion characters are used for formatting common date/time compositions.

'R'	Time formatted for the 24-hour clock as"%tH:%tM"
'T'	Time formatted for the 24-hour clock as"%tH:%tM:%tS".
'r'	Time formatted for the 12-hour clock as"%tI:%tM:%tS %Tp". The location of the morning or afternoon marker ('%Tp') may be locale-dependent.
'D'	Date formatted as"%tm/%td/%ty".
'F'	ISO8601complete date formatted as"%tY-%tm-%td".
'c'	Date and time formatted as"%ta %tb %td %tT %tZ %tY", e.g."Sun Jul 20 16:17:00 EDT 1969".

Any characters not explicitly defined as date/time conversion suffixes are illegal and are reserved for future extensions.

Flags

The following table summarizes the supported flags.ymeans the flag is supported for the indicated argument types.

Flag	General	Character	Integral	Floating Point	Date/Time	Description
'-'	y	y	y	y	y	The result will be left-justified.
'#'	y1	-	y3	y	-	The result should use a conversion-dependent alternate form
'+'	-	-	y4	y	-	The result will always include a sign
''	-	-	y4	y	-	The result will include a leading space for positive values
'0'	-	-	y	y	-	The result will be zero-padded
','	-	-	y2	y5	-	The result will include locale-specificgrouping separators
'('	-	-	y4	y5	-	The result will enclose negative numbers in parentheses

¹Depends on the definition ofFormattable.

²For'd'conversion only.

³For'o','x', and'X'conversions only.

⁴For'd','o','x', and'X'conversions applied toBigIntegeror'd'applied tobyte,Byte,short,Short,intandInteger,long, andLong.

⁵For'e','E','f','g', and'G'conversions only.

Any characters not explicitly defined as flags are illegal and are reserved for future extensions.

Width

The width is the minimum number of characters to be written to the output. For the line separator conversion, width is not applicable; if it is provided, an exception will be thrown.

Precision

For general argument types, the precision is the maximum number of characters to be written to the output.

For the floating-point conversions'e','E', and'f'the precision is the number of digits after the decimal separator. If the conversion is'g'or'G', then the precision is the total number of digits in the resulting magnitude after rounding. If the conversion is'a'or'A', then the precision must not be specified.

For character, integral, and date/time argument types and the percent and line separator conversions, the precision is not applicable; if a precision is provided, an exception will be thrown.

Argument Index

The argument index is a decimal integer indicating the position of the argument in the argument list. The first argument is referenced by "1$", the second by "2$", etc.

Another way to reference arguments by position is to use the'<'('\u003c') flag, which causes the argument for the previous format specifier to be re-used. For example, the following two statements would produce identical strings:

Calendar c = ...; String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c); String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c);

---

Details

This section is intended to provide behavioral details for formatting, including conditions and exceptions, supported data types, localization, and interactions between flags, conversions, and data types. For an overview of formatting concepts, refer to theSummary

Any characters not explicitly defined as conversions, date/time conversion suffixes, or flags are illegal and are reserved for future extensions. Use of such a character in a format string will cause anUnknownFormatConversionExceptionorUnknownFormatFlagsExceptionto be thrown.

If the format specifier contains a width or precision with an invalid value or which is otherwise unsupported, then aIllegalFormatWidthExceptionorIllegalFormatPrecisionExceptionrespectively will be thrown.

If a format specifier contains a conversion character that is not applicable to the corresponding argument, then anIllegalFormatConversionExceptionwill be thrown.

All specified exceptions may be thrown by any of theformatmethods ofFormatteras well as by anyformatconvenience methods such asString.formatandPrintStream.printf.

Conversions denoted by an upper-case character (i.e.'B','H','S','C','X','E','G','A', and'T') are the same as those for the corresponding lower-case conversion characters except that the result is converted to upper case according to the rules of the prevailingLocale. The result is equivalent to the following invocation ofString.toUpperCase()

out.toUpperCase()

General

The following general conversions may be applied to any argument type:

'b'	'\u0062'	Produces either "true" or "false" as returned byBoolean.toString(boolean). If the argument isnull, then the result is "false". If the argument is abooleanorBoolean, then the result is the string returned byString.valueOf(). Otherwise, the result is "true". If the'#'flag is given, then aFormatFlagsConversionMismatchExceptionwill be thrown.
'B'	'\u0042'	The upper-case variant of'b'.
'h'	'\u0068'	Produces a string representing the hash code value of the object. If the argument,argisnull, then the result is "null". Otherwise, the result is obtained by invokingInteger.toHexString(arg.hashCode()). If the'#'flag is given, then aFormatFlagsConversionMismatchExceptionwill be thrown.
'H'	'\u0048'	The upper-case variant of'h'.
's'	'\u0073'	Produces a string. If the argument isnull, then the result is "null". If the argument implementsFormattable, then itsformatTomethod is invoked. Otherwise, the result is obtained by invoking the argument'stoString()method. If the'#'flag is given and the argument is not aFormattable, then aFormatFlagsConversionMismatchExceptionwill be thrown.
'S'	'\u0053'	The upper-case variant of's'.

The followingflagsapply to general conversions:

'-'	'\u002d'	Left justifies the output. Spaces ('\u0020') will be added at the end of the converted value as required to fill the minimum width of the field. If the width is not provided, then aMissingFormatWidthExceptionwill be thrown. If this flag is not given then the output will be right-justified.
'#'	'\u0023'	Requires the output use an alternate form. The definition of the form is specified by the conversion.

Thewidthis the minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by''(\u0020') until the total number of characters equals the width. The padding is on the left by default. If the'-'flag is given, then the padding will be on the right. If the width is not specified then there is no minimum.

The precision is the maximum number of characters to be written to the output. The precision is applied before the width, thus the output will be truncated toprecisioncharacters even if the width is greater than the precision. If the precision is not specified then there is no explicit limit on the number of characters.

Character

This conversion may be applied tocharandCharacter. It may also be applied to the typesbyte,Byte,short, andShort,intandIntegerwhenCharacter.isValidCodePoint(int)returnstrue. If it returnsfalsethen anIllegalFormatCodePointExceptionwill be thrown.

'c'	'\u0063'	Formats the argument as a Unicode character as described inUnicode Character Representation. This may be more than one 16-bitcharin the case where the argument represents a supplementary character. If the'#'flag is given, then aFormatFlagsConversionMismatchExceptionwill be thrown.
'C'	'\u0043'	The upper-case variant of'c'.

The'-'flag defined forGeneral conversionsapplies. If the'#'flag is given, then aFormatFlagsConversionMismatchExceptionwill be thrown.

The width is defined as forGeneral conversions.

The precision is not applicable. If the precision is specified then anIllegalFormatPrecisionExceptionwill be thrown.

Numeric

Numeric conversions are divided into the following categories:

1. Byte, Short, Integer, and Long
2. BigInteger
3. Float and Double
4. BigDecimal

Numeric types will be formatted according to the following algorithm:

Number Localization Algorithm

After digits are obtained for the integer part, fractional part, and exponent (as appropriate for the data type), the following transformation is applied:

1. Each digit characterdin the string is replaced by a locale-specific digit computed relative to the current locale'szero digitz; that isd-'0'+z.
2. If a decimal separator is present, a locale-specificdecimal separatoris substituted.
3. If the','('\u002c')flagis given, then the locale-specificgrouping separatoris inserted by scanning the integer part of the string from least significant to most significant digits and inserting a separator at intervals defined by the locale'sgrouping size.
4. If the'0'flag is given, then the locale-specificzero digitsare inserted after the sign character, if any, and before the first non-zero digit, until the length of the string is equal to the requested field width.
5. If the value is negative and the'('flag is given, then a'('('\u0028') is prepended and a')'('\u0029') is appended.
6. If the value is negative (or floating-point negative zero) and'('flag is not given, then a'-'('\u002d') is prepended.
7. If the'+'flag is given and the value is positive or zero (or floating-point positive zero), then a'+'('\u002b') will be prepended.

If the value is NaN or positive infinity the literal strings "NaN" or "Infinity" respectively, will be output. If the value is negative infinity, then the output will be "(Infinity)" if the'('flag is given otherwise the output will be "-Infinity". These values are not localized.

Byte, Short, Integer, and Long

The following conversions may be applied tobyte,Byte,short,Short,intandInteger,long, andLong.

'd'	'\u0054'	Formats the argument as a decimal integer. Thelocalization algorithmis applied. If the'0'flag is given and the value is negative, then the zero padding will occur after the sign. If the'#'flag is given then aFormatFlagsConversionMismatchExceptionwill be thrown.
'o'	'\u006f'	Formats the argument as an integer in base eight. No localization is applied. Ifxis negative then the result will be an unsigned value generated by adding 2nto the value wherenis the number of bits in the type as returned by the staticSIZEfield in theByte,Short,Integer, orLongclasses as appropriate. If the'#'flag is given then the output will always begin with the radix indicator'0'. If the'0'flag is given then the output will be padded with leading zeros to the field width following any indication of sign. If'(','+', '', or','flags are given then aFormatFlagsConversionMismatchExceptionwill be thrown.
'x'	'\u0078'	Formats the argument as an integer in base sixteen. No localization is applied. Ifxis negative then the result will be an unsigned value generated by adding 2nto the value wherenis the number of bits in the type as returned by the staticSIZEfield in theByte,Short,Integer, orLongclasses as appropriate. If the'#'flag is given then the output will always begin with the radix indicator"0x". If the'0'flag is given then the output will be padded to the field width with leading zeros after the radix indicator or sign (if present). If'(','','+', or','flags are given then aFormatFlagsConversionMismatchExceptionwill be thrown.
'X'	'\u0058'	The upper-case variant of'x'. The entire string representing the number will be converted toupper caseincluding the'x'(if any) and all hexadecimal digits'a'-'f'('\u0061'-'\u0066').

If the conversion is'o','x', or'X'and both the'#'and the'0'flags are given, then result will contain the radix indicator ('0'for octal and"0x"or"0X"for hexadecimal), some number of zeros (based on the width), and the value.

If the'-'flag is not given, then the space padding will occur before the sign.

The followingflagsapply to numeric integral conversions:

'+'	'\u002b'	Requires the output to include a positive sign for all positive numbers. If this flag is not given then only negative values will include a sign. If both the'+'and''flags are given then anIllegalFormatFlagsExceptionwill be thrown.
''	'\u0020'	Requires the output to include a single extra space ('\u0020') for non-negative values. If both the'+'and''flags are given then anIllegalFormatFlagsExceptionwill be thrown.
'0'	'\u0030'	Requires the output to be padded with leadingzerosto the minimum field width following any sign or radix indicator except when converting NaN or infinity. If the width is not provided, then aMissingFormatWidthExceptionwill be thrown. If both the'-'and'0'flags are given then anIllegalFormatFlagsExceptionwill be thrown.
','	'\u002c'	Requires the output to include the locale-specificgroup separatorsas described in the"group" sectionof the localization algorithm.
'('	'\u0028'	Requires the output to prepend a'('('\u0028') and append a')'('\u0029') to negative values.

If noflagsare given the default formatting is as follows:

• The output is right-justified within thewidth
• Negative numbers begin with a'-'('\u002d')
• Positive numbers and zero do not include a sign or extra leading space
• No grouping separators are included

Thewidthis the minimum number of characters to be written to the output. This includes any signs, digits, grouping separators, radix indicator, and parentheses. If the length of the converted value is less than the width then the output will be padded by spaces ('\u0020') until the total number of characters equals width. The padding is on the left by default. If'-'flag is given then the padding will be on the right. If width is not specified then there is no minimum.

The precision is not applicable. If precision is specified then anIllegalFormatPrecisionExceptionwill be thrown.

BigInteger

The following conversions may be applied toBigInteger.

'd'	'\u0054'	Requires the output to be formatted as a decimal integer. Thelocalization algorithmis applied. If the'#'flag is givenFormatFlagsConversionMismatchExceptionwill be thrown.
'o'	'\u006f'	Requires the output to be formatted as an integer in base eight. No localization is applied. Ifxis negative then the result will be a signed value beginning with'-'('\u002d'). Signed output is allowed for this type because unlike the primitive types it is not possible to create an unsigned equivalent without assuming an explicit data-type size. Ifxis positive or zero and the'+'flag is given then the result will begin with'+'('\u002b'). If the'#'flag is given then the output will always begin with'0'prefix. If the'0'flag is given then the output will be padded with leading zeros to the field width following any indication of sign. If the','flag is given then aFormatFlagsConversionMismatchExceptionwill be thrown.
'x'	'\u0078'	Requires the output to be formatted as an integer in base sixteen. No localization is applied. Ifxis negative then the result will be a signed value beginning with'-'('\u002d'). Signed output is allowed for this type because unlike the primitive types it is not possible to create an unsigned equivalent without assuming an explicit data-type size. Ifxis positive or zero and the'+'flag is given then the result will begin with'+'('\u002b'). If the'#'flag is given then the output will always begin with the radix indicator"0x". If the'0'flag is given then the output will be padded to the field width with leading zeros after the radix indicator or sign (if present). If the','flag is given then aFormatFlagsConversionMismatchExceptionwill be thrown.
'X'	'\u0058'	The upper-case variant of'x'. The entire string representing the number will be converted toupper caseincluding the'x'(if any) and all hexadecimal digits'a'-'f'('\u0061'-'\u0066').

If the conversion is'o','x', or'X'and both the'#'and the'0'flags are given, then result will contain the base indicator ('0'for octal and"0x"or"0X"for hexadecimal), some number of zeros (based on the width), and the value.

If the'0'flag is given and the value is negative, then the zero padding will occur after the sign.

If the'-'flag is not given, then the space padding will occur before the sign.

Allflagsdefined for Byte, Short, Integer, and Long apply. Thedefault behaviorwhen no flags are given is the same as for Byte, Short, Integer, and Long.

The specification ofwidthis the same as defined for Byte, Short, Integer, and Long.

The precision is not applicable. If precision is specified then anIllegalFormatPrecisionExceptionwill be thrown.

Float and Double

The following conversions may be applied tofloat,Float,doubleandDouble.

'e'	'\u0065'	Requires the output to be formatted usingcomputerized scientific notation. Thelocalization algorithmis applied. The formatting of the magnitudemdepends upon its value. Ifmis NaN or infinite, the literal strings "NaN" or "Infinity", respectively, will be output. These values are not localized. Ifmis positive-zero or negative-zero, then the exponent will be"+00". Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. The formatting of the sign is described in thelocalization algorithm. The formatting of the magnitudemdepends upon its value. Letnbe the unique integer such that 10n<=m< 10n+1; then letabe the mathematically exact quotient ofmand 10nso that 1 <=a< 10. The magnitude is then represented as the integer part ofa, as a single decimal digit, followed by the decimal separator followed by decimal digits representing the fractional part ofa, followed by the exponent symbol'e'('\u0065'), followed by the sign of the exponent, followed by a representation ofnas a decimal integer, as produced by the methodLong.toString(long, int), and zero-padded to include at least two digits. The number of digits in the result for the fractional part ofmorais equal to the precision. If the precision is not specified then the default value is6. If the precision is less than the number of digits which would appear after the decimal point in the string returned byFloat.toString(float)orDouble.toString(double)respectively, then the value will be rounded using theround half up algorithm. Otherwise, zeros may be appended to reach the precision. For a canonical representation of the value, useFloat.toString(float)orDouble.toString(double)as appropriate. If the','flag is given, then anFormatFlagsConversionMismatchExceptionwill be thrown.
'E'	'\u0045'	The upper-case variant of'e'. The exponent symbol will be'E'('\u0045').
'g'	'\u0067'	Requires the output to be formatted in general scientific notation as described below. Thelocalization algorithmis applied. After rounding for the precision, the formatting of the resulting magnitudemdepends on its value. Ifmis greater than or equal to 10-4but less than 10precisionthen it is represented indecimal format. Ifmis less than 10-4or greater than or equal to 10precision, then it is represented incomputerized scientific notation. The total number of significant digits inmis equal to the precision. If the precision is not specified, then the default value is6. If the precision is0, then it is taken to be1. If the'#'flag is given then anFormatFlagsConversionMismatchExceptionwill be thrown.
'G'	'\u0047'	The upper-case variant of'g'.
'f'	'\u0066'	Requires the output to be formatted usingdecimal format. Thelocalization algorithmis applied. The result is a string that represents the sign and magnitude (absolute value) of the argument. The formatting of the sign is described in thelocalization algorithm. The formatting of the magnitudemdepends upon its value. IfmNaN or infinite, the literal strings "NaN" or "Infinity", respectively, will be output. These values are not localized. The magnitude is formatted as the integer part ofm, with no leading zeroes, followed by the decimal separator followed by one or more decimal digits representing the fractional part ofm. The number of digits in the result for the fractional part ofmorais equal to the precision. If the precision is not specified then the default value is6. If the precision is less than the number of digits which would appear after the decimal point in the string returned byFloat.toString(float)orDouble.toString(double)respectively, then the value will be rounded using theround half up algorithm. Otherwise, zeros may be appended to reach the precision. For a canonical representation of the value,useFloat.toString(float)orDouble.toString(double)as appropriate.
'a'	'\u0061'	Requires the output to be formatted in hexadecimal exponential form. No localization is applied. The result is a string that represents the sign and magnitude (absolute value) of the argumentx. Ifxis negative or a negative-zero value then the result will begin with'-'('\u002d'). Ifxis positive or a positive-zero value and the'+'flag is given then the result will begin with'+'('\u002b'). The formatting of the magnitudemdepends upon its value. If the value is NaN or infinite, the literal strings "NaN" or "Infinity", respectively, will be output. Ifmis zero then it is represented by the string"0x0.0p0". Ifmis adoublevalue with a normalized representation then substrings are used to represent the significand and exponent fields. The significand is represented by the characters"0x1."followed by the hexadecimal representation of the rest of the significand as a fraction. The exponent is represented by'p'('\u0070') followed by a decimal string of the unbiased exponent as if produced by invokingInteger.toStringon the exponent value. Ifmis adoublevalue with a subnormal representation then the significand is represented by the characters'0x0.'followed by the hexadecimal representation of the rest of the significand as a fraction. The exponent is represented by'p-1022'. Note that there must be at least one nonzero digit in a subnormal significand. If the'('or','flags are given, then aFormatFlagsConversionMismatchExceptionwill be thrown.
'A'	'\u0041'	The upper-case variant of'a'. The entire string representing the number will be converted to upper case including the'x'('\u0078') and'p'('\u0070'and all hexadecimal digits'a'-'f'('\u0061'-'\u0066').

Allflagsdefined for Byte, Short, Integer, and Long apply.

If the'#'flag is given, then the decimal separator will always be present.

If noflagsare given the default formatting is as follows:

• The output is right-justified within thewidth
• Negative numbers begin with a'-'
• Positive numbers and positive zero do not include a sign or extra leading space
• No grouping separators are included
• The decimal separator will only appear if a digit follows it

Thewidthis the minimum number of characters to be written to the output. This includes any signs, digits, grouping separators, decimal separators, exponential symbol, radix indicator, parentheses, and strings representing infinity and NaN as applicable. If the length of the converted value is less than the width then the output will be padded by spaces ('\u0020') until the total number of characters equals width. The padding is on the left by default. If the'-'flag is given then the padding will be on the right. If width is not specified then there is no minimum.

If theconversionis'e','E'or'f', then the precision is the number of digits after the decimal separator. If the precision is not specified, then it is assumed to be6.

If the conversion is'g'or'G', then the precision is the total number of significant digits in the resulting magnitude after rounding. If the precision is not specified, then the default value is6. If the precision is0, then it is taken to be1.

If the conversion is'a'or'A', then the precision is the number of hexadecimal digits after the decimal separator. If the precision is not provided, then all of the digits as returned byDouble.toHexString(double)will be output.

BigDecimal

The following conversions may be appliedBigDecimal.

'e'	'\u0065'	Requires the output to be formatted usingcomputerized scientific notation. Thelocalization algorithmis applied. The formatting of the magnitudemdepends upon its value. Ifmis positive-zero or negative-zero, then the exponent will be"+00". Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. The formatting of the sign is described in thelocalization algorithm. The formatting of the magnitudemdepends upon its value. Letnbe the unique integer such that 10n<=m< 10n+1; then letabe the mathematically exact quotient ofmand 10nso that 1 <=a< 10. The magnitude is then represented as the integer part ofa, as a single decimal digit, followed by the decimal separator followed by decimal digits representing the fractional part ofa, followed by the exponent symbol'e'('\u0065'), followed by the sign of the exponent, followed by a representation ofnas a decimal integer, as produced by the methodLong.toString(long, int), and zero-padded to include at least two digits. The number of digits in the result for the fractional part ofmorais equal to the precision. If the precision is not specified then the default value is6. If the precision is less than the number of digits which would appear after the decimal point in the string returned byFloat.toString(float)orDouble.toString(double)respectively, then the value will be rounded using theround half up algorithm. Otherwise, zeros may be appended to reach the precision. For a canonical representation of the value, useBigDecimal.toString(). If the','flag is given, then anFormatFlagsConversionMismatchExceptionwill be thrown.
'E'	'\u0045'	The upper-case variant of'e'. The exponent symbol will be'E'('\u0045').
'g'	'\u0067'	Requires the output to be formatted in general scientific notation as described below. Thelocalization algorithmis applied. After rounding for the precision, the formatting of the resulting magnitudemdepends on its value. Ifmis greater than or equal to 10-4but less than 10precisionthen it is represented indecimal format. Ifmis less than 10-4or greater than or equal to 10precision, then it is represented incomputerized scientific notation. The total number of significant digits inmis equal to the precision. If the precision is not specified, then the default value is6. If the precision is0, then it is taken to be1. If the'#'flag is given then anFormatFlagsConversionMismatchExceptionwill be thrown.
'G'	'\u0047'	The upper-case variant of'g'.
'f'	'\u0066'	Requires the output to be formatted usingdecimal format. Thelocalization algorithmis applied. The result is a string that represents the sign and magnitude (absolute value) of the argument. The formatting of the sign is described in thelocalization algorithm. The formatting of the magnitudemdepends upon its value. The magnitude is formatted as the integer part ofm, with no leading zeroes, followed by the decimal separator followed by one or more decimal digits representing the fractional part ofm. The number of digits in the result for the fractional part ofmorais equal to the precision. If the precision is not specified then the default value is6. If the precision is less than the number of digits which would appear after the decimal point in the string returned byFloat.toString(float)orDouble.toString(double)respectively, then the value will be rounded using theround half up algorithm. Otherwise, zeros may be appended to reach the precision. For a canonical representation of the value, useBigDecimal.toString().

Allflagsdefined for Byte, Short, Integer, and Long apply.

If the'#'flag is given, then the decimal separator will always be present.

Thedefault behaviorwhen no flags are given is the same as for Float and Double.

The specification ofwidthandprecisionis the same as defined for Float and Double.

Date/Time

This conversion may be applied tolong,Long,Calendar, andDate.

't'	'\u0074'	Prefix for date and time conversion characters.
'T'	'\u0054'	The upper-case variant of't'.

The following date and time conversion character suffixes are defined for the't'and'T'conversions. The types are similar to but not completely identical to those defined by GNUdateand POSIXstrftime(3c). Additional conversion types are provided to access Java-specific functionality (e.g.'L'for milliseconds within the second).

The following conversion characters are used for formatting times:

'H'	'\u0048'	Hour of the day for the 24-hour clock, formatted as two digits with a leading zero as necessary i.e.00 - 23.00corresponds to midnight.
'I'	'\u0049'	Hour for the 12-hour clock, formatted as two digits with a leading zero as necessary, i.e.01 - 12.01corresponds to one o'clock (either morning or afternoon).
'k'	'\u006b'	Hour of the day for the 24-hour clock, i.e.0 - 23.0corresponds to midnight.
'l'	'\u006c'	Hour for the 12-hour clock, i.e.1 - 12.1corresponds to one o'clock (either morning or afternoon).
'M'	'\u004d'	Minute within the hour formatted as two digits with a leading zero as necessary, i.e.00 - 59.
'S'	'\u0053'	Seconds within the minute, formatted as two digits with a leading zero as necessary, i.e.00 - 60("60" is a special value required to support leap seconds).
'L'	'\u004c'	Millisecond within the second formatted as three digits with leading zeros as necessary, i.e.000 - 999.
'N'	'\u004e'	Nanosecond within the second, formatted as nine digits with leading zeros as necessary, i.e.000000000 - 999999999. The precision of this value is limited by the resolution of the underlying operating system or hardware.
'p'	'\u0070'	Locale-specificmorning or afternoonmarker in lower case, e.g."am" or "pm". Use of the conversion prefix'T'forces this output to upper case. (Note that'p'produces lower-case output. This is different from GNUdateand POSIXstrftime(3c)which produce upper-case output.)
'z'	'\u007a'	RFC822style numeric time zone offset from GMT, e.g.-0800.
'Z'	'\u005a'	A string representing the abbreviation for the time zone.
's'	'\u0073'	Seconds since the beginning of the epoch starting at 1 January 197000:00:00UTC, i.e.Long.MIN_VALUE/1000toLong.MAX_VALUE/1000.
'Q'	'\u004f'	Milliseconds since the beginning of the epoch starting at 1 January 197000:00:00UTC, i.e.Long.MIN_VALUEtoLong.MAX_VALUE. The precision of this value is limited by the resolution of the underlying operating system or hardware.

The following conversion characters are used for formatting dates:

'B'	'\u0042'	Locale-specificfull month name, e.g."January","February".
'b'	'\u0062'	Locale-specificabbreviated month name, e.g."Jan","Feb".
'h'	'\u0068'	Same as'b'.
'A'	'\u0041'	Locale-specific full name of theday of the week, e.g."Sunday","Monday"
'a'	'\u0061'	Locale-specific short name of theday of the week, e.g."Sun","Mon"
'C'	'\u0043'	Four-digit year divided by100, formatted as two digits with leading zero as necessary, i.e.00 - 99
'Y'	'\u0059'	Year, formatted to at least four digits with leading zeros as necessary, e.g.0092equals92CE for the Gregorian calendar.
'y'	'\u0079'	Last two digits of the year, formatted with leading zeros as necessary, i.e.00 - 99.
'j'	'\u006a'	Day of year, formatted as three digits with leading zeros as necessary, e.g.001 - 366for the Gregorian calendar.001corresponds to the first day of the year.
'm'	'\u006d'	Month, formatted as two digits with leading zeros as necessary, i.e.01 - 13, where "01" is the first month of the year and ("13" is a special value required to support lunar calendars).
'd'	'\u0064'	Day of month, formatted as two digits with leading zeros as necessary, i.e.01 - 31, where "01" is the first day of the month.
'e'	'\u0065'	Day of month, formatted as two digits, i.e.1 - 31where "1" is the first day of the month.

The following conversion characters are used for formatting common date/time compositions.

'R'	'\u0052'	Time formatted for the 24-hour clock as"%tH:%tM"
'T'	'\u0054'	Time formatted for the 24-hour clock as"%tH:%tM:%tS".
'r'	'\u0072'	Time formatted for the 12-hour clock as"%tI:%tM:%tS %Tp". The location of the morning or afternoon marker ('%Tp') may be locale-dependent.
'D'	'\u0044'	Date formatted as"%tm/%td/%ty".
'F'	'\u0046'	ISO8601complete date formatted as"%tY-%tm-%td".
'c'	'\u0063'	Date and time formatted as"%ta %tb %td %tT %tZ %tY", e.g."Sun Jul 20 16:17:00 EDT 1969".

The'-'flag defined forGeneral conversionsapplies. If the'#'flag is given, then aFormatFlagsConversionMismatchExceptionwill be thrown.

Thewidthis the minimum number of characters to be written to the output. If the length of the converted value is less than thewidththen the output will be padded by spaces ('\u0020') until the total number of characters equals width. The padding is on the left by default. If the'-'flag is given then the padding will be on the right. If width is not specified then there is no minimum.

The precision is not applicable. If the precision is specified then anIllegalFormatPrecisionExceptionwill be thrown.

Percent

The conversion does not correspond to any argument.

'%'

The result is a literal'%'('\u0025') Thewidthis the minimum number of characters to be written to the output including the'%'. If the length of the converted value is less than thewidththen the output will be padded by spaces ('\u0020') until the total number of characters equals width. The padding is on the left. If width is not specified then just the'%'is output. The'-'flag defined forGeneral conversionsapplies. If any other flags are provided, then aFormatFlagsConversionMismatchExceptionwill be thrown. The precision is not applicable. If the precision is specified anIllegalFormatPrecisionExceptionwill be thrown.

Line Separator

The conversion does not correspond to any argument.

'n'	the platform-specific line separator as returned bySystem.getProperty("line.separator").

Flags, width, and precision are not applicable. If any are provided anIllegalFormatFlagsException,IllegalFormatWidthException, andIllegalFormatPrecisionException, respectively will be thrown.

Argument Index

Format specifiers can reference arguments in three ways:

• Explicit indexingis used when the format specifier contains an argument index. The argument index is a decimal integer indicating the position of the argument in the argument list. The first argument is referenced by "1$", the second by "2$", etc. An argument may be referenced more than once.

  For example:

  formatter.format("%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s", "a", "b", "c", "d") // -> "d c b a d c b a"

• Relative indexingis used when the format specifier contains a'<'('\u003c') flag which causes the argument for the previous format specifier to be re-used. If there is no previous argument, then aMissingFormatArgumentExceptionis thrown.

  formatter.format("%s %s %<s %<s", "a", "b", "c", "d") // -> "a b b b" // "c" and "d" are ignored because they are not referenced

• Ordinary indexingis used when the format specifier contains neither an argument index nor a'<'flag. Each format specifier which uses ordinary indexing is assigned a sequential implicit index into argument list which is independent of the indices used by explicit or relative indexing.

  formatter.format("%s %s %s %s", "a", "b", "c", "d") // -> "a b c d"

It is possible to have a format string which uses all forms of indexing, for example:

formatter.format("%2$s %s %<s %s", "a", "b", "c", "d") // -> "b a a b" // "c" and "d" are ignored because they are not referenced

The maximum number of arguments is limited by the maximum dimension of a Java array as defined by theJava Virtual Machine Specification. If the argument index is does not correspond to an available argument, then aMissingFormatArgumentExceptionis thrown.

If there are more arguments than format specifiers, the extra arguments are ignored.

Unless otherwise specified, passing anullargument to any method or constructor in this class will cause aNullPointerExceptionto be thrown.

Since:

1.5

---

Nested Class Summary
staticclass	Formatter.BigDecimalLayoutForm

Constructor Summary
Formatter() Constructs a new formatter.
Formatter(Appendablea) Constructs a new formatter with the specified destination.
Formatter(Appendablea,Localel) Constructs a new formatter with the specified destination and locale.
Formatter(Filefile) Constructs a new formatter with the specified file.
Formatter(Filefile,Stringcsn) Constructs a new formatter with the specified file and charset.
Formatter(Filefile,Stringcsn,Localel) Constructs a new formatter with the specified file, charset, and locale.
Formatter(Localel) Constructs a new formatter with the specified locale.
Formatter(OutputStreamos) Constructs a new formatter with the specified output stream.
Formatter(OutputStreamos,Stringcsn) Constructs a new formatter with the specified output stream and charset.
Formatter(OutputStreamos,Stringcsn,Localel) Constructs a new formatter with the specified output stream, charset, and locale.
Formatter(PrintStreamps) Constructs a new formatter with the specified print stream.
Formatter(StringfileName) Constructs a new formatter with the specified file name.
Formatter(StringfileName,Stringcsn) Constructs a new formatter with the specified file name and charset.
Formatter(StringfileName,Stringcsn,Localel) Constructs a new formatter with the specified file name, charset, and locale.

Method Summary
void	close() Closes this formatter.
void	flush() Flushes this formatter.
Formatter	format(Localel,Stringformat,Object...args) Writes a formatted string to this object's destination using the specified locale, format string, and arguments.
Formatter	format(Stringformat,Object...args) Writes a formatted string to this object's destination using the specified format string and arguments.
IOException	ioException() Returns theIOExceptionlast thrown by this formatter'sAppendable.
Locale	locale() Returns the locale set by the construction of this formatter.
Appendable	out() Returns the destination for the output.
String	toString() Returns the result of invokingtoString()on the destination for the output.

Methods inherited from class java.lang.Object
clone,equals,finalize,getClass,hashCode,notify,notifyAll,wait,wait,wait

Constructor Detail

Formatter

publicFormatter()

Constructs a new formatter.

The destination of the formatted output is aStringBuilderwhich may be retrieved by invokingout()and whose current content may be converted into a string by invokingtoString(). The locale used is thedefault localefor this instance of the Java virtual machine.

---

Formatter

publicFormatter(Appendablea)

Constructs a new formatter with the specified destination.

The locale used is thedefault localefor this instance of the Java virtual machine.

Parameters:

a- Destination for the formatted output. Ifaisnullthen aStringBuilderwill be created.

---

Formatter

publicFormatter(Localel)

Constructs a new formatter with the specified locale.

The destination of the formatted output is aStringBuilderwhich may be retrieved by invokingout()and whose current content may be converted into a string by invokingtoString().

Parameters:

l- Thelocaleto apply during formatting. Iflisnullthen no localization is applied.

---

Formatter

publicFormatter(Appendablea,Localel)

Constructs a new formatter with the specified destination and locale.

Parameters:

a- Destination for the formatted output. Ifaisnullthen aStringBuilderwill be created.

l- Thelocaleto apply during formatting. Iflisnullthen no localization is applied.

---

Formatter

publicFormatter(StringfileName) throwsFileNotFoundException

Constructs a new formatter with the specified file name.

The charset used is thedefault charsetfor this instance of the Java virtual machine.

The locale used is thedefault localefor this instance of the Java virtual machine.

Parameters:

fileName- The name of the file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

Throws:

SecurityException- If a security manager is present andcheckWrite(fileName)denies write access to the file

FileNotFoundException- If the given file name does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

---

Formatter

publicFormatter(StringfileName,Stringcsn) throwsFileNotFoundException,UnsupportedEncodingException

Constructs a new formatter with the specified file name and charset.

The locale used is thedefault localefor this instance of the Java virtual machine.

Parameters:

fileName- The name of the file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

csn- The name of a supportedcharset

Throws:

FileNotFoundException- If the given file name does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

SecurityException- If a security manager is present andcheckWrite(fileName)denies write access to the file

UnsupportedEncodingException- If the named charset is not supported

---

Formatter

publicFormatter(StringfileName,Stringcsn,Localel) throwsFileNotFoundException,UnsupportedEncodingException

Constructs a new formatter with the specified file name, charset, and locale.

Parameters:

fileName- The name of the file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

csn- The name of a supportedcharset

l- Thelocaleto apply during formatting. Iflisnullthen no localization is applied.

Throws:

FileNotFoundException- If the given file name does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

SecurityException- If a security manager is present andcheckWrite(fileName)denies write access to the file

UnsupportedEncodingException- If the named charset is not supported

---

Formatter

publicFormatter(Filefile) throwsFileNotFoundException

Constructs a new formatter with the specified file.

The charset used is thedefault charsetfor this instance of the Java virtual machine.

The locale used is thedefault localefor this instance of the Java virtual machine.

Parameters:

file- The file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

Throws:

SecurityException- If a security manager is present andcheckWrite(file.getPath())denies write access to the file

FileNotFoundException- If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

---

Formatter

publicFormatter(Filefile,Stringcsn) throwsFileNotFoundException,UnsupportedEncodingException

Constructs a new formatter with the specified file and charset.

The locale used is thedefault localefor this instance of the Java virtual machine.

Parameters:

file- The file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

csn- The name of a supportedcharset

Throws:

FileNotFoundException- If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

SecurityException- If a security manager is present andcheckWrite(file.getPath())denies write access to the file

UnsupportedEncodingException- If the named charset is not supported

---

Formatter

publicFormatter(Filefile,Stringcsn,Localel) throwsFileNotFoundException,UnsupportedEncodingException

Constructs a new formatter with the specified file, charset, and locale.

Parameters:

file- The file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.

csn- The name of a supportedcharset

l- Thelocaleto apply during formatting. Iflisnullthen no localization is applied.

Throws:

FileNotFoundException- If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file

SecurityException- If a security manager is present andcheckWrite(file.getPath())denies write access to the file

UnsupportedEncodingException- If the named charset is not supported

---

Formatter

publicFormatter(PrintStreamps)

Constructs a new formatter with the specified print stream.

The locale used is thedefault localefor this instance of the Java virtual machine.

Characters are written to the givenPrintStreamobject and are therefore encoded using that object's charset.

Parameters:

ps- The stream to use as the destination of this formatter.

---

Formatter

publicFormatter(OutputStreamos)

Constructs a new formatter with the specified output stream.

The charset used is thedefault charsetfor this instance of the Java virtual machine.

The locale used is thedefault localefor this instance of the Java virtual machine.

Parameters:

os- The output stream to use as the destination of this formatter. The output will be buffered.

---

Formatter

publicFormatter(OutputStreamos,Stringcsn) throwsUnsupportedEncodingException

Constructs a new formatter with the specified output stream and charset.

The locale used is thedefault localefor this instance of the Java virtual machine.

Parameters:

os- The output stream to use as the destination of this formatter. The output will be buffered.

csn- The name of a supportedcharset

Throws:

UnsupportedEncodingException- If the named charset is not supported

---

Formatter

publicFormatter(OutputStreamos,Stringcsn,Localel) throwsUnsupportedEncodingException

Constructs a new formatter with the specified output stream, charset, and locale.

Parameters:

os- The output stream to use as the destination of this formatter. The output will be buffered.

csn- The name of a supportedcharset

l- Thelocaleto apply during formatting. Iflisnullthen no localization is applied.

Throws:

UnsupportedEncodingException- If the named charset is not supported

Method Detail

locale

publicLocalelocale()

Returns the locale set by the construction of this formatter.

Theformatmethod for this object which has a locale argument does not change this value.

Returns:

nullif no localization is applied, otherwise a locale

Throws:

FormatterClosedException- If this formatter has been closed by invoking itsclose()method

---

out

publicAppendableout()

Returns the destination for the output.

Returns:

The destination for the output

Throws:

FormatterClosedException- If this formatter has been closed by invoking itsclose()method

---

toString

publicStringtoString()

Returns the result of invokingtoString()on the destination for the output. For example, the following code formats text into aStringBuilderthen retrieves the resultant string:

Formatter f = new Formatter(); f.format("Last reboot at %tc", lastRebootDate); String s = f.toString(); // -> s == "Last reboot at Sat Jan 01 00:00:00 PST 2000"

An invocation of this method behaves in exactly the same way as the invocation

out().toString()

Depending on the specification oftoStringfor theAppendable, the returned string may or may not contain the characters written to the destination. For instance, buffers typically return their contents intoString(), but streams cannot since the data is discarded.

Overrides:

toStringin classObject

Returns:

The result of invokingtoString()on the destination for the output

Throws:

FormatterClosedException- If this formatter has been closed by invoking itsclose()method

---

flush

public voidflush()

Flushes this formatter. If the destination implements theFlushableinterface, itsflushmethod will be invoked.

Flushing a formatter writes any buffered output in the destination to the underlying stream.

Specified by:

flushin interfaceFlushable

Throws:

FormatterClosedException- If this formatter has been closed by invoking itsclose()method

---

close

public voidclose()

Closes this formatter. If the destination implements theCloseableinterface, itsclosemethod will be invoked.

Closing a formatter allows it to release resources it may be holding (such as open files). If the formatter is already closed, then invoking this method has no effect.

Attempting to invoke any methods exceptioException()in this formatter after it has been closed will result in aFormatterClosedException.

Specified by:

closein interfaceCloseable

---

ioException

publicIOExceptionioException()

Returns theIOExceptionlast thrown by this formatter'sAppendable.

If the destination'sappend()method never throwsIOException, then this method will always returnnull.

Returns:

The last exception thrown by the Appendable ornullif no such exception exists.

---

format

publicFormatterformat(Stringformat,Object...args)

Writes a formatted string to this object's destination using the specified format string and arguments. The locale used is the one defined during the construction of this formatter.

Parameters:

format- A format string as described inFormat string syntax.

args- Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by theJava Virtual Machine Specification.

Returns:

This formatter

Throws:

IllegalFormatException- If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see theDetailssection of the formatter class specification.

FormatterClosedException- If this formatter has been closed by invoking itsclose()method

---

format

publicFormatterformat(Localel,Stringformat,Object...args)

Writes a formatted string to this object's destination using the specified locale, format string, and arguments.

Parameters:

l- Thelocaleto apply during formatting. Iflisnullthen no localization is applied. This does not change this object's locale that was set during construction.

format- A format string as described inFormat string syntax

args- Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by theJava Virtual Machine Specification

Returns:

This formatter

Throws:

IllegalFormatException- If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see theDetailssection of the formatter class specification.

FormatterClosedException- If this formatter has been closed by invoking itsclose()method