42 import java.math.RoundingMode;
43 import java.nio.charset.Charset;
44 import java.text.DateFormatSymbols;
45 import java.text.DecimalFormat;
46 import java.text.DecimalFormatSymbols;
47 import java.text.NumberFormat;
48 import java.util.Calendar;
49 import java.util.Date;
50 import java.util.Locale;
51 import java.util.regex.Matcher;
52 import java.util.regex.Pattern;
53
54 import sun.misc.FpUtils;
55 import sun.misc.DoubleConsts;
56 import sun.misc.FormattedFloatingDecimal;
57
58 /**
59 * An interpreter for printf-style format strings. This class provides support
60 * for layout justification and alignment, common formats for numeric, string,
61 * and date/time data, and locale-specific output. Common Java types such as
62 * <tt>byte</tt>, {@link java.math.BigDecimal BigDecimal}, and {@link Calendar}
63 * are supported. Limited formatting customization for arbitrary user types is
64 * provided through the {@link Formattable} interface.
65 *
66 * <p> Formatters are not necessarily safe for multithreaded access. Thread
67 * safety is optional and is the responsibility of users of methods in this
68 * class.
69 *
70 * <p> Formatted printing for the Java language is heavily inspired by C's
71 * <tt>printf</tt>. Although the format strings are similar to C, some
72 * customizations have been made to accommodate the Java language and exploit
73 * some of its features. Also, Java formatting is more strict than C's; for
74 * example, if a conversion is incompatible with a flag, an exception will be
75 * thrown. In C inapplicable flags are silently ignored. The format strings
76 * are thus intended to be recognizable to C programmers but not necessarily
77 * completely compatible with those in C.
78 *
79 * <p> Examples of expected usage:
80 *
81 * <blockquote><pre>
82 * StringBuilder sb = new StringBuilder();
83 * // Send all output to the Appendable object sb
84 * Formatter formatter = new Formatter(sb, Locale.US);
85 *
86 * // Explicit argument indices may be used to re-order output.
87 * formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d")
88 * // -> " d c b a"
89 *
90 * // Optional locale as the first argument can be used to get
91 * // locale-specific formatting of numbers. The precision and width can be
98 * // automatically inserted.
99 * formatter.format("Amount gained or lost since last statement: $ %(,.2f",
100 * balanceDelta);
101 * // -> "Amount gained or lost since last statement: $ (6,217.58)"
102 * </pre></blockquote>
103 *
104 * <p> Convenience methods for common formatting requests exist as illustrated
105 * by the following invocations:
106 *
107 * <blockquote><pre>
108 * // Writes a formatted string to System.out.
109 * System.out.format("Local time: %tT", Calendar.getInstance());
110 * // -> "Local time: 13:34:18"
111 *
112 * // Writes formatted output to System.err.
113 * System.err.printf("Unable to open file '%1$s': %2$s",
114 * fileName, exception.getMessage());
115 * // -> "Unable to open file 'food': No such file or directory"
116 * </pre></blockquote>
117 *
118 * <p> Like C's <tt>sprintf(3)</tt>, Strings may be formatted using the static
119 * method {@link String#format(String,Object...) String.format}:
120 *
121 * <blockquote><pre>
122 * // Format a string containing a date.
123 * import java.util.Calendar;
124 * import java.util.GregorianCalendar;
125 * import static java.util.Calendar.*;
126 *
127 * Calendar c = new GregorianCalendar(1995, MAY, 23);
128 * String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
129 * // -> s == "Duke's Birthday: May 23, 1995"
130 * </pre></blockquote>
131 *
132 * <h3><a name="org">Organization</a></h3>
133 *
134 * <p> This specification is divided into two sections. The first section, <a
135 * href="#summary">Summary</a>, covers the basic formatting concepts. This
136 * section is intended for users who want to get started quickly and are
137 * familiar with formatted printing in other programming languages. The second
138 * section, <a href="#detail">Details</a>, covers the specific implementation
140 * formatting behavior.
141 *
142 * <h3><a name="summary">Summary</a></h3>
143 *
144 * <p> This section is intended to provide a brief overview of formatting
145 * concepts. For precise behavioral details, refer to the <a
146 * href="#detail">Details</a> section.
147 *
148 * <h4><a name="syntax">Format String Syntax</a></h4>
149 *
150 * <p> Every method which produces formatted output requires a <i>format
151 * string</i> and an <i>argument list</i>. The format string is a {@link
152 * String} which may contain fixed text and one or more embedded <i>format
153 * specifiers</i>. Consider the following example:
154 *
155 * <blockquote><pre>
156 * Calendar c = ...;
157 * String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
158 * </pre></blockquote>
159 *
160 * This format string is the first argument to the <tt>format</tt> method. It
161 * contains three format specifiers "<tt>%1$tm</tt>", "<tt>%1$te</tt>", and
162 * "<tt>%1$tY</tt>" which indicate how the arguments should be processed and
163 * where they should be inserted in the text. The remaining portions of the
164 * format string are fixed text including <tt>"Dukes Birthday: "</tt> and any
165 * other spaces or punctuation.
166 *
167 * The argument list consists of all arguments passed to the method after the
168 * format string. In the above example, the argument list is of size one and
169 * consists of the {@link java.util.Calendar Calendar} object <tt>c</tt>.
170 *
171 * <ul>
172 *
173 * <li> The format specifiers for general, character, and numeric types have
174 * the following syntax:
175 *
176 * <blockquote><pre>
177 * %[argument_index$][flags][width][.precision]conversion
178 * </pre></blockquote>
179 *
180 * <p> The optional <i>argument_index</i> is a decimal integer indicating the
181 * position of the argument in the argument list. The first argument is
182 * referenced by "<tt>1$</tt>", the second by "<tt>2$</tt>", etc.
183 *
184 * <p> The optional <i>flags</i> is a set of characters that modify the output
185 * format. The set of valid flags depends on the conversion.
186 *
187 * <p> The optional <i>width</i> is a non-negative decimal integer indicating
188 * the minimum number of characters to be written to the output.
189 *
190 * <p> The optional <i>precision</i> is a non-negative decimal integer usually
191 * used to restrict the number of characters. The specific behavior depends on
192 * the conversion.
193 *
194 * <p> The required <i>conversion</i> is a character indicating how the
195 * argument should be formatted. The set of valid conversions for a given
196 * argument depends on the argument's data type.
197 *
198 * <li> The format specifiers for types which are used to represents dates and
199 * times have the following syntax:
200 *
201 * <blockquote><pre>
202 * %[argument_index$][flags][width]conversion
203 * </pre></blockquote>
204 *
205 * <p> The optional <i>argument_index</i>, <i>flags</i> and <i>width</i> are
206 * defined as above.
207 *
208 * <p> The required <i>conversion</i> is a two character sequence. The first
209 * character is <tt>'t'</tt> or <tt>'T'</tt>. The second character indicates
210 * the format to be used. These characters are similar to but not completely
211 * identical to those defined by GNU <tt>date</tt> and POSIX
212 * <tt>strftime(3c)</tt>.
213 *
214 * <li> The format specifiers which do not correspond to arguments have the
215 * following syntax:
216 *
217 * <blockquote><pre>
218 * %[flags][width]conversion
219 * </pre></blockquote>
220 *
221 * <p> The optional <i>flags</i> and <i>width</i> is defined as above.
222 *
223 * <p> The required <i>conversion</i> is a character indicating content to be
224 * inserted in the output.
225 *
226 * </ul>
227 *
228 * <h4> Conversions </h4>
229 *
230 * <p> Conversions are divided into the following categories:
231 *
232 * <ol>
233 *
234 * <li> <b>General</b> - may be applied to any argument
235 * type
236 *
237 * <li> <b>Character</b> - may be applied to basic types which represent
238 * Unicode characters: <tt>char</tt>, {@link Character}, <tt>byte</tt>, {@link
239 * Byte}, <tt>short</tt>, and {@link Short}. This conversion may also be
240 * applied to the types <tt>int</tt> and {@link Integer} when {@link
241 * Character#isValidCodePoint} returns <tt>true</tt>
242 *
243 * <li> <b>Numeric</b>
244 *
245 * <ol>
246 *
247 * <li> <b>Integral</b> - may be applied to Java integral types: <tt>byte</tt>,
248 * {@link Byte}, <tt>short</tt>, {@link Short}, <tt>int</tt> and {@link
249 * Integer}, <tt>long</tt>, {@link Long}, and {@link java.math.BigInteger
250 * BigInteger}
251 *
252 * <li><b>Floating Point</b> - may be applied to Java floating-point types:
253 * <tt>float</tt>, {@link Float}, <tt>double</tt>, {@link Double}, and {@link
254 * java.math.BigDecimal BigDecimal}
255 *
256 * </ol>
257 *
258 * <li> <b>Date/Time</b> - may be applied to Java types which are capable of
259 * encoding a date or time: <tt>long</tt>, {@link Long}, {@link Calendar}, and
260 * {@link Date}.
261 *
262 * <li> <b>Percent</b> - produces a literal <tt>'%'</tt>
263 * (<tt>'\u0025'</tt>)
264 *
265 * <li> <b>Line Separator</b> - produces the platform-specific line separator
266 *
267 * </ol>
268 *
269 * <p> The following table summarizes the supported conversions. Conversions
270 * denoted by an upper-case character (i.e. <tt>'B'</tt>, <tt>'H'</tt>,
271 * <tt>'S'</tt>, <tt>'C'</tt>, <tt>'X'</tt>, <tt>'E'</tt>, <tt>'G'</tt>,
272 * <tt>'A'</tt>, and <tt>'T'</tt>) are the same as those for the corresponding
273 * lower-case conversion characters except that the result is converted to
274 * upper case according to the rules of the prevailing {@link java.util.Locale
275 * Locale}. The result is equivalent to the following invocation of {@link
276 * String#toUpperCase()}
277 *
278 * <pre>
279 * out.toUpperCase() </pre>
280 *
281 * <table cellpadding=5 summary="genConv">
282 *
283 * <tr><th valign="bottom"> Conversion
284 * <th valign="bottom"> Argument Category
285 * <th valign="bottom"> Description
286 *
287 * <tr><td valign="top"> <tt>'b'</tt>, <tt>'B'</tt>
288 * <td valign="top"> general
289 * <td> If the argument <i>arg</i> is <tt>null</tt>, then the result is
290 * "<tt>false</tt>". If <i>arg</i> is a <tt>boolean</tt> or {@link
291 * Boolean}, then the result is the string returned by {@link
292 * String#valueOf(boolean) String.valueOf(arg)}. Otherwise, the result is
293 * "true".
294 *
295 * <tr><td valign="top"> <tt>'h'</tt>, <tt>'H'</tt>
296 * <td valign="top"> general
297 * <td> If the argument <i>arg</i> is <tt>null</tt>, then the result is
298 * "<tt>null</tt>". Otherwise, the result is obtained by invoking
299 * <tt>Integer.toHexString(arg.hashCode())</tt>.
300 *
301 * <tr><td valign="top"> <tt>'s'</tt>, <tt>'S'</tt>
302 * <td valign="top"> general
303 * <td> If the argument <i>arg</i> is <tt>null</tt>, then the result is
304 * "<tt>null</tt>". If <i>arg</i> implements {@link Formattable}, then
305 * {@link Formattable#formatTo arg.formatTo} is invoked. Otherwise, the
306 * result is obtained by invoking <tt>arg.toString()</tt>.
307 *
308 * <tr><td valign="top"><tt>'c'</tt>, <tt>'C'</tt>
309 * <td valign="top"> character
310 * <td> The result is a Unicode character
311 *
312 * <tr><td valign="top"><tt>'d'</tt>
313 * <td valign="top"> integral
314 * <td> The result is formatted as a decimal integer
315 *
316 * <tr><td valign="top"><tt>'o'</tt>
317 * <td valign="top"> integral
318 * <td> The result is formatted as an octal integer
319 *
320 * <tr><td valign="top"><tt>'x'</tt>, <tt>'X'</tt>
321 * <td valign="top"> integral
322 * <td> The result is formatted as a hexadecimal integer
323 *
324 * <tr><td valign="top"><tt>'e'</tt>, <tt>'E'</tt>
325 * <td valign="top"> floating point
326 * <td> The result is formatted as a decimal number in computerized
327 * scientific notation
328 *
329 * <tr><td valign="top"><tt>'f'</tt>
330 * <td valign="top"> floating point
331 * <td> The result is formatted as a decimal number
332 *
333 * <tr><td valign="top"><tt>'g'</tt>, <tt>'G'</tt>
334 * <td valign="top"> floating point
335 * <td> The result is formatted using computerized scientific notation or
336 * decimal format, depending on the precision and the value after rounding.
337 *
338 * <tr><td valign="top"><tt>'a'</tt>, <tt>'A'</tt>
339 * <td valign="top"> floating point
340 * <td> The result is formatted as a hexadecimal floating-point number with
341 * a significand and an exponent
342 *
343 * <tr><td valign="top"><tt>'t'</tt>, <tt>'T'</tt>
344 * <td valign="top"> date/time
345 * <td> Prefix for date and time conversion characters. See <a
346 * href="#dt">Date/Time Conversions</a>.
347 *
348 * <tr><td valign="top"><tt>'%'</tt>
349 * <td valign="top"> percent
350 * <td> The result is a literal <tt>'%'</tt> (<tt>'\u0025'</tt>)
351 *
352 * <tr><td valign="top"><tt>'n'</tt>
353 * <td valign="top"> line separator
354 * <td> The result is the platform-specific line separator
355 *
356 * </table>
357 *
358 * <p> Any characters not explicitly defined as conversions are illegal and are
359 * reserved for future extensions.
360 *
361 * <h4><a name="dt">Date/Time Conversions</a></h4>
362 *
363 * <p> The following date and time conversion suffix characters are defined for
364 * the <tt>'t'</tt> and <tt>'T'</tt> conversions. The types are similar to but
365 * not completely identical to those defined by GNU <tt>date</tt> and POSIX
366 * <tt>strftime(3c)</tt>. Additional conversion types are provided to access
367 * Java-specific functionality (e.g. <tt>'L'</tt> for milliseconds within the
368 * second).
369 *
370 * <p> The following conversion characters are used for formatting times:
371 *
372 * <table cellpadding=5 summary="time">
373 *
374 * <tr><td valign="top"> <tt>'H'</tt>
375 * <td> Hour of the day for the 24-hour clock, formatted as two digits with
376 * a leading zero as necessary i.e. <tt>00 - 23</tt>.
377 *
378 * <tr><td valign="top"><tt>'I'</tt>
379 * <td> Hour for the 12-hour clock, formatted as two digits with a leading
380 * zero as necessary, i.e. <tt>01 - 12</tt>.
381 *
382 * <tr><td valign="top"><tt>'k'</tt>
383 * <td> Hour of the day for the 24-hour clock, i.e. <tt>0 - 23</tt>.
384 *
385 * <tr><td valign="top"><tt>'l'</tt>
386 * <td> Hour for the 12-hour clock, i.e. <tt>1 - 12</tt>.
387 *
388 * <tr><td valign="top"><tt>'M'</tt>
389 * <td> Minute within the hour formatted as two digits with a leading zero
390 * as necessary, i.e. <tt>00 - 59</tt>.
391 *
392 * <tr><td valign="top"><tt>'S'</tt>
393 * <td> Seconds within the minute, formatted as two digits with a leading
394 * zero as necessary, i.e. <tt>00 - 60</tt> ("<tt>60</tt>" is a special
395 * value required to support leap seconds).
396 *
397 * <tr><td valign="top"><tt>'L'</tt>
398 * <td> Millisecond within the second formatted as three digits with
399 * leading zeros as necessary, i.e. <tt>000 - 999</tt>.
400 *
401 * <tr><td valign="top"><tt>'N'</tt>
402 * <td> Nanosecond within the second, formatted as nine digits with leading
403 * zeros as necessary, i.e. <tt>000000000 - 999999999</tt>.
404 *
405 * <tr><td valign="top"><tt>'p'</tt>
406 * <td> Locale-specific {@linkplain
407 * java.text.DateFormatSymbols#getAmPmStrings morning or afternoon} marker
408 * in lower case, e.g."<tt>am</tt>" or "<tt>pm</tt>". Use of the conversion
409 * prefix <tt>'T'</tt> forces this output to upper case.
410 *
411 * <tr><td valign="top"><tt>'z'</tt>
412 * <td> <a href="http://www.ietf.org/rfc/rfc0822.txt">RFC 822</a>
413 * style numeric time zone offset from GMT, e.g. <tt>-0800</tt>. This
414 * value will be adjusted as necessary for Daylight Saving Time. For
415 * <tt>long</tt>, {@link Long}, and {@link Date} the time zone used is
416 * the {@plainlink TimeZone#getDefault() default time zone} for this
417 * instance of the Java virtual machine.
418 *
419 * <tr><td valign="top"><tt>'Z'</tt>
420 * <td> A string representing the abbreviation for the time zone. This
421 * value will be adjusted as necessary for Daylight Saving Time. For
422 * <tt>long</tt>, {@link Long}, and {@link Date} the time zone used is
423 * the {@plainlink TimeZone#getDefault() default time zone} for this
424 * instance of the Java virtual machine. The Formatter's locale will
425 * supersede the locale of the argument (if any).
426 *
427 * <tr><td valign="top"><tt>'s'</tt>
428 * <td> Seconds since the beginning of the epoch starting at 1 January 1970
429 * <tt>00:00:00</tt> UTC, i.e. <tt>Long.MIN_VALUE/1000</tt> to
430 * <tt>Long.MAX_VALUE/1000</tt>.
431 *
432 * <tr><td valign="top"><tt>'Q'</tt>
433 * <td> Milliseconds since the beginning of the epoch starting at 1 January
434 * 1970 <tt>00:00:00</tt> UTC, i.e. <tt>Long.MIN_VALUE</tt> to
435 * <tt>Long.MAX_VALUE</tt>.
436 *
437 * </table>
438 *
439 * <p> The following conversion characters are used for formatting dates:
440 *
441 * <table cellpadding=5 summary="date">
442 *
443 * <tr><td valign="top"><tt>'B'</tt>
444 * <td> Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths
445 * full month name}, e.g. <tt>"January"</tt>, <tt>"February"</tt>.
446 *
447 * <tr><td valign="top"><tt>'b'</tt>
448 * <td> Locale-specific {@linkplain
449 * java.text.DateFormatSymbols#getShortMonths abbreviated month name},
450 * e.g. <tt>"Jan"</tt>, <tt>"Feb"</tt>.
451 *
452 * <tr><td valign="top"><tt>'h'</tt>
453 * <td> Same as <tt>'b'</tt>.
454 *
455 * <tr><td valign="top"><tt>'A'</tt>
456 * <td> Locale-specific full name of the {@linkplain
457 * java.text.DateFormatSymbols#getWeekdays day of the week},
458 * e.g. <tt>"Sunday"</tt>, <tt>"Monday"</tt>
459 *
460 * <tr><td valign="top"><tt>'a'</tt>
461 * <td> Locale-specific short name of the {@linkplain
462 * java.text.DateFormatSymbols#getShortWeekdays day of the week},
463 * e.g. <tt>"Sun"</tt>, <tt>"Mon"</tt>
464 *
465 * <tr><td valign="top"><tt>'C'</tt>
466 * <td> Four-digit year divided by <tt>100</tt>, formatted as two digits
467 * with leading zero as necessary, i.e. <tt>00 - 99</tt>
468 *
469 * <tr><td valign="top"><tt>'Y'</tt>
470 * <td> Year, formatted as at least four digits with leading zeros as
471 * necessary, e.g. <tt>0092</tt> equals <tt>92</tt> CE for the Gregorian
472 * calendar.
473 *
474 * <tr><td valign="top"><tt>'y'</tt>
475 * <td> Last two digits of the year, formatted with leading zeros as
476 * necessary, i.e. <tt>00 - 99</tt>.
477 *
478 * <tr><td valign="top"><tt>'j'</tt>
479 * <td> Day of year, formatted as three digits with leading zeros as
480 * necessary, e.g. <tt>001 - 366</tt> for the Gregorian calendar.
481 *
482 * <tr><td valign="top"><tt>'m'</tt>
483 * <td> Month, formatted as two digits with leading zeros as necessary,
484 * i.e. <tt>01 - 13</tt>.
485 *
486 * <tr><td valign="top"><tt>'d'</tt>
487 * <td> Day of month, formatted as two digits with leading zeros as
488 * necessary, i.e. <tt>01 - 31</tt>
489 *
490 * <tr><td valign="top"><tt>'e'</tt>
491 * <td> Day of month, formatted as two digits, i.e. <tt>1 - 31</tt>.
492 *
493 * </table>
494 *
495 * <p> The following conversion characters are used for formatting common
496 * date/time compositions.
497 *
498 * <table cellpadding=5 summary="composites">
499 *
500 * <tr><td valign="top"><tt>'R'</tt>
501 * <td> Time formatted for the 24-hour clock as <tt>"%tH:%tM"</tt>
502 *
503 * <tr><td valign="top"><tt>'T'</tt>
504 * <td> Time formatted for the 24-hour clock as <tt>"%tH:%tM:%tS"</tt>.
505 *
506 * <tr><td valign="top"><tt>'r'</tt>
507 * <td> Time formatted for the 12-hour clock as <tt>"%tI:%tM:%tS %Tp"</tt>.
508 * The location of the morning or afternoon marker (<tt>'%Tp'</tt>) may be
509 * locale-dependent.
510 *
511 * <tr><td valign="top"><tt>'D'</tt>
512 * <td> Date formatted as <tt>"%tm/%td/%ty"</tt>.
513 *
514 * <tr><td valign="top"><tt>'F'</tt>
515 * <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a>
516 * complete date formatted as <tt>"%tY-%tm-%td"</tt>.
517 *
518 * <tr><td valign="top"><tt>'c'</tt>
519 * <td> Date and time formatted as <tt>"%ta %tb %td %tT %tZ %tY"</tt>,
520 * e.g. <tt>"Sun Jul 20 16:17:00 EDT 1969"</tt>.
521 *
522 * </table>
523 *
524 * <p> Any characters not explicitly defined as date/time conversion suffixes
525 * are illegal and are reserved for future extensions.
526 *
527 * <h4> Flags </h4>
528 *
529 * <p> The following table summarizes the supported flags. <i>y</i> means the
530 * flag is supported for the indicated argument types.
531 *
532 * <table cellpadding=5 summary="genConv">
533 *
534 * <tr><th valign="bottom"> Flag <th valign="bottom"> General
535 * <th valign="bottom"> Character <th valign="bottom"> Integral
536 * <th valign="bottom"> Floating Point
537 * <th valign="bottom"> Date/Time
538 * <th valign="bottom"> Description
539 *
540 * <tr><td> '-' <td align="center" valign="top"> y
574 *
575 * <tr><td> ',' <td align="center" valign="top"> -
576 * <td align="center" valign="top"> -
577 * <td align="center" valign="top"> y<sup>2</sup>
578 * <td align="center" valign="top"> y<sup>5</sup>
579 * <td align="center" valign="top"> -
580 * <td> The result will include locale-specific {@linkplain
581 * java.text.DecimalFormatSymbols#getGroupingSeparator grouping separators}
582 *
583 * <tr><td> '(' <td align="center" valign="top"> -
584 * <td align="center" valign="top"> -
585 * <td align="center" valign="top"> y<sup>4</sup>
586 * <td align="center" valign="top"> y<sup>5</sup>
587 * <td align="center"> -
588 * <td> The result will enclose negative numbers in parentheses
589 *
590 * </table>
591 *
592 * <p> <sup>1</sup> Depends on the definition of {@link Formattable}.
593 *
594 * <p> <sup>2</sup> For <tt>'d'</tt> conversion only.
595 *
596 * <p> <sup>3</sup> For <tt>'o'</tt>, <tt>'x'</tt>, and <tt>'X'</tt>
597 * conversions only.
598 *
599 * <p> <sup>4</sup> For <tt>'d'</tt>, <tt>'o'</tt>, <tt>'x'</tt>, and
600 * <tt>'X'</tt> conversions applied to {@link java.math.BigInteger BigInteger}
601 * or <tt>'d'</tt> applied to <tt>byte</tt>, {@link Byte}, <tt>short</tt>, {@link
602 * Short}, <tt>int</tt> and {@link Integer}, <tt>long</tt>, and {@link Long}.
603 *
604 * <p> <sup>5</sup> For <tt>'e'</tt>, <tt>'E'</tt>, <tt>'f'</tt>,
605 * <tt>'g'</tt>, and <tt>'G'</tt> conversions only.
606 *
607 * <p> Any characters not explicitly defined as flags are illegal and are
608 * reserved for future extensions.
609 *
610 * <h4> Width </h4>
611 *
612 * <p> The width is the minimum number of characters to be written to the
613 * output. For the line separator conversion, width is not applicable; if it
614 * is provided, an exception will be thrown.
615 *
616 * <h4> Precision </h4>
617 *
618 * <p> For general argument types, the precision is the maximum number of
619 * characters to be written to the output.
620 *
621 * <p> For the floating-point conversions <tt>'e'</tt>, <tt>'E'</tt>, and
622 * <tt>'f'</tt> the precision is the number of digits after the decimal
623 * separator. If the conversion is <tt>'g'</tt> or <tt>'G'</tt>, then the
624 * precision is the total number of digits in the resulting magnitude after
625 * rounding. If the conversion is <tt>'a'</tt> or <tt>'A'</tt>, then the
626 * precision must not be specified.
627 *
628 * <p> For character, integral, and date/time argument types and the percent
629 * and line separator conversions, the precision is not applicable; if a
630 * precision is provided, an exception will be thrown.
631 *
632 * <h4> Argument Index </h4>
633 *
634 * <p> The argument index is a decimal integer indicating the position of the
635 * argument in the argument list. The first argument is referenced by
636 * "<tt>1$</tt>", the second by "<tt>2$</tt>", etc.
637 *
638 * <p> Another way to reference arguments by position is to use the
639 * <tt>'<'</tt> (<tt>'\u003c'</tt>) flag, which causes the argument for
640 * the previous format specifier to be re-used. For example, the following two
641 * statements would produce identical strings:
642 *
643 * <blockquote><pre>
644 * Calendar c = ...;
645 * String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
646 *
647 * String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c);
648 * </pre></blockquote>
649 *
650 * <hr>
651 * <h3><a name="detail">Details</a></h3>
652 *
653 * <p> This section is intended to provide behavioral details for formatting,
654 * including conditions and exceptions, supported data types, localization, and
655 * interactions between flags, conversions, and data types. For an overview of
656 * formatting concepts, refer to the <a href="#summary">Summary</a>
657 *
658 * <p> Any characters not explicitly defined as conversions, date/time
659 * conversion suffixes, or flags are illegal and are reserved for
660 * future extensions. Use of such a character in a format string will
661 * cause an {@link UnknownFormatConversionException} or {@link
662 * UnknownFormatFlagsException} to be thrown.
663 *
664 * <p> If the format specifier contains a width or precision with an invalid
665 * value or which is otherwise unsupported, then a {@link
666 * IllegalFormatWidthException} or {@link IllegalFormatPrecisionException}
667 * respectively will be thrown.
668 *
669 * <p> If a format specifier contains a conversion character that is not
670 * applicable to the corresponding argument, then an {@link
671 * IllegalFormatConversionException} will be thrown.
672 *
673 * <p> All specified exceptions may be thrown by any of the <tt>format</tt>
674 * methods of <tt>Formatter</tt> as well as by any <tt>format</tt> convenience
675 * methods such as {@link String#format(String,Object...) String.format} and
676 * {@link java.io.PrintStream#printf(String,Object...) PrintStream.printf}.
677 *
678 * <p> Conversions denoted by an upper-case character (i.e. <tt>'B'</tt>,
679 * <tt>'H'</tt>, <tt>'S'</tt>, <tt>'C'</tt>, <tt>'X'</tt>, <tt>'E'</tt>,
680 * <tt>'G'</tt>, <tt>'A'</tt>, and <tt>'T'</tt>) are the same as those for the
681 * corresponding lower-case conversion characters except that the result is
682 * converted to upper case according to the rules of the prevailing {@link
683 * java.util.Locale Locale}. The result is equivalent to the following
684 * invocation of {@link String#toUpperCase()}
685 *
686 * <pre>
687 * out.toUpperCase() </pre>
688 *
689 * <h4><a name="dgen">General</a></h4>
690 *
691 * <p> The following general conversions may be applied to any argument type:
692 *
693 * <table cellpadding=5 summary="dgConv">
694 *
695 * <tr><td valign="top"> <tt>'b'</tt>
696 * <td valign="top"> <tt>'\u0062'</tt>
697 * <td> Produces either "<tt>true</tt>" or "<tt>false</tt>" as returned by
698 * {@link Boolean#toString(boolean)}.
699 *
700 * <p> If the argument is <tt>null</tt>, then the result is
701 * "<tt>false</tt>". If the argument is a <tt>boolean</tt> or {@link
702 * Boolean}, then the result is the string returned by {@link
703 * String#valueOf(boolean) String.valueOf()}. Otherwise, the result is
704 * "<tt>true</tt>".
705 *
706 * <p> If the <tt>'#'</tt> flag is given, then a {@link
707 * FormatFlagsConversionMismatchException} will be thrown.
708 *
709 * <tr><td valign="top"> <tt>'B'</tt>
710 * <td valign="top"> <tt>'\u0042'</tt>
711 * <td> The upper-case variant of <tt>'b'</tt>.
712 *
713 * <tr><td valign="top"> <tt>'h'</tt>
714 * <td valign="top"> <tt>'\u0068'</tt>
715 * <td> Produces a string representing the hash code value of the object.
716 *
717 * <p> If the argument, <i>arg</i> is <tt>null</tt>, then the
718 * result is "<tt>null</tt>". Otherwise, the result is obtained
719 * by invoking <tt>Integer.toHexString(arg.hashCode())</tt>.
720 *
721 * <p> If the <tt>'#'</tt> flag is given, then a {@link
722 * FormatFlagsConversionMismatchException} will be thrown.
723 *
724 * <tr><td valign="top"> <tt>'H'</tt>
725 * <td valign="top"> <tt>'\u0048'</tt>
726 * <td> The upper-case variant of <tt>'h'</tt>.
727 *
728 * <tr><td valign="top"> <tt>'s'</tt>
729 * <td valign="top"> <tt>'\u0073'</tt>
730 * <td> Produces a string.
731 *
732 * <p> If the argument is <tt>null</tt>, then the result is
733 * "<tt>null</tt>". If the argument implements {@link Formattable}, then
734 * its {@link Formattable#formatTo formatTo} method is invoked.
735 * Otherwise, the result is obtained by invoking the argument's
736 * <tt>toString()</tt> method.
737 *
738 * <p> If the <tt>'#'</tt> flag is given and the argument is not a {@link
739 * Formattable} , then a {@link FormatFlagsConversionMismatchException}
740 * will be thrown.
741 *
742 * <tr><td valign="top"> <tt>'S'</tt>
743 * <td valign="top"> <tt>'\u0053'</tt>
744 * <td> The upper-case variant of <tt>'s'</tt>.
745 *
746 * </table>
747 *
748 * <p> The following <a name="dFlags">flags</a> apply to general conversions:
749 *
750 * <table cellpadding=5 summary="dFlags">
751 *
752 * <tr><td valign="top"> <tt>'-'</tt>
753 * <td valign="top"> <tt>'\u002d'</tt>
754 * <td> Left justifies the output. Spaces (<tt>'\u0020'</tt>) will be
755 * added at the end of the converted value as required to fill the minimum
756 * width of the field. If the width is not provided, then a {@link
757 * MissingFormatWidthException} will be thrown. If this flag is not given
758 * then the output will be right-justified.
759 *
760 * <tr><td valign="top"> <tt>'#'</tt>
761 * <td valign="top"> <tt>'\u0023'</tt>
762 * <td> Requires the output use an alternate form. The definition of the
763 * form is specified by the conversion.
764 *
765 * </table>
766 *
767 * <p> The <a name="genWidth">width</a> is the minimum number of characters to
768 * be written to the
769 * output. If the length of the converted value is less than the width then
770 * the output will be padded by <tt>' '</tt> (<tt>\u0020'</tt>)
771 * until the total number of characters equals the width. The padding is on
772 * the left by default. If the <tt>'-'</tt> flag is given, then the padding
773 * will be on the right. If the width is not specified then there is no
774 * minimum.
775 *
776 * <p> The precision is the maximum number of characters to be written to the
777 * output. The precision is applied before the width, thus the output will be
778 * truncated to <tt>precision</tt> characters even if the width is greater than
779 * the precision. If the precision is not specified then there is no explicit
780 * limit on the number of characters.
781 *
782 * <h4><a name="dchar">Character</a></h4>
783 *
784 * This conversion may be applied to <tt>char</tt> and {@link Character}. It
785 * may also be applied to the types <tt>byte</tt>, {@link Byte},
786 * <tt>short</tt>, and {@link Short}, <tt>int</tt> and {@link Integer} when
787 * {@link Character#isValidCodePoint} returns <tt>true</tt>. If it returns
788 * <tt>false</tt> then an {@link IllegalFormatCodePointException} will be
789 * thrown.
790 *
791 * <table cellpadding=5 summary="charConv">
792 *
793 * <tr><td valign="top"> <tt>'c'</tt>
794 * <td valign="top"> <tt>'\u0063'</tt>
795 * <td> Formats the argument as a Unicode character as described in <a
796 * href="../lang/Character.html#unicode">Unicode Character
797 * Representation</a>. This may be more than one 16-bit <tt>char</tt> in
798 * the case where the argument represents a supplementary character.
799 *
800 * <p> If the <tt>'#'</tt> flag is given, then a {@link
801 * FormatFlagsConversionMismatchException} will be thrown.
802 *
803 * <tr><td valign="top"> <tt>'C'</tt>
804 * <td valign="top"> <tt>'\u0043'</tt>
805 * <td> The upper-case variant of <tt>'c'</tt>.
806 *
807 * </table>
808 *
809 * <p> The <tt>'-'</tt> flag defined for <a href="#dFlags">General
810 * conversions</a> applies. If the <tt>'#'</tt> flag is given, then a {@link
811 * FormatFlagsConversionMismatchException} will be thrown.
812 *
813 * <p> The width is defined as for <a href="#genWidth">General conversions</a>.
814 *
815 * <p> The precision is not applicable. If the precision is specified then an
816 * {@link IllegalFormatPrecisionException} will be thrown.
817 *
818 * <h4><a name="dnum">Numeric</a></h4>
819 *
820 * <p> Numeric conversions are divided into the following categories:
821 *
822 * <ol>
823 *
824 * <li> <a href="#dnint"><b>Byte, Short, Integer, and Long</b></a>
825 *
826 * <li> <a href="#dnbint"><b>BigInteger</b></a>
827 *
828 * <li> <a href="#dndec"><b>Float and Double</b></a>
829 *
830 * <li> <a href="#dndec"><b>BigDecimal</b></a>
831 *
832 * </ol>
833 *
834 * <p> Numeric types will be formatted according to the following algorithm:
835 *
836 * <p><b><a name="l10n algorithm"> Number Localization Algorithm</a></b>
837 *
838 * <p> After digits are obtained for the integer part, fractional part, and
839 * exponent (as appropriate for the data type), the following transformation
840 * is applied:
841 *
842 * <ol>
843 *
844 * <li> Each digit character <i>d</i> in the string is replaced by a
845 * locale-specific digit computed relative to the current locale's
846 * {@linkplain java.text.DecimalFormatSymbols#getZeroDigit() zero digit}
847 * <i>z</i>; that is <i>d - </i> <tt>'0'</tt>
848 * <i> + z</i>.
849 *
850 * <li> If a decimal separator is present, a locale-specific {@linkplain
851 * java.text.DecimalFormatSymbols#getDecimalSeparator decimal separator} is
852 * substituted.
853 *
854 * <li> If the <tt>','</tt> (<tt>'\u002c'</tt>)
855 * <a name="l10n group">flag</a> is given, then the locale-specific {@linkplain
856 * java.text.DecimalFormatSymbols#getGroupingSeparator grouping separator} is
857 * inserted by scanning the integer part of the string from least significant
858 * to most significant digits and inserting a separator at intervals defined by
859 * the locale's {@linkplain java.text.DecimalFormat#getGroupingSize() grouping
860 * size}.
861 *
862 * <li> If the <tt>'0'</tt> flag is given, then the locale-specific {@linkplain
863 * java.text.DecimalFormatSymbols#getZeroDigit() zero digits} are inserted
864 * after the sign character, if any, and before the first non-zero digit, until
865 * the length of the string is equal to the requested field width.
866 *
867 * <li> If the value is negative and the <tt>'('</tt> flag is given, then a
868 * <tt>'('</tt> (<tt>'\u0028'</tt>) is prepended and a <tt>')'</tt>
869 * (<tt>'\u0029'</tt>) is appended.
870 *
871 * <li> If the value is negative (or floating-point negative zero) and
872 * <tt>'('</tt> flag is not given, then a <tt>'-'</tt> (<tt>'\u002d'</tt>)
873 * is prepended.
874 *
875 * <li> If the <tt>'+'</tt> flag is given and the value is positive or zero (or
876 * floating-point positive zero), then a <tt>'+'</tt> (<tt>'\u002b'</tt>)
877 * will be prepended.
878 *
879 * </ol>
880 *
881 * <p> If the value is NaN or positive infinity the literal strings "NaN" or
882 * "Infinity" respectively, will be output. If the value is negative infinity,
883 * then the output will be "(Infinity)" if the <tt>'('</tt> flag is given
884 * otherwise the output will be "-Infinity". These values are not localized.
885 *
886 * <p><a name="dnint"><b> Byte, Short, Integer, and Long </b></a>
887 *
888 * <p> The following conversions may be applied to <tt>byte</tt>, {@link Byte},
889 * <tt>short</tt>, {@link Short}, <tt>int</tt> and {@link Integer},
890 * <tt>long</tt>, and {@link Long}.
891 *
892 * <table cellpadding=5 summary="IntConv">
893 *
894 * <tr><td valign="top"> <tt>'d'</tt>
895 * <td valign="top"> <tt>'\u0054'</tt>
896 * <td> Formats the argument as a decimal integer. The <a
897 * href="#l10n algorithm">localization algorithm</a> is applied.
898 *
899 * <p> If the <tt>'0'</tt> flag is given and the value is negative, then
900 * the zero padding will occur after the sign.
901 *
902 * <p> If the <tt>'#'</tt> flag is given then a {@link
903 * FormatFlagsConversionMismatchException} will be thrown.
904 *
905 * <tr><td valign="top"> <tt>'o'</tt>
906 * <td valign="top"> <tt>'\u006f'</tt>
907 * <td> Formats the argument as an integer in base eight. No localization
908 * is applied.
909 *
910 * <p> If <i>x</i> is negative then the result will be an unsigned value
911 * generated by adding 2<sup>n</sup> to the value where <tt>n</tt> is the
912 * number of bits in the type as returned by the static <tt>SIZE</tt> field
913 * in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short},
914 * {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long}
915 * classes as appropriate.
916 *
917 * <p> If the <tt>'#'</tt> flag is given then the output will always begin
918 * with the radix indicator <tt>'0'</tt>.
919 *
920 * <p> If the <tt>'0'</tt> flag is given then the output will be padded
921 * with leading zeros to the field width following any indication of sign.
922 *
923 * <p> If <tt>'('</tt>, <tt>'+'</tt>, '  ', or <tt>','</tt> flags
924 * are given then a {@link FormatFlagsConversionMismatchException} will be
925 * thrown.
926 *
927 * <tr><td valign="top"> <tt>'x'</tt>
928 * <td valign="top"> <tt>'\u0078'</tt>
929 * <td> Formats the argument as an integer in base sixteen. No
930 * localization is applied.
931 *
932 * <p> If <i>x</i> is negative then the result will be an unsigned value
933 * generated by adding 2<sup>n</sup> to the value where <tt>n</tt> is the
934 * number of bits in the type as returned by the static <tt>SIZE</tt> field
935 * in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short},
936 * {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long}
937 * classes as appropriate.
938 *
939 * <p> If the <tt>'#'</tt> flag is given then the output will always begin
940 * with the radix indicator <tt>"0x"</tt>.
941 *
942 * <p> If the <tt>'0'</tt> flag is given then the output will be padded to
943 * the field width with leading zeros after the radix indicator or sign (if
944 * present).
945 *
946 * <p> If <tt>'('</tt>, <tt>' '</tt>, <tt>'+'</tt>, or
947 * <tt>','</tt> flags are given then a {@link
948 * FormatFlagsConversionMismatchException} will be thrown.
949 *
950 * <tr><td valign="top"> <tt>'X'</tt>
951 * <td valign="top"> <tt>'\u0058'</tt>
952 * <td> The upper-case variant of <tt>'x'</tt>. The entire string
953 * representing the number will be converted to {@linkplain
954 * String#toUpperCase upper case} including the <tt>'x'</tt> (if any) and
955 * all hexadecimal digits <tt>'a'</tt> - <tt>'f'</tt>
956 * (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>).
957 *
958 * </table>
959 *
960 * <p> If the conversion is <tt>'o'</tt>, <tt>'x'</tt>, or <tt>'X'</tt> and
961 * both the <tt>'#'</tt> and the <tt>'0'</tt> flags are given, then result will
962 * contain the radix indicator (<tt>'0'</tt> for octal and <tt>"0x"</tt> or
963 * <tt>"0X"</tt> for hexadecimal), some number of zeros (based on the width),
964 * and the value.
965 *
966 * <p> If the <tt>'-'</tt> flag is not given, then the space padding will occur
967 * before the sign.
968 *
969 * <p> The following <a name="intFlags">flags</a> apply to numeric integral
970 * conversions:
971 *
972 * <table cellpadding=5 summary="intFlags">
973 *
974 * <tr><td valign="top"> <tt>'+'</tt>
975 * <td valign="top"> <tt>'\u002b'</tt>
976 * <td> Requires the output to include a positive sign for all positive
977 * numbers. If this flag is not given then only negative values will
978 * include a sign.
979 *
980 * <p> If both the <tt>'+'</tt> and <tt>' '</tt> flags are given
981 * then an {@link IllegalFormatFlagsException} will be thrown.
982 *
983 * <tr><td valign="top"> <tt>' '</tt>
984 * <td valign="top"> <tt>'\u0020'</tt>
985 * <td> Requires the output to include a single extra space
986 * (<tt>'\u0020'</tt>) for non-negative values.
987 *
988 * <p> If both the <tt>'+'</tt> and <tt>' '</tt> flags are given
989 * then an {@link IllegalFormatFlagsException} will be thrown.
990 *
991 * <tr><td valign="top"> <tt>'0'</tt>
992 * <td valign="top"> <tt>'\u0030'</tt>
993 * <td> Requires the output to be padded with leading {@linkplain
994 * java.text.DecimalFormatSymbols#getZeroDigit zeros} to the minimum field
995 * width following any sign or radix indicator except when converting NaN
996 * or infinity. If the width is not provided, then a {@link
997 * MissingFormatWidthException} will be thrown.
998 *
999 * <p> If both the <tt>'-'</tt> and <tt>'0'</tt> flags are given then an
1000 * {@link IllegalFormatFlagsException} will be thrown.
1001 *
1002 * <tr><td valign="top"> <tt>','</tt>
1003 * <td valign="top"> <tt>'\u002c'</tt>
1004 * <td> Requires the output to include the locale-specific {@linkplain
1005 * java.text.DecimalFormatSymbols#getGroupingSeparator group separators} as
1006 * described in the <a href="#l10n group">"group" section</a> of the
1007 * localization algorithm.
1008 *
1009 * <tr><td valign="top"> <tt>'('</tt>
1010 * <td valign="top"> <tt>'\u0028'</tt>
1011 * <td> Requires the output to prepend a <tt>'('</tt>
1012 * (<tt>'\u0028'</tt>) and append a <tt>')'</tt>
1013 * (<tt>'\u0029'</tt>) to negative values.
1014 *
1015 * </table>
1016 *
1017 * <p> If no <a name="intdFlags">flags</a> are given the default formatting is
1018 * as follows:
1019 *
1020 * <ul>
1021 *
1022 * <li> The output is right-justified within the <tt>width</tt>
1023 *
1024 * <li> Negative numbers begin with a <tt>'-'</tt> (<tt>'\u002d'</tt>)
1025 *
1026 * <li> Positive numbers and zero do not include a sign or extra leading
1027 * space
1028 *
1029 * <li> No grouping separators are included
1030 *
1031 * </ul>
1032 *
1033 * <p> The <a name="intWidth">width</a> is the minimum number of characters to
1034 * be written to the output. This includes any signs, digits, grouping
1035 * separators, radix indicator, and parentheses. If the length of the
1036 * converted value is less than the width then the output will be padded by
1037 * spaces (<tt>'\u0020'</tt>) until the total number of characters equals
1038 * width. The padding is on the left by default. If <tt>'-'</tt> flag is
1039 * given then the padding will be on the right. If width is not specified then
1040 * there is no minimum.
1041 *
1042 * <p> The precision is not applicable. If precision is specified then an
1043 * {@link IllegalFormatPrecisionException} will be thrown.
1044 *
1045 * <p><a name="dnbint"><b> BigInteger </b></a>
1046 *
1047 * <p> The following conversions may be applied to {@link
1048 * java.math.BigInteger}.
1049 *
1050 * <table cellpadding=5 summary="BIntConv">
1051 *
1052 * <tr><td valign="top"> <tt>'d'</tt>
1053 * <td valign="top"> <tt>'\u0054'</tt>
1054 * <td> Requires the output to be formatted as a decimal integer. The <a
1055 * href="#l10n algorithm">localization algorithm</a> is applied.
1056 *
1057 * <p> If the <tt>'#'</tt> flag is given {@link
1058 * FormatFlagsConversionMismatchException} will be thrown.
1059 *
1060 * <tr><td valign="top"> <tt>'o'</tt>
1061 * <td valign="top"> <tt>'\u006f'</tt>
1062 * <td> Requires the output to be formatted as an integer in base eight.
1063 * No localization is applied.
1064 *
1065 * <p> If <i>x</i> is negative then the result will be a signed value
1066 * beginning with <tt>'-'</tt> (<tt>'\u002d'</tt>). Signed output is
1067 * allowed for this type because unlike the primitive types it is not
1068 * possible to create an unsigned equivalent without assuming an explicit
1069 * data-type size.
1070 *
1071 * <p> If <i>x</i> is positive or zero and the <tt>'+'</tt> flag is given
1072 * then the result will begin with <tt>'+'</tt> (<tt>'\u002b'</tt>).
1073 *
1074 * <p> If the <tt>'#'</tt> flag is given then the output will always begin
1075 * with <tt>'0'</tt> prefix.
1076 *
1077 * <p> If the <tt>'0'</tt> flag is given then the output will be padded
1078 * with leading zeros to the field width following any indication of sign.
1079 *
1080 * <p> If the <tt>','</tt> flag is given then a {@link
1081 * FormatFlagsConversionMismatchException} will be thrown.
1082 *
1083 * <tr><td valign="top"> <tt>'x'</tt>
1084 * <td valign="top"> <tt>'\u0078'</tt>
1085 * <td> Requires the output to be formatted as an integer in base
1086 * sixteen. No localization is applied.
1087 *
1088 * <p> If <i>x</i> is negative then the result will be a signed value
1089 * beginning with <tt>'-'</tt> (<tt>'\u002d'</tt>). Signed output is
1090 * allowed for this type because unlike the primitive types it is not
1091 * possible to create an unsigned equivalent without assuming an explicit
1092 * data-type size.
1093 *
1094 * <p> If <i>x</i> is positive or zero and the <tt>'+'</tt> flag is given
1095 * then the result will begin with <tt>'+'</tt> (<tt>'\u002b'</tt>).
1096 *
1097 * <p> If the <tt>'#'</tt> flag is given then the output will always begin
1098 * with the radix indicator <tt>"0x"</tt>.
1099 *
1100 * <p> If the <tt>'0'</tt> flag is given then the output will be padded to
1101 * the field width with leading zeros after the radix indicator or sign (if
1102 * present).
1103 *
1104 * <p> If the <tt>','</tt> flag is given then a {@link
1105 * FormatFlagsConversionMismatchException} will be thrown.
1106 *
1107 * <tr><td valign="top"> <tt>'X'</tt>
1108 * <td valign="top"> <tt>'\u0058'</tt>
1109 * <td> The upper-case variant of <tt>'x'</tt>. The entire string
1110 * representing the number will be converted to {@linkplain
1111 * String#toUpperCase upper case} including the <tt>'x'</tt> (if any) and
1112 * all hexadecimal digits <tt>'a'</tt> - <tt>'f'</tt>
1113 * (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>).
1114 *
1115 * </table>
1116 *
1117 * <p> If the conversion is <tt>'o'</tt>, <tt>'x'</tt>, or <tt>'X'</tt> and
1118 * both the <tt>'#'</tt> and the <tt>'0'</tt> flags are given, then result will
1119 * contain the base indicator (<tt>'0'</tt> for octal and <tt>"0x"</tt> or
1120 * <tt>"0X"</tt> for hexadecimal), some number of zeros (based on the width),
1121 * and the value.
1122 *
1123 * <p> If the <tt>'0'</tt> flag is given and the value is negative, then the
1124 * zero padding will occur after the sign.
1125 *
1126 * <p> If the <tt>'-'</tt> flag is not given, then the space padding will occur
1127 * before the sign.
1128 *
1129 * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1130 * Long apply. The <a href="#intdFlags">default behavior</a> when no flags are
1131 * given is the same as for Byte, Short, Integer, and Long.
1132 *
1133 * <p> The specification of <a href="#intWidth">width</a> is the same as
1134 * defined for Byte, Short, Integer, and Long.
1135 *
1136 * <p> The precision is not applicable. If precision is specified then an
1137 * {@link IllegalFormatPrecisionException} will be thrown.
1138 *
1139 * <p><a name="dndec"><b> Float and Double</b></a>
1140 *
1141 * <p> The following conversions may be applied to <tt>float</tt>, {@link
1142 * Float}, <tt>double</tt> and {@link Double}.
1143 *
1144 * <table cellpadding=5 summary="floatConv">
1145 *
1146 * <tr><td valign="top"> <tt>'e'</tt>
1147 * <td valign="top"> <tt>'\u0065'</tt>
1148 * <td> Requires the output to be formatted using <a
1149 * name="scientific">computerized scientific notation</a>. The <a
1150 * href="#l10n algorithm">localization algorithm</a> is applied.
1151 *
1152 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1153 *
1154 * <p> If <i>m</i> is NaN or infinite, the literal strings "NaN" or
1155 * "Infinity", respectively, will be output. These values are not
1156 * localized.
1157 *
1158 * <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1159 * will be <tt>"+00"</tt>.
1160 *
1161 * <p> Otherwise, the result is a string that represents the sign and
1162 * magnitude (absolute value) of the argument. The formatting of the sign
1163 * is described in the <a href="#l10n algorithm">localization
1164 * algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1165 * value.
1166 *
1167 * <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
1168 * <= <i>m</i> < 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
1169 * mathematically exact quotient of <i>m</i> and 10<sup><i>n</i></sup> so
1170 * that 1 <= <i>a</i> < 10. The magnitude is then represented as the
1171 * integer part of <i>a</i>, as a single decimal digit, followed by the
1172 * decimal separator followed by decimal digits representing the fractional
1173 * part of <i>a</i>, followed by the exponent symbol <tt>'e'</tt>
1174 * (<tt>'\u0065'</tt>), followed by the sign of the exponent, followed
1175 * by a representation of <i>n</i> as a decimal integer, as produced by the
1176 * method {@link Long#toString(long, int)}, and zero-padded to include at
1177 * least two digits.
1178 *
1179 * <p> The number of digits in the result for the fractional part of
1180 * <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1181 * specified then the default value is <tt>6</tt>. If the precision is less
1182 * than the number of digits which would appear after the decimal point in
1183 * the string returned by {@link Float#toString(float)} or {@link
1184 * Double#toString(double)} respectively, then the value will be rounded
1185 * using the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1186 * algorithm}. Otherwise, zeros may be appended to reach the precision.
1187 * For a canonical representation of the value, use {@link
1188 * Float#toString(float)} or {@link Double#toString(double)} as
1189 * appropriate.
1190 *
1191 * <p>If the <tt>','</tt> flag is given, then an {@link
1192 * FormatFlagsConversionMismatchException} will be thrown.
1193 *
1194 * <tr><td valign="top"> <tt>'E'</tt>
1195 * <td valign="top"> <tt>'\u0045'</tt>
1196 * <td> The upper-case variant of <tt>'e'</tt>. The exponent symbol
1197 * will be <tt>'E'</tt> (<tt>'\u0045'</tt>).
1198 *
1199 * <tr><td valign="top"> <tt>'g'</tt>
1200 * <td valign="top"> <tt>'\u0067'</tt>
1201 * <td> Requires the output to be formatted in general scientific notation
1202 * as described below. The <a href="#l10n algorithm">localization
1203 * algorithm</a> is applied.
1204 *
1205 * <p> After rounding for the precision, the formatting of the resulting
1206 * magnitude <i>m</i> depends on its value.
1207 *
1208 * <p> If <i>m</i> is greater than or equal to 10<sup>-4</sup> but less
1209 * than 10<sup>precision</sup> then it is represented in <i><a
1210 * href="#decimal">decimal format</a></i>.
1211 *
1212 * <p> If <i>m</i> is less than 10<sup>-4</sup> or greater than or equal to
1213 * 10<sup>precision</sup>, then it is represented in <i><a
1214 * href="#scientific">computerized scientific notation</a></i>.
1215 *
1216 * <p> The total number of significant digits in <i>m</i> is equal to the
1217 * precision. If the precision is not specified, then the default value is
1218 * <tt>6</tt>. If the precision is <tt>0</tt>, then it is taken to be
1219 * <tt>1</tt>.
1220 *
1221 * <p> If the <tt>'#'</tt> flag is given then an {@link
1222 * FormatFlagsConversionMismatchException} will be thrown.
1223 *
1224 * <tr><td valign="top"> <tt>'G'</tt>
1225 * <td valign="top"> <tt>'\u0047'</tt>
1226 * <td> The upper-case variant of <tt>'g'</tt>.
1227 *
1228 * <tr><td valign="top"> <tt>'f'</tt>
1229 * <td valign="top"> <tt>'\u0066'</tt>
1230 * <td> Requires the output to be formatted using <a name="decimal">decimal
1231 * format</a>. The <a href="#l10n algorithm">localization algorithm</a> is
1232 * applied.
1233 *
1234 * <p> The result is a string that represents the sign and magnitude
1235 * (absolute value) of the argument. The formatting of the sign is
1236 * described in the <a href="#l10n algorithm">localization
1237 * algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1238 * value.
1239 *
1240 * <p> If <i>m</i> NaN or infinite, the literal strings "NaN" or
1241 * "Infinity", respectively, will be output. These values are not
1242 * localized.
1243 *
1244 * <p> The magnitude is formatted as the integer part of <i>m</i>, with no
1245 * leading zeroes, followed by the decimal separator followed by one or
1246 * more decimal digits representing the fractional part of <i>m</i>.
1247 *
1248 * <p> The number of digits in the result for the fractional part of
1249 * <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1250 * specified then the default value is <tt>6</tt>. If the precision is less
1251 * than the number of digits which would appear after the decimal point in
1252 * the string returned by {@link Float#toString(float)} or {@link
1253 * Double#toString(double)} respectively, then the value will be rounded
1254 * using the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1255 * algorithm}. Otherwise, zeros may be appended to reach the precision.
1256 * For a canonical representation of the value, use {@link
1257 * Float#toString(float)} or {@link Double#toString(double)} as
1258 * appropriate.
1259 *
1260 * <tr><td valign="top"> <tt>'a'</tt>
1261 * <td valign="top"> <tt>'\u0061'</tt>
1262 * <td> Requires the output to be formatted in hexadecimal exponential
1263 * form. No localization is applied.
1264 *
1265 * <p> The result is a string that represents the sign and magnitude
1266 * (absolute value) of the argument <i>x</i>.
1267 *
1268 * <p> If <i>x</i> is negative or a negative-zero value then the result
1269 * will begin with <tt>'-'</tt> (<tt>'\u002d'</tt>).
1270 *
1271 * <p> If <i>x</i> is positive or a positive-zero value and the
1272 * <tt>'+'</tt> flag is given then the result will begin with <tt>'+'</tt>
1273 * (<tt>'\u002b'</tt>).
1274 *
1275 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1276 *
1277 * <ul>
1278 *
1279 * <li> If the value is NaN or infinite, the literal strings "NaN" or
1280 * "Infinity", respectively, will be output.
1281 *
1282 * <li> If <i>m</i> is zero then it is represented by the string
1283 * <tt>"0x0.0p0"</tt>.
1284 *
1285 * <li> If <i>m</i> is a <tt>double</tt> value with a normalized
1286 * representation then substrings are used to represent the significand and
1287 * exponent fields. The significand is represented by the characters
1288 * <tt>"0x1."</tt> followed by the hexadecimal representation of the rest
1289 * of the significand as a fraction. The exponent is represented by
1290 * <tt>'p'</tt> (<tt>'\u0070'</tt>) followed by a decimal string of the
1291 * unbiased exponent as if produced by invoking {@link
1292 * Integer#toString(int) Integer.toString} on the exponent value.
1293 *
1294 * <li> If <i>m</i> is a <tt>double</tt> value with a subnormal
1295 * representation then the significand is represented by the characters
1296 * <tt>'0x0.'</tt> followed by the hexadecimal representation of the rest
1297 * of the significand as a fraction. The exponent is represented by
1298 * <tt>'p-1022'</tt>. Note that there must be at least one nonzero digit
1299 * in a subnormal significand.
1300 *
1301 * </ul>
1302 *
1303 * <p> If the <tt>'('</tt> or <tt>','</tt> flags are given, then a {@link
1304 * FormatFlagsConversionMismatchException} will be thrown.
1305 *
1306 * <tr><td valign="top"> <tt>'A'</tt>
1307 * <td valign="top"> <tt>'\u0041'</tt>
1308 * <td> The upper-case variant of <tt>'a'</tt>. The entire string
1309 * representing the number will be converted to upper case including the
1310 * <tt>'x'</tt> (<tt>'\u0078'</tt>) and <tt>'p'</tt>
1311 * (<tt>'\u0070'</tt> and all hexadecimal digits <tt>'a'</tt> -
1312 * <tt>'f'</tt> (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>).
1313 *
1314 * </table>
1315 *
1316 * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1317 * Long apply.
1318 *
1319 * <p> If the <tt>'#'</tt> flag is given, then the decimal separator will
1320 * always be present.
1321 *
1322 * <p> If no <a name="floatdFlags">flags</a> are given the default formatting
1323 * is as follows:
1324 *
1325 * <ul>
1326 *
1327 * <li> The output is right-justified within the <tt>width</tt>
1328 *
1329 * <li> Negative numbers begin with a <tt>'-'</tt>
1330 *
1331 * <li> Positive numbers and positive zero do not include a sign or extra
1332 * leading space
1333 *
1334 * <li> No grouping separators are included
1335 *
1336 * <li> The decimal separator will only appear if a digit follows it
1337 *
1338 * </ul>
1339 *
1340 * <p> The <a name="floatDWidth">width</a> is the minimum number of characters
1341 * to be written to the output. This includes any signs, digits, grouping
1342 * separators, decimal separators, exponential symbol, radix indicator,
1343 * parentheses, and strings representing infinity and NaN as applicable. If
1344 * the length of the converted value is less than the width then the output
1345 * will be padded by spaces (<tt>'\u0020'</tt>) until the total number of
1346 * characters equals width. The padding is on the left by default. If the
1347 * <tt>'-'</tt> flag is given then the padding will be on the right. If width
1348 * is not specified then there is no minimum.
1349 *
1350 * <p> If the <a name="floatDPrec">conversion</a> is <tt>'e'</tt>,
1351 * <tt>'E'</tt> or <tt>'f'</tt>, then the precision is the number of digits
1352 * after the decimal separator. If the precision is not specified, then it is
1353 * assumed to be <tt>6</tt>.
1354 *
1355 * <p> If the conversion is <tt>'g'</tt> or <tt>'G'</tt>, then the precision is
1356 * the total number of significant digits in the resulting magnitude after
1357 * rounding. If the precision is not specified, then the default value is
1358 * <tt>6</tt>. If the precision is <tt>0</tt>, then it is taken to be
1359 * <tt>1</tt>.
1360 *
1361 * <p> If the conversion is <tt>'a'</tt> or <tt>'A'</tt>, then the precision
1362 * is the number of hexadecimal digits after the decimal separator. If the
1363 * precision is not provided, then all of the digits as returned by {@link
1364 * Double#toHexString(double)} will be output.
1365 *
1366 * <p><a name="dndec"><b> BigDecimal </b></a>
1367 *
1368 * <p> The following conversions may be applied {@link java.math.BigDecimal
1369 * BigDecimal}.
1370 *
1371 * <table cellpadding=5 summary="floatConv">
1372 *
1373 * <tr><td valign="top"> <tt>'e'</tt>
1374 * <td valign="top"> <tt>'\u0065'</tt>
1375 * <td> Requires the output to be formatted using <a
1376 * name="scientific">computerized scientific notation</a>. The <a
1377 * href="#l10n algorithm">localization algorithm</a> is applied.
1378 *
1379 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1380 *
1381 * <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1382 * will be <tt>"+00"</tt>.
1383 *
1384 * <p> Otherwise, the result is a string that represents the sign and
1385 * magnitude (absolute value) of the argument. The formatting of the sign
1386 * is described in the <a href="#l10n algorithm">localization
1387 * algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1388 * value.
1389 *
1390 * <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
1391 * <= <i>m</i> < 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
1392 * mathematically exact quotient of <i>m</i> and 10<sup><i>n</i></sup> so
1393 * that 1 <= <i>a</i> < 10. The magnitude is then represented as the
1394 * integer part of <i>a</i>, as a single decimal digit, followed by the
1395 * decimal separator followed by decimal digits representing the fractional
1396 * part of <i>a</i>, followed by the exponent symbol <tt>'e'</tt>
1397 * (<tt>'\u0065'</tt>), followed by the sign of the exponent, followed
1398 * by a representation of <i>n</i> as a decimal integer, as produced by the
1399 * method {@link Long#toString(long, int)}, and zero-padded to include at
1400 * least two digits.
1401 *
1402 * <p> The number of digits in the result for the fractional part of
1403 * <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1404 * specified then the default value is <tt>6</tt>. If the precision is
1405 * less than the number of digits which would appear after the decimal
1406 * point in the string returned by {@link Float#toString(float)} or {@link
1407 * Double#toString(double)} respectively, then the value will be rounded
1408 * using the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1409 * algorithm}. Otherwise, zeros may be appended to reach the precision.
1410 * For a canonical representation of the value, use {@link
1411 * BigDecimal#toString()}.
1412 *
1413 * <p> If the <tt>','</tt> flag is given, then an {@link
1414 * FormatFlagsConversionMismatchException} will be thrown.
1415 *
1416 * <tr><td valign="top"> <tt>'E'</tt>
1417 * <td valign="top"> <tt>'\u0045'</tt>
1418 * <td> The upper-case variant of <tt>'e'</tt>. The exponent symbol
1419 * will be <tt>'E'</tt> (<tt>'\u0045'</tt>).
1420 *
1421 * <tr><td valign="top"> <tt>'g'</tt>
1422 * <td valign="top"> <tt>'\u0067'</tt>
1423 * <td> Requires the output to be formatted in general scientific notation
1424 * as described below. The <a href="#l10n algorithm">localization
1425 * algorithm</a> is applied.
1426 *
1427 * <p> After rounding for the precision, the formatting of the resulting
1428 * magnitude <i>m</i> depends on its value.
1429 *
1430 * <p> If <i>m</i> is greater than or equal to 10<sup>-4</sup> but less
1431 * than 10<sup>precision</sup> then it is represented in <i><a
1432 * href="#decimal">decimal format</a></i>.
1433 *
1434 * <p> If <i>m</i> is less than 10<sup>-4</sup> or greater than or equal to
1435 * 10<sup>precision</sup>, then it is represented in <i><a
1436 * href="#scientific">computerized scientific notation</a></i>.
1437 *
1438 * <p> The total number of significant digits in <i>m</i> is equal to the
1439 * precision. If the precision is not specified, then the default value is
1440 * <tt>6</tt>. If the precision is <tt>0</tt>, then it is taken to be
1441 * <tt>1</tt>.
1442 *
1443 * <p> If the <tt>'#'</tt> flag is given then an {@link
1444 * FormatFlagsConversionMismatchException} will be thrown.
1445 *
1446 * <tr><td valign="top"> <tt>'G'</tt>
1447 * <td valign="top"> <tt>'\u0047'</tt>
1448 * <td> The upper-case variant of <tt>'g'</tt>.
1449 *
1450 * <tr><td valign="top"> <tt>'f'</tt>
1451 * <td valign="top"> <tt>'\u0066'</tt>
1452 * <td> Requires the output to be formatted using <a name="decimal">decimal
1453 * format</a>. The <a href="#l10n algorithm">localization algorithm</a> is
1454 * applied.
1455 *
1456 * <p> The result is a string that represents the sign and magnitude
1457 * (absolute value) of the argument. The formatting of the sign is
1458 * described in the <a href="#l10n algorithm">localization
1459 * algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1460 * value.
1461 *
1462 * <p> The magnitude is formatted as the integer part of <i>m</i>, with no
1463 * leading zeroes, followed by the decimal separator followed by one or
1464 * more decimal digits representing the fractional part of <i>m</i>.
1465 *
1466 * <p> The number of digits in the result for the fractional part of
1467 * <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1468 * specified then the default value is <tt>6</tt>. If the precision is
1469 * less than the number of digits which would appear after the decimal
1470 * point in the string returned by {@link Float#toString(float)} or {@link
1471 * Double#toString(double)} respectively, then the value will be rounded
1472 * using the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1473 * algorithm}. Otherwise, zeros may be appended to reach the precision.
1474 * For a canonical representation of the value, use {@link
1475 * BigDecimal#toString()}.
1476 *
1477 * </table>
1478 *
1479 * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1480 * Long apply.
1481 *
1482 * <p> If the <tt>'#'</tt> flag is given, then the decimal separator will
1483 * always be present.
1484 *
1485 * <p> The <a href="#floatdFlags">default behavior</a> when no flags are
1486 * given is the same as for Float and Double.
1487 *
1488 * <p> The specification of <a href="#floatDWidth">width</a> and <a
1489 * href="#floatDPrec">precision</a> is the same as defined for Float and
1490 * Double.
1491 *
1492 * <h4><a name="ddt">Date/Time</a></h4>
1493 *
1494 * <p> This conversion may be applied to <tt>long</tt>, {@link Long}, {@link
1495 * Calendar}, and {@link Date}.
1496 *
1497 * <table cellpadding=5 summary="DTConv">
1498 *
1499 * <tr><td valign="top"> <tt>'t'</tt>
1500 * <td valign="top"> <tt>'\u0074'</tt>
1501 * <td> Prefix for date and time conversion characters.
1502 * <tr><td valign="top"> <tt>'T'</tt>
1503 * <td valign="top"> <tt>'\u0054'</tt>
1504 * <td> The upper-case variant of <tt>'t'</tt>.
1505 *
1506 * </table>
1507 *
1508 * <p> The following date and time conversion character suffixes are defined
1509 * for the <tt>'t'</tt> and <tt>'T'</tt> conversions. The types are similar to
1510 * but not completely identical to those defined by GNU <tt>date</tt> and
1511 * POSIX <tt>strftime(3c)</tt>. Additional conversion types are provided to
1512 * access Java-specific functionality (e.g. <tt>'L'</tt> for milliseconds
1513 * within the second).
1514 *
1515 * <p> The following conversion characters are used for formatting times:
1516 *
1517 * <table cellpadding=5 summary="time">
1518 *
1519 * <tr><td valign="top"> <tt>'H'</tt>
1520 * <td valign="top"> <tt>'\u0048'</tt>
1521 * <td> Hour of the day for the 24-hour clock, formatted as two digits with
1522 * a leading zero as necessary i.e. <tt>00 - 23</tt>. <tt>00</tt>
1523 * corresponds to midnight.
1524 *
1525 * <tr><td valign="top"><tt>'I'</tt>
1526 * <td valign="top"> <tt>'\u0049'</tt>
1527 * <td> Hour for the 12-hour clock, formatted as two digits with a leading
1528 * zero as necessary, i.e. <tt>01 - 12</tt>. <tt>01</tt> corresponds to
1529 * one o'clock (either morning or afternoon).
1530 *
1531 * <tr><td valign="top"><tt>'k'</tt>
1532 * <td valign="top"> <tt>'\u006b'</tt>
1533 * <td> Hour of the day for the 24-hour clock, i.e. <tt>0 - 23</tt>.
1534 * <tt>0</tt> corresponds to midnight.
1535 *
1536 * <tr><td valign="top"><tt>'l'</tt>
1537 * <td valign="top"> <tt>'\u006c'</tt>
1538 * <td> Hour for the 12-hour clock, i.e. <tt>1 - 12</tt>. <tt>1</tt>
1539 * corresponds to one o'clock (either morning or afternoon).
1540 *
1541 * <tr><td valign="top"><tt>'M'</tt>
1542 * <td valign="top"> <tt>'\u004d'</tt>
1543 * <td> Minute within the hour formatted as two digits with a leading zero
1544 * as necessary, i.e. <tt>00 - 59</tt>.
1545 *
1546 * <tr><td valign="top"><tt>'S'</tt>
1547 * <td valign="top"> <tt>'\u0053'</tt>
1548 * <td> Seconds within the minute, formatted as two digits with a leading
1549 * zero as necessary, i.e. <tt>00 - 60</tt> ("<tt>60</tt>" is a special
1550 * value required to support leap seconds).
1551 *
1552 * <tr><td valign="top"><tt>'L'</tt>
1553 * <td valign="top"> <tt>'\u004c'</tt>
1554 * <td> Millisecond within the second formatted as three digits with
1555 * leading zeros as necessary, i.e. <tt>000 - 999</tt>.
1556 *
1557 * <tr><td valign="top"><tt>'N'</tt>
1558 * <td valign="top"> <tt>'\u004e'</tt>
1559 * <td> Nanosecond within the second, formatted as nine digits with leading
1560 * zeros as necessary, i.e. <tt>000000000 - 999999999</tt>. The precision
1561 * of this value is limited by the resolution of the underlying operating
1562 * system or hardware.
1563 *
1564 * <tr><td valign="top"><tt>'p'</tt>
1565 * <td valign="top"> <tt>'\u0070'</tt>
1566 * <td> Locale-specific {@linkplain
1567 * java.text.DateFormatSymbols#getAmPmStrings morning or afternoon} marker
1568 * in lower case, e.g."<tt>am</tt>" or "<tt>pm</tt>". Use of the
1569 * conversion prefix <tt>'T'</tt> forces this output to upper case. (Note
1570 * that <tt>'p'</tt> produces lower-case output. This is different from
1571 * GNU <tt>date</tt> and POSIX <tt>strftime(3c)</tt> which produce
1572 * upper-case output.)
1573 *
1574 * <tr><td valign="top"><tt>'z'</tt>
1575 * <td valign="top"> <tt>'\u007a'</tt>
1576 * <td> <a href="http://www.ietf.org/rfc/rfc0822.txt">RFC 822</a>
1577 * style numeric time zone offset from GMT, e.g. <tt>-0800</tt>. This
1578 * value will be adjusted as necessary for Daylight Saving Time. For
1579 * <tt>long</tt>, {@link Long}, and {@link Date} the time zone used is
1580 * the {@plainlink TimeZone#getDefault() default time zone} for this
1581 * instance of the Java virtual machine.
1582 *
1583 * <tr><td valign="top"><tt>'Z'</tt>
1584 * <td> A string representing the abbreviation for the time zone. This
1585 * value will be adjusted as necessary for Daylight Saving Time. For
1586 * <tt>long</tt>, {@link Long}, and {@link Date} the time zone used is
1587 * the {@plainlink TimeZone#getDefault() default time zone} for this
1588 * instance of the Java virtual machine. The Formatter's locale will
1589 * supersede the locale of the argument (if any).
1590 *
1591 * <tr><td valign="top"><tt>'s'</tt>
1592 * <td valign="top"> <tt>'\u0073'</tt>
1593 * <td> Seconds since the beginning of the epoch starting at 1 January 1970
1594 * <tt>00:00:00</tt> UTC, i.e. <tt>Long.MIN_VALUE/1000</tt> to
1595 * <tt>Long.MAX_VALUE/1000</tt>.
1596 *
1597 * <tr><td valign="top"><tt>'Q'</tt>
1598 * <td valign="top"> <tt>'\u004f'</tt>
1599 * <td> Milliseconds since the beginning of the epoch starting at 1 January
1600 * 1970 <tt>00:00:00</tt> UTC, i.e. <tt>Long.MIN_VALUE</tt> to
1601 * <tt>Long.MAX_VALUE</tt>. The precision of this value is limited by
1602 * the resolution of the underlying operating system or hardware.
1603 *
1604 * </table>
1605 *
1606 * <p> The following conversion characters are used for formatting dates:
1607 *
1608 * <table cellpadding=5 summary="date">
1609 *
1610 * <tr><td valign="top"><tt>'B'</tt>
1611 * <td valign="top"> <tt>'\u0042'</tt>
1612 * <td> Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths
1613 * full month name}, e.g. <tt>"January"</tt>, <tt>"February"</tt>.
1614 *
1615 * <tr><td valign="top"><tt>'b'</tt>
1616 * <td valign="top"> <tt>'\u0062'</tt>
1617 * <td> Locale-specific {@linkplain
1618 * java.text.DateFormatSymbols#getShortMonths abbreviated month name},
1619 * e.g. <tt>"Jan"</tt>, <tt>"Feb"</tt>.
1620 *
1621 * <tr><td valign="top"><tt>'h'</tt>
1622 * <td valign="top"> <tt>'\u0068'</tt>
1623 * <td> Same as <tt>'b'</tt>.
1624 *
1625 * <tr><td valign="top"><tt>'A'</tt>
1626 * <td valign="top"> <tt>'\u0041'</tt>
1627 * <td> Locale-specific full name of the {@linkplain
1628 * java.text.DateFormatSymbols#getWeekdays day of the week},
1629 * e.g. <tt>"Sunday"</tt>, <tt>"Monday"</tt>
1630 *
1631 * <tr><td valign="top"><tt>'a'</tt>
1632 * <td valign="top"> <tt>'\u0061'</tt>
1633 * <td> Locale-specific short name of the {@linkplain
1634 * java.text.DateFormatSymbols#getShortWeekdays day of the week},
1635 * e.g. <tt>"Sun"</tt>, <tt>"Mon"</tt>
1636 *
1637 * <tr><td valign="top"><tt>'C'</tt>
1638 * <td valign="top"> <tt>'\u0043'</tt>
1639 * <td> Four-digit year divided by <tt>100</tt>, formatted as two digits
1640 * with leading zero as necessary, i.e. <tt>00 - 99</tt>
1641 *
1642 * <tr><td valign="top"><tt>'Y'</tt>
1643 * <td valign="top"> <tt>'\u0059'</tt> <td> Year, formatted to at least
1644 * four digits with leading zeros as necessary, e.g. <tt>0092</tt> equals
1645 * <tt>92</tt> CE for the Gregorian calendar.
1646 *
1647 * <tr><td valign="top"><tt>'y'</tt>
1648 * <td valign="top"> <tt>'\u0079'</tt>
1649 * <td> Last two digits of the year, formatted with leading zeros as
1650 * necessary, i.e. <tt>00 - 99</tt>.
1651 *
1652 * <tr><td valign="top"><tt>'j'</tt>
1653 * <td valign="top"> <tt>'\u006a'</tt>
1654 * <td> Day of year, formatted as three digits with leading zeros as
1655 * necessary, e.g. <tt>001 - 366</tt> for the Gregorian calendar.
1656 * <tt>001</tt> corresponds to the first day of the year.
1657 *
1658 * <tr><td valign="top"><tt>'m'</tt>
1659 * <td valign="top"> <tt>'\u006d'</tt>
1660 * <td> Month, formatted as two digits with leading zeros as necessary,
1661 * i.e. <tt>01 - 13</tt>, where "<tt>01</tt>" is the first month of the
1662 * year and ("<tt>13</tt>" is a special value required to support lunar
1663 * calendars).
1664 *
1665 * <tr><td valign="top"><tt>'d'</tt>
1666 * <td valign="top"> <tt>'\u0064'</tt>
1667 * <td> Day of month, formatted as two digits with leading zeros as
1668 * necessary, i.e. <tt>01 - 31</tt>, where "<tt>01</tt>" is the first day
1669 * of the month.
1670 *
1671 * <tr><td valign="top"><tt>'e'</tt>
1672 * <td valign="top"> <tt>'\u0065'</tt>
1673 * <td> Day of month, formatted as two digits, i.e. <tt>1 - 31</tt> where
1674 * "<tt>1</tt>" is the first day of the month.
1675 *
1676 * </table>
1677 *
1678 * <p> The following conversion characters are used for formatting common
1679 * date/time compositions.
1680 *
1681 * <table cellpadding=5 summary="composites">
1682 *
1683 * <tr><td valign="top"><tt>'R'</tt>
1684 * <td valign="top"> <tt>'\u0052'</tt>
1685 * <td> Time formatted for the 24-hour clock as <tt>"%tH:%tM"</tt>
1686 *
1687 * <tr><td valign="top"><tt>'T'</tt>
1688 * <td valign="top"> <tt>'\u0054'</tt>
1689 * <td> Time formatted for the 24-hour clock as <tt>"%tH:%tM:%tS"</tt>.
1690 *
1691 * <tr><td valign="top"><tt>'r'</tt>
1692 * <td valign="top"> <tt>'\u0072'</tt>
1693 * <td> Time formatted for the 12-hour clock as <tt>"%tI:%tM:%tS
1694 * %Tp"</tt>. The location of the morning or afternoon marker
1695 * (<tt>'%Tp'</tt>) may be locale-dependent.
1696 *
1697 * <tr><td valign="top"><tt>'D'</tt>
1698 * <td valign="top"> <tt>'\u0044'</tt>
1699 * <td> Date formatted as <tt>"%tm/%td/%ty"</tt>.
1700 *
1701 * <tr><td valign="top"><tt>'F'</tt>
1702 * <td valign="top"> <tt>'\u0046'</tt>
1703 * <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a>
1704 * complete date formatted as <tt>"%tY-%tm-%td"</tt>.
1705 *
1706 * <tr><td valign="top"><tt>'c'</tt>
1707 * <td valign="top"> <tt>'\u0063'</tt>
1708 * <td> Date and time formatted as <tt>"%ta %tb %td %tT %tZ %tY"</tt>,
1709 * e.g. <tt>"Sun Jul 20 16:17:00 EDT 1969"</tt>.
1710 *
1711 * </table>
1712 *
1713 * <p> The <tt>'-'</tt> flag defined for <a href="#dFlags">General
1714 * conversions</a> applies. If the <tt>'#'</tt> flag is given, then a {@link
1715 * FormatFlagsConversionMismatchException} will be thrown.
1716 *
1717 * <p> The <a name="dtWidth">width</a> is the minimum number of characters to
1718 * be written to the output. If the length of the converted value is less than
1719 * the <tt>width</tt> then the output will be padded by spaces
1720 * (<tt>'\u0020'</tt>) until the total number of characters equals width.
1721 * The padding is on the left by default. If the <tt>'-'</tt> flag is given
1722 * then the padding will be on the right. If width is not specified then there
1723 * is no minimum.
1724 *
1725 * <p> The precision is not applicable. If the precision is specified then an
1726 * {@link IllegalFormatPrecisionException} will be thrown.
1727 *
1728 * <h4><a name="dper">Percent</a></h4>
1729 *
1730 * <p> The conversion does not correspond to any argument.
1731 *
1732 * <table cellpadding=5 summary="DTConv">
1733 *
1734 * <tr><td valign="top"><tt>'%'</tt>
1735 * <td> The result is a literal <tt>'%'</tt> (<tt>'\u0025'</tt>)
1736 *
1737 * <p> The <a name="dtWidth">width</a> is the minimum number of characters to
1738 * be written to the output including the <tt>'%'</tt>. If the length of the
1739 * converted value is less than the <tt>width</tt> then the output will be
1740 * padded by spaces (<tt>'\u0020'</tt>) until the total number of
1741 * characters equals width. The padding is on the left. If width is not
1742 * specified then just the <tt>'%'</tt> is output.
1743 *
1744 * <p> The <tt>'-'</tt> flag defined for <a href="#dFlags">General
1745 * conversions</a> applies. If any other flags are provided, then a
1746 * {@link FormatFlagsConversionMismatchException} will be thrown.
1747 *
1748 * <p> The precision is not applicable. If the precision is specified an
1749 * {@link IllegalFormatPrecisionException} will be thrown.
1750 *
1751 * </table>
1752 *
1753 * <h4><a name="dls">Line Separator</a></h4>
1754 *
1755 * <p> The conversion does not correspond to any argument.
1756 *
1757 * <table cellpadding=5 summary="DTConv">
1758 *
1759 * <tr><td valign="top"><tt>'n'</tt>
1760 * <td> the platform-specific line separator as returned by {@link
1761 * System#getProperty System.getProperty("line.separator")}.
1762 *
1763 * </table>
1764 *
1765 * <p> Flags, width, and precision are not applicable. If any are provided an
1766 * {@link IllegalFormatFlagsException}, {@link IllegalFormatWidthException},
1767 * and {@link IllegalFormatPrecisionException}, respectively will be thrown.
1768 *
1769 * <h4><a name="dpos">Argument Index</a></h4>
1770 *
1771 * <p> Format specifiers can reference arguments in three ways:
1772 *
1773 * <ul>
1774 *
1775 * <li> <i>Explicit indexing</i> is used when the format specifier contains an
1776 * argument index. The argument index is a decimal integer indicating the
1777 * position of the argument in the argument list. The first argument is
1778 * referenced by "<tt>1$</tt>", the second by "<tt>2$</tt>", etc. An argument
1779 * may be referenced more than once.
1780 *
1781 * <p> For example:
1782 *
1783 * <blockquote><pre>
1784 * formatter.format("%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s",
1785 * "a", "b", "c", "d")
1786 * // -> "d c b a d c b a"
1787 * </pre></blockquote>
1788 *
1789 * <li> <i>Relative indexing</i> is used when the format specifier contains a
1790 * <tt>'<'</tt> (<tt>'\u003c'</tt>) flag which causes the argument for
1791 * the previous format specifier to be re-used. If there is no previous
1792 * argument, then a {@link MissingFormatArgumentException} is thrown.
1793 *
1794 * <blockquote><pre>
1795 * formatter.format("%s %s %<s %<s", "a", "b", "c", "d")
1796 * // -> "a b b b"
1797 * // "c" and "d" are ignored because they are not referenced
1798 * </pre></blockquote>
1799 *
1800 * <li> <i>Ordinary indexing</i> is used when the format specifier contains
1801 * neither an argument index nor a <tt>'<'</tt> flag. Each format specifier
1802 * which uses ordinary indexing is assigned a sequential implicit index into
1803 * argument list which is independent of the indices used by explicit or
1804 * relative indexing.
1805 *
1806 * <blockquote><pre>
1807 * formatter.format("%s %s %s %s", "a", "b", "c", "d")
1808 * // -> "a b c d"
1809 * </pre></blockquote>
1810 *
1811 * </ul>
1812 *
1813 * <p> It is possible to have a format string which uses all forms of indexing,
1814 * for example:
1815 *
1816 * <blockquote><pre>
1817 * formatter.format("%2$s %s %<s %s", "a", "b", "c", "d")
1818 * // -> "b a a b"
1819 * // "c" and "d" are ignored because they are not referenced
1820 * </pre></blockquote>
1821 *
1822 * <p> The maximum number of arguments is limited by the maximum dimension of a
1823 * Java array as defined by the <a
1824 * href="http://java.sun.com/docs/books/vmspec/">Java Virtual Machine
1825 * Specification</a>. If the argument index is does not correspond to an
1826 * available argument, then a {@link MissingFormatArgumentException} is thrown.
1827 *
1828 * <p> If there are more arguments than format specifiers, the extra arguments
1829 * are ignored.
1830 *
1831 * <p> Unless otherwise specified, passing a <tt>null</tt> argument to any
1832 * method or constructor in this class will cause a {@link
1833 * NullPointerException} to be thrown.
1834 *
1835 * @author Iris Clark
1836 * @since 1.5
1837 */
1838 public final class Formatter implements Closeable, Flushable {
1839 private Appendable a;
1840 private Locale l;
1841
1842 private IOException lastException;
1843
1844 private char zero = '0';
1845 private static double scaleUp;
1846
1847 // 1 (sign) + 19 (max # sig digits) + 1 ('.') + 1 ('e') + 1 (sign)
1848 // + 3 (max # exp digits) + 4 (error) = 30
1849 private static final int MAX_FD_CHARS = 30;
1850
1851 // Initialize internal data.
1859 * Constructs a new formatter.
1860 *
1861 * <p> The destination of the formatted output is a {@link StringBuilder}
1862 * which may be retrieved by invoking {@link #out out()} and whose
1863 * current content may be converted into a string by invoking {@link
1864 * #toString toString()}. The locale used is the {@linkplain
1865 * Locale#getDefault() default locale} for this instance of the Java
1866 * virtual machine.
1867 */
1868 public Formatter() {
1869 init(new StringBuilder(), Locale.getDefault());
1870 }
1871
1872 /**
1873 * Constructs a new formatter with the specified destination.
1874 *
1875 * <p> The locale used is the {@linkplain Locale#getDefault() default
1876 * locale} for this instance of the Java virtual machine.
1877 *
1878 * @param a
1879 * Destination for the formatted output. If <tt>a</tt> is
1880 * <tt>null</tt> then a {@link StringBuilder} will be created.
1881 */
1882 public Formatter(Appendable a) {
1883 if (a == null)
1884 a = new StringBuilder();
1885 init(a, Locale.getDefault());
1886 }
1887
1888 /**
1889 * Constructs a new formatter with the specified locale.
1890 *
1891 * <p> The destination of the formatted output is a {@link StringBuilder}
1892 * which may be retrieved by invoking {@link #out out()} and whose current
1893 * content may be converted into a string by invoking {@link #toString
1894 * toString()}.
1895 *
1896 * @param l
1897 * The {@linkplain java.util.Locale locale} to apply during
1898 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
1899 * is applied.
1900 */
1901 public Formatter(Locale l) {
1902 init(new StringBuilder(), l);
1903 }
1904
1905 /**
1906 * Constructs a new formatter with the specified destination and locale.
1907 *
1908 * @param a
1909 * Destination for the formatted output. If <tt>a</tt> is
1910 * <tt>null</tt> then a {@link StringBuilder} will be created.
1911 *
1912 * @param l
1913 * The {@linkplain java.util.Locale locale} to apply during
1914 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
1915 * is applied.
1916 */
1917 public Formatter(Appendable a, Locale l) {
1918 if (a == null)
1919 a = new StringBuilder();
1920 init(a, l);
1921 }
1922
1923 /**
1924 * Constructs a new formatter with the specified file name.
1925 *
1926 * <p> The charset used is the {@linkplain
1927 * java.nio.charset.Charset#defaultCharset() default charset} for this
1928 * instance of the Java virtual machine.
1929 *
1930 * <p> The locale used is the {@linkplain Locale#getDefault() default
1931 * locale} for this instance of the Java virtual machine.
1932 *
1933 * @param fileName
1934 * The name of the file to use as the destination of this
1987 {
1988 this(fileName, csn, Locale.getDefault());
1989 }
1990
1991 /**
1992 * Constructs a new formatter with the specified file name, charset, and
1993 * locale.
1994 *
1995 * @param fileName
1996 * The name of the file to use as the destination of this
1997 * formatter. If the file exists then it will be truncated to
1998 * zero size; otherwise, a new file will be created. The output
1999 * will be written to the file and is buffered.
2000 *
2001 * @param csn
2002 * The name of a supported {@linkplain java.nio.charset.Charset
2003 * charset}
2004 *
2005 * @param l
2006 * The {@linkplain java.util.Locale locale} to apply during
2007 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
2008 * is applied.
2009 *
2010 * @throws FileNotFoundException
2011 * If the given file name does not denote an existing, writable
2012 * regular file and a new regular file of that name cannot be
2013 * created, or if some other error occurs while opening or
2014 * creating the file
2015 *
2016 * @throws SecurityException
2017 * If a security manager is present and {@link
2018 * SecurityManager#checkWrite checkWrite(fileName)} denies write
2019 * access to the file
2020 *
2021 * @throws UnsupportedEncodingException
2022 * If the named charset is not supported
2023 */
2024 public Formatter(String fileName, String csn, Locale l)
2025 throws FileNotFoundException, UnsupportedEncodingException
2026 {
2027 init(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(fileName), csn)),
2095 {
2096 this(file, csn, Locale.getDefault());
2097 }
2098
2099 /**
2100 * Constructs a new formatter with the specified file, charset, and
2101 * locale.
2102 *
2103 * @param file
2104 * The file to use as the destination of this formatter. If the
2105 * file exists then it will be truncated to zero size; otherwise,
2106 * a new file will be created. The output will be written to the
2107 * file and is buffered.
2108 *
2109 * @param csn
2110 * The name of a supported {@linkplain java.nio.charset.Charset
2111 * charset}
2112 *
2113 * @param l
2114 * The {@linkplain java.util.Locale locale} to apply during
2115 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
2116 * is applied.
2117 *
2118 * @throws FileNotFoundException
2119 * If the given file object does not denote an existing, writable
2120 * regular file and a new regular file of that name cannot be
2121 * created, or if some other error occurs while opening or
2122 * creating the file
2123 *
2124 * @throws SecurityException
2125 * If a security manager is present and {@link
2126 * SecurityManager#checkWrite checkWrite(file.getPath())} denies
2127 * write access to the file
2128 *
2129 * @throws UnsupportedEncodingException
2130 * If the named charset is not supported
2131 */
2132 public Formatter(File file, String csn, Locale l)
2133 throws FileNotFoundException, UnsupportedEncodingException
2134 {
2135 init(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file), csn)),
2195 public Formatter(OutputStream os, String csn)
2196 throws UnsupportedEncodingException
2197 {
2198 this(os, csn, Locale.getDefault());
2199 }
2200
2201 /**
2202 * Constructs a new formatter with the specified output stream, charset,
2203 * and locale.
2204 *
2205 * @param os
2206 * The output stream to use as the destination of this formatter.
2207 * The output will be buffered.
2208 *
2209 * @param csn
2210 * The name of a supported {@linkplain java.nio.charset.Charset
2211 * charset}
2212 *
2213 * @param l
2214 * The {@linkplain java.util.Locale locale} to apply during
2215 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
2216 * is applied.
2217 *
2218 * @throws UnsupportedEncodingException
2219 * If the named charset is not supported
2220 */
2221 public Formatter(OutputStream os, String csn, Locale l)
2222 throws UnsupportedEncodingException
2223 {
2224 init(new BufferedWriter(new OutputStreamWriter(os, csn)), l);
2225 }
2226
2227 private void setZero() {
2228 if ((l != null) && !l.equals(Locale.US)) {
2229 DecimalFormatSymbols dfs = DecimalFormatSymbols.getInstance(l);
2230 zero = dfs.getZeroDigit();
2231 }
2232 }
2233
2234 /**
2235 * Returns the locale set by the construction of this formatter.
2236 *
2237 * <p> The {@link #format(java.util.Locale,String,Object...) format} method
2238 * for this object which has a locale argument does not change this value.
2239 *
2240 * @return <tt>null</tt> if no localization is applied, otherwise a
2241 * locale
2242 *
2243 * @throws FormatterClosedException
2244 * If this formatter has been closed by invoking its {@link
2245 * #close()} method
2246 */
2247 public Locale locale() {
2248 ensureOpen();
2249 return l;
2250 }
2251
2252 /**
2253 * Returns the destination for the output.
2254 *
2255 * @return The destination for the output
2256 *
2257 * @throws FormatterClosedException
2258 * If this formatter has been closed by invoking its {@link
2259 * #close()} method
2260 */
2261 public Appendable out() {
2262 ensureOpen();
2263 return a;
2264 }
2265
2266 /**
2267 * Returns the result of invoking <tt>toString()</tt> on the destination
2268 * for the output. For example, the following code formats text into a
2269 * {@link StringBuilder} then retrieves the resultant string:
2270 *
2271 * <blockquote><pre>
2272 * Formatter f = new Formatter();
2273 * f.format("Last reboot at %tc", lastRebootDate);
2274 * String s = f.toString();
2275 * // -> s == "Last reboot at Sat Jan 01 00:00:00 PST 2000"
2276 * </pre></blockquote>
2277 *
2278 * <p> An invocation of this method behaves in exactly the same way as the
2279 * invocation
2280 *
2281 * <pre>
2282 * out().toString() </pre>
2283 *
2284 * <p> Depending on the specification of <tt>toString</tt> for the {@link
2285 * Appendable}, the returned string may or may not contain the characters
2286 * written to the destination. For instance, buffers typically return
2287 * their contents in <tt>toString()</tt>, but streams cannot since the
2288 * data is discarded.
2289 *
2290 * @return The result of invoking <tt>toString()</tt> on the destination
2291 * for the output
2292 *
2293 * @throws FormatterClosedException
2294 * If this formatter has been closed by invoking its {@link
2295 * #close()} method
2296 */
2297 public String toString() {
2298 ensureOpen();
2299 return a.toString();
2300 }
2301
2302 /**
2303 * Flushes this formatter. If the destination implements the {@link
2304 * java.io.Flushable} interface, its <tt>flush</tt> method will be invoked.
2305 *
2306 * <p> Flushing a formatter writes any buffered output in the destination
2307 * to the underlying stream.
2308 *
2309 * @throws FormatterClosedException
2310 * If this formatter has been closed by invoking its {@link
2311 * #close()} method
2312 */
2313 public void flush() {
2314 ensureOpen();
2315 if (a instanceof Flushable) {
2316 try {
2317 ((Flushable)a).flush();
2318 } catch (IOException ioe) {
2319 lastException = ioe;
2320 }
2321 }
2322 }
2323
2324 /**
2325 * Closes this formatter. If the destination implements the {@link
2326 * java.io.Closeable} interface, its <tt>close</tt> method will be invoked.
2327 *
2328 * <p> Closing a formatter allows it to release resources it may be holding
2329 * (such as open files). If the formatter is already closed, then invoking
2330 * this method has no effect.
2331 *
2332 * <p> Attempting to invoke any methods except {@link #ioException()} in
2333 * this formatter after it has been closed will result in a {@link
2334 * FormatterClosedException}.
2335 */
2336 public void close() {
2337 if (a == null)
2338 return;
2339 try {
2340 if (a instanceof Closeable)
2341 ((Closeable)a).close();
2342 } catch (IOException ioe) {
2343 lastException = ioe;
2344 } finally {
2345 a = null;
2346 }
2347 }
2348
2349 private void ensureOpen() {
2350 if (a == null)
2351 throw new FormatterClosedException();
2352 }
2353
2354 /**
2355 * Returns the <tt>IOException</tt> last thrown by this formatter's {@link
2356 * Appendable}.
2357 *
2358 * <p> If the destination's <tt>append()</tt> method never throws
2359 * <tt>IOException</tt>, then this method will always return <tt>null</tt>.
2360 *
2361 * @return The last exception thrown by the Appendable or <tt>null</tt> if
2362 * no such exception exists.
2363 */
2364 public IOException ioException() {
2365 return lastException;
2366 }
2367
2368 /**
2369 * Writes a formatted string to this object's destination using the
2370 * specified format string and arguments. The locale used is the one
2371 * defined during the construction of this formatter.
2372 *
2373 * @param format
2374 * A format string as described in <a href="#syntax">Format string
2375 * syntax</a>.
2376 *
2377 * @param args
2378 * Arguments referenced by the format specifiers in the format
2379 * string. If there are more arguments than format specifiers, the
2380 * extra arguments are ignored. The maximum number of arguments is
2381 * limited by the maximum dimension of a Java array as defined by
2389 * illegal conditions. For specification of all possible
2390 * formatting errors, see the <a href="#detail">Details</a>
2391 * section of the formatter class specification.
2392 *
2393 * @throws FormatterClosedException
2394 * If this formatter has been closed by invoking its {@link
2395 * #close()} method
2396 *
2397 * @return This formatter
2398 */
2399 public Formatter format(String format, Object ... args) {
2400 return format(l, format, args);
2401 }
2402
2403 /**
2404 * Writes a formatted string to this object's destination using the
2405 * specified locale, format string, and arguments.
2406 *
2407 * @param l
2408 * The {@linkplain java.util.Locale locale} to apply during
2409 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
2410 * is applied. This does not change this object's locale that was
2411 * set during construction.
2412 *
2413 * @param format
2414 * A format string as described in <a href="#syntax">Format string
2415 * syntax</a>
2416 *
2417 * @param args
2418 * Arguments referenced by the format specifiers in the format
2419 * string. If there are more arguments than format specifiers, the
2420 * extra arguments are ignored. The maximum number of arguments is
2421 * limited by the maximum dimension of a Java array as defined by
2422 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
2423 * Virtual Machine Specification</a>
2424 *
2425 * @throws IllegalFormatException
2426 * If a format string contains an illegal syntax, a format
2427 * specifier that is incompatible with the given arguments,
2428 * insufficient arguments given the format string, or other
2429 * illegal conditions. For specification of all possible
4179 }
4180 return f;
4181 }
4182
4183 // parse those flags which may be provided by users
4184 private static Flags parse(char c) {
4185 switch (c) {
4186 case '-': return LEFT_JUSTIFY;
4187 case '#': return ALTERNATE;
4188 case '+': return PLUS;
4189 case ' ': return LEADING_SPACE;
4190 case '0': return ZERO_PAD;
4191 case ',': return GROUP;
4192 case '(': return PARENTHESES;
4193 case '<': return PREVIOUS;
4194 default:
4195 throw new UnknownFormatFlagsException(String.valueOf(c));
4196 }
4197 }
4198
4199 // Returns a string representation of the current <tt>Flags</tt>.
4200 public static String toString(Flags f) {
4201 return f.toString();
4202 }
4203
4204 public String toString() {
4205 StringBuilder sb = new StringBuilder();
4206 if (contains(LEFT_JUSTIFY)) sb.append('-');
4207 if (contains(UPPERCASE)) sb.append('^');
4208 if (contains(ALTERNATE)) sb.append('#');
4209 if (contains(PLUS)) sb.append('+');
4210 if (contains(LEADING_SPACE)) sb.append(' ');
4211 if (contains(ZERO_PAD)) sb.append('0');
4212 if (contains(GROUP)) sb.append(',');
4213 if (contains(PARENTHESES)) sb.append('(');
4214 if (contains(PREVIOUS)) sb.append('<');
4215 return sb.toString();
4216 }
4217 }
4218
4219 private static class Conversion {
|
42 import java.math.RoundingMode;
43 import java.nio.charset.Charset;
44 import java.text.DateFormatSymbols;
45 import java.text.DecimalFormat;
46 import java.text.DecimalFormatSymbols;
47 import java.text.NumberFormat;
48 import java.util.Calendar;
49 import java.util.Date;
50 import java.util.Locale;
51 import java.util.regex.Matcher;
52 import java.util.regex.Pattern;
53
54 import sun.misc.FpUtils;
55 import sun.misc.DoubleConsts;
56 import sun.misc.FormattedFloatingDecimal;
57
58 /**
59 * An interpreter for printf-style format strings. This class provides support
60 * for layout justification and alignment, common formats for numeric, string,
61 * and date/time data, and locale-specific output. Common Java types such as
62 * {@code byte}, {@link java.math.BigDecimal BigDecimal}, and {@link Calendar}
63 * are supported. Limited formatting customization for arbitrary user types is
64 * provided through the {@link Formattable} interface.
65 *
66 * <p> Formatters are not necessarily safe for multithreaded access. Thread
67 * safety is optional and is the responsibility of users of methods in this
68 * class.
69 *
70 * <p> Formatted printing for the Java language is heavily inspired by C's
71 * {@code printf}. Although the format strings are similar to C, some
72 * customizations have been made to accommodate the Java language and exploit
73 * some of its features. Also, Java formatting is more strict than C's; for
74 * example, if a conversion is incompatible with a flag, an exception will be
75 * thrown. In C inapplicable flags are silently ignored. The format strings
76 * are thus intended to be recognizable to C programmers but not necessarily
77 * completely compatible with those in C.
78 *
79 * <p> Examples of expected usage:
80 *
81 * <blockquote><pre>
82 * StringBuilder sb = new StringBuilder();
83 * // Send all output to the Appendable object sb
84 * Formatter formatter = new Formatter(sb, Locale.US);
85 *
86 * // Explicit argument indices may be used to re-order output.
87 * formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d")
88 * // -> " d c b a"
89 *
90 * // Optional locale as the first argument can be used to get
91 * // locale-specific formatting of numbers. The precision and width can be
98 * // automatically inserted.
99 * formatter.format("Amount gained or lost since last statement: $ %(,.2f",
100 * balanceDelta);
101 * // -> "Amount gained or lost since last statement: $ (6,217.58)"
102 * </pre></blockquote>
103 *
104 * <p> Convenience methods for common formatting requests exist as illustrated
105 * by the following invocations:
106 *
107 * <blockquote><pre>
108 * // Writes a formatted string to System.out.
109 * System.out.format("Local time: %tT", Calendar.getInstance());
110 * // -> "Local time: 13:34:18"
111 *
112 * // Writes formatted output to System.err.
113 * System.err.printf("Unable to open file '%1$s': %2$s",
114 * fileName, exception.getMessage());
115 * // -> "Unable to open file 'food': No such file or directory"
116 * </pre></blockquote>
117 *
118 * <p> Like C's {@code sprintf(3)}, Strings may be formatted using the static
119 * method {@link String#format(String,Object...) String.format}:
120 *
121 * <blockquote><pre>
122 * // Format a string containing a date.
123 * import java.util.Calendar;
124 * import java.util.GregorianCalendar;
125 * import static java.util.Calendar.*;
126 *
127 * Calendar c = new GregorianCalendar(1995, MAY, 23);
128 * String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
129 * // -> s == "Duke's Birthday: May 23, 1995"
130 * </pre></blockquote>
131 *
132 * <h3><a name="org">Organization</a></h3>
133 *
134 * <p> This specification is divided into two sections. The first section, <a
135 * href="#summary">Summary</a>, covers the basic formatting concepts. This
136 * section is intended for users who want to get started quickly and are
137 * familiar with formatted printing in other programming languages. The second
138 * section, <a href="#detail">Details</a>, covers the specific implementation
140 * formatting behavior.
141 *
142 * <h3><a name="summary">Summary</a></h3>
143 *
144 * <p> This section is intended to provide a brief overview of formatting
145 * concepts. For precise behavioral details, refer to the <a
146 * href="#detail">Details</a> section.
147 *
148 * <h4><a name="syntax">Format String Syntax</a></h4>
149 *
150 * <p> Every method which produces formatted output requires a <i>format
151 * string</i> and an <i>argument list</i>. The format string is a {@link
152 * String} which may contain fixed text and one or more embedded <i>format
153 * specifiers</i>. Consider the following example:
154 *
155 * <blockquote><pre>
156 * Calendar c = ...;
157 * String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
158 * </pre></blockquote>
159 *
160 * This format string is the first argument to the {@code format} method. It
161 * contains three format specifiers "{@code %1$tm}", "{@code %1$te}", and
162 * "{@code %1$tY}" which indicate how the arguments should be processed and
163 * where they should be inserted in the text. The remaining portions of the
164 * format string are fixed text including {@code "Dukes Birthday: "} and any
165 * other spaces or punctuation.
166 *
167 * The argument list consists of all arguments passed to the method after the
168 * format string. In the above example, the argument list is of size one and
169 * consists of the {@link java.util.Calendar Calendar} object {@code c}.
170 *
171 * <ul>
172 *
173 * <li> The format specifiers for general, character, and numeric types have
174 * the following syntax:
175 *
176 * <blockquote><pre>
177 * %[argument_index$][flags][width][.precision]conversion
178 * </pre></blockquote>
179 *
180 * <p> The optional <i>argument_index</i> is a decimal integer indicating the
181 * position of the argument in the argument list. The first argument is
182 * referenced by "{@code 1$}", the second by "{@code 2$}", etc.
183 *
184 * <p> The optional <i>flags</i> is a set of characters that modify the output
185 * format. The set of valid flags depends on the conversion.
186 *
187 * <p> The optional <i>width</i> is a non-negative decimal integer indicating
188 * the minimum number of characters to be written to the output.
189 *
190 * <p> The optional <i>precision</i> is a non-negative decimal integer usually
191 * used to restrict the number of characters. The specific behavior depends on
192 * the conversion.
193 *
194 * <p> The required <i>conversion</i> is a character indicating how the
195 * argument should be formatted. The set of valid conversions for a given
196 * argument depends on the argument's data type.
197 *
198 * <li> The format specifiers for types which are used to represents dates and
199 * times have the following syntax:
200 *
201 * <blockquote><pre>
202 * %[argument_index$][flags][width]conversion
203 * </pre></blockquote>
204 *
205 * <p> The optional <i>argument_index</i>, <i>flags</i> and <i>width</i> are
206 * defined as above.
207 *
208 * <p> The required <i>conversion</i> is a two character sequence. The first
209 * character is {@code 't'} or {@code 'T'}. The second character indicates
210 * the format to be used. These characters are similar to but not completely
211 * identical to those defined by GNU {@code date} and POSIX
212 * {@code strftime(3c)}.
213 *
214 * <li> The format specifiers which do not correspond to arguments have the
215 * following syntax:
216 *
217 * <blockquote><pre>
218 * %[flags][width]conversion
219 * </pre></blockquote>
220 *
221 * <p> The optional <i>flags</i> and <i>width</i> is defined as above.
222 *
223 * <p> The required <i>conversion</i> is a character indicating content to be
224 * inserted in the output.
225 *
226 * </ul>
227 *
228 * <h4> Conversions </h4>
229 *
230 * <p> Conversions are divided into the following categories:
231 *
232 * <ol>
233 *
234 * <li> <b>General</b> - may be applied to any argument
235 * type
236 *
237 * <li> <b>Character</b> - may be applied to basic types which represent
238 * Unicode characters: {@code char}, {@link Character}, {@code byte}, {@link
239 * Byte}, {@code short}, and {@link Short}. This conversion may also be
240 * applied to the types {@code int} and {@link Integer} when {@link
241 * Character#isValidCodePoint} returns {@code true}
242 *
243 * <li> <b>Numeric</b>
244 *
245 * <ol>
246 *
247 * <li> <b>Integral</b> - may be applied to Java integral types: {@code byte},
248 * {@link Byte}, {@code short}, {@link Short}, {@code int} and {@link
249 * Integer}, {@code long}, {@link Long}, and {@link java.math.BigInteger
250 * BigInteger}
251 *
252 * <li><b>Floating Point</b> - may be applied to Java floating-point types:
253 * {@code float}, {@link Float}, {@code double}, {@link Double}, and {@link
254 * java.math.BigDecimal BigDecimal}
255 *
256 * </ol>
257 *
258 * <li> <b>Date/Time</b> - may be applied to Java types which are capable of
259 * encoding a date or time: {@code long}, {@link Long}, {@link Calendar}, and
260 * {@link Date}.
261 *
262 * <li> <b>Percent</b> - produces a literal {@code '%'}
263 * (<tt>'\u0025'</tt>)
264 *
265 * <li> <b>Line Separator</b> - produces the platform-specific line separator
266 *
267 * </ol>
268 *
269 * <p> The following table summarizes the supported conversions. Conversions
270 * denoted by an upper-case character (i.e. {@code 'B'}, {@code 'H'},
271 * {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'}, {@code 'G'},
272 * {@code 'A'}, and {@code 'T'}) are the same as those for the corresponding
273 * lower-case conversion characters except that the result is converted to
274 * upper case according to the rules of the prevailing {@link java.util.Locale
275 * Locale}. The result is equivalent to the following invocation of {@link
276 * String#toUpperCase()}
277 *
278 * <pre>
279 * out.toUpperCase() </pre>
280 *
281 * <table cellpadding=5 summary="genConv">
282 *
283 * <tr><th valign="bottom"> Conversion
284 * <th valign="bottom"> Argument Category
285 * <th valign="bottom"> Description
286 *
287 * <tr><td valign="top"> {@code 'b'}, {@code 'B'}
288 * <td valign="top"> general
289 * <td> If the argument <i>arg</i> is {@code null}, then the result is
290 * "{@code false}". If <i>arg</i> is a {@code boolean} or {@link
291 * Boolean}, then the result is the string returned by {@link
292 * String#valueOf(boolean) String.valueOf(arg)}. Otherwise, the result is
293 * "true".
294 *
295 * <tr><td valign="top"> {@code 'h'}, {@code 'H'}
296 * <td valign="top"> general
297 * <td> If the argument <i>arg</i> is {@code null}, then the result is
298 * "{@code null}". Otherwise, the result is obtained by invoking
299 * {@code Integer.toHexString(arg.hashCode())}.
300 *
301 * <tr><td valign="top"> {@code 's'}, {@code 'S'}
302 * <td valign="top"> general
303 * <td> If the argument <i>arg</i> is {@code null}, then the result is
304 * "{@code null}". If <i>arg</i> implements {@link Formattable}, then
305 * {@link Formattable#formatTo arg.formatTo} is invoked. Otherwise, the
306 * result is obtained by invoking {@code arg.toString()}.
307 *
308 * <tr><td valign="top">{@code 'c'}, {@code 'C'}
309 * <td valign="top"> character
310 * <td> The result is a Unicode character
311 *
312 * <tr><td valign="top">{@code 'd'}
313 * <td valign="top"> integral
314 * <td> The result is formatted as a decimal integer
315 *
316 * <tr><td valign="top">{@code 'o'}
317 * <td valign="top"> integral
318 * <td> The result is formatted as an octal integer
319 *
320 * <tr><td valign="top">{@code 'x'}, {@code 'X'}
321 * <td valign="top"> integral
322 * <td> The result is formatted as a hexadecimal integer
323 *
324 * <tr><td valign="top">{@code 'e'}, {@code 'E'}
325 * <td valign="top"> floating point
326 * <td> The result is formatted as a decimal number in computerized
327 * scientific notation
328 *
329 * <tr><td valign="top">{@code 'f'}
330 * <td valign="top"> floating point
331 * <td> The result is formatted as a decimal number
332 *
333 * <tr><td valign="top">{@code 'g'}, {@code 'G'}
334 * <td valign="top"> floating point
335 * <td> The result is formatted using computerized scientific notation or
336 * decimal format, depending on the precision and the value after rounding.
337 *
338 * <tr><td valign="top">{@code 'a'}, {@code 'A'}
339 * <td valign="top"> floating point
340 * <td> The result is formatted as a hexadecimal floating-point number with
341 * a significand and an exponent
342 *
343 * <tr><td valign="top">{@code 't'}, {@code 'T'}
344 * <td valign="top"> date/time
345 * <td> Prefix for date and time conversion characters. See <a
346 * href="#dt">Date/Time Conversions</a>.
347 *
348 * <tr><td valign="top">{@code '%'}
349 * <td valign="top"> percent
350 * <td> The result is a literal {@code '%'} (<tt>'\u0025'</tt>)
351 *
352 * <tr><td valign="top">{@code 'n'}
353 * <td valign="top"> line separator
354 * <td> The result is the platform-specific line separator
355 *
356 * </table>
357 *
358 * <p> Any characters not explicitly defined as conversions are illegal and are
359 * reserved for future extensions.
360 *
361 * <h4><a name="dt">Date/Time Conversions</a></h4>
362 *
363 * <p> The following date and time conversion suffix characters are defined for
364 * the {@code 't'} and {@code 'T'} conversions. The types are similar to but
365 * not completely identical to those defined by GNU {@code date} and POSIX
366 * {@code strftime(3c)}. Additional conversion types are provided to access
367 * Java-specific functionality (e.g. {@code 'L'} for milliseconds within the
368 * second).
369 *
370 * <p> The following conversion characters are used for formatting times:
371 *
372 * <table cellpadding=5 summary="time">
373 *
374 * <tr><td valign="top"> {@code 'H'}
375 * <td> Hour of the day for the 24-hour clock, formatted as two digits with
376 * a leading zero as necessary i.e. {@code 00 - 23}.
377 *
378 * <tr><td valign="top">{@code 'I'}
379 * <td> Hour for the 12-hour clock, formatted as two digits with a leading
380 * zero as necessary, i.e. {@code 01 - 12}.
381 *
382 * <tr><td valign="top">{@code 'k'}
383 * <td> Hour of the day for the 24-hour clock, i.e. {@code 0 - 23}.
384 *
385 * <tr><td valign="top">{@code 'l'}
386 * <td> Hour for the 12-hour clock, i.e. {@code 1 - 12}.
387 *
388 * <tr><td valign="top">{@code 'M'}
389 * <td> Minute within the hour formatted as two digits with a leading zero
390 * as necessary, i.e. {@code 00 - 59}.
391 *
392 * <tr><td valign="top">{@code 'S'}
393 * <td> Seconds within the minute, formatted as two digits with a leading
394 * zero as necessary, i.e. {@code 00 - 60} ("{@code 60}" is a special
395 * value required to support leap seconds).
396 *
397 * <tr><td valign="top">{@code 'L'}
398 * <td> Millisecond within the second formatted as three digits with
399 * leading zeros as necessary, i.e. {@code 000 - 999}.
400 *
401 * <tr><td valign="top">{@code 'N'}
402 * <td> Nanosecond within the second, formatted as nine digits with leading
403 * zeros as necessary, i.e. {@code 000000000 - 999999999}.
404 *
405 * <tr><td valign="top">{@code 'p'}
406 * <td> Locale-specific {@linkplain
407 * java.text.DateFormatSymbols#getAmPmStrings morning or afternoon} marker
408 * in lower case, e.g."{@code am}" or "{@code pm}". Use of the conversion
409 * prefix {@code 'T'} forces this output to upper case.
410 *
411 * <tr><td valign="top">{@code 'z'}
412 * <td> <a href="http://www.ietf.org/rfc/rfc0822.txt">RFC 822</a>
413 * style numeric time zone offset from GMT, e.g. {@code -0800}. This
414 * value will be adjusted as necessary for Daylight Saving Time. For
415 * {@code long}, {@link Long}, and {@link Date} the time zone used is
416 * the {@linkplain TimeZone#getDefault() default time zone} for this
417 * instance of the Java virtual machine.
418 *
419 * <tr><td valign="top">{@code 'Z'}
420 * <td> A string representing the abbreviation for the time zone. This
421 * value will be adjusted as necessary for Daylight Saving Time. For
422 * {@code long}, {@link Long}, and {@link Date} the time zone used is
423 * the {@linkplain TimeZone#getDefault() default time zone} for this
424 * instance of the Java virtual machine. The Formatter's locale will
425 * supersede the locale of the argument (if any).
426 *
427 * <tr><td valign="top">{@code 's'}
428 * <td> Seconds since the beginning of the epoch starting at 1 January 1970
429 * {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE/1000} to
430 * {@code Long.MAX_VALUE/1000}.
431 *
432 * <tr><td valign="top">{@code 'Q'}
433 * <td> Milliseconds since the beginning of the epoch starting at 1 January
434 * 1970 {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE} to
435 * {@code Long.MAX_VALUE}.
436 *
437 * </table>
438 *
439 * <p> The following conversion characters are used for formatting dates:
440 *
441 * <table cellpadding=5 summary="date">
442 *
443 * <tr><td valign="top">{@code 'B'}
444 * <td> Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths
445 * full month name}, e.g. {@code "January"}, {@code "February"}.
446 *
447 * <tr><td valign="top">{@code 'b'}
448 * <td> Locale-specific {@linkplain
449 * java.text.DateFormatSymbols#getShortMonths abbreviated month name},
450 * e.g. {@code "Jan"}, {@code "Feb"}.
451 *
452 * <tr><td valign="top">{@code 'h'}
453 * <td> Same as {@code 'b'}.
454 *
455 * <tr><td valign="top">{@code 'A'}
456 * <td> Locale-specific full name of the {@linkplain
457 * java.text.DateFormatSymbols#getWeekdays day of the week},
458 * e.g. {@code "Sunday"}, {@code "Monday"}
459 *
460 * <tr><td valign="top">{@code 'a'}
461 * <td> Locale-specific short name of the {@linkplain
462 * java.text.DateFormatSymbols#getShortWeekdays day of the week},
463 * e.g. {@code "Sun"}, {@code "Mon"}
464 *
465 * <tr><td valign="top">{@code 'C'}
466 * <td> Four-digit year divided by {@code 100}, formatted as two digits
467 * with leading zero as necessary, i.e. {@code 00 - 99}
468 *
469 * <tr><td valign="top">{@code 'Y'}
470 * <td> Year, formatted as at least four digits with leading zeros as
471 * necessary, e.g. {@code 0092} equals {@code 92} CE for the Gregorian
472 * calendar.
473 *
474 * <tr><td valign="top">{@code 'y'}
475 * <td> Last two digits of the year, formatted with leading zeros as
476 * necessary, i.e. {@code 00 - 99}.
477 *
478 * <tr><td valign="top">{@code 'j'}
479 * <td> Day of year, formatted as three digits with leading zeros as
480 * necessary, e.g. {@code 001 - 366} for the Gregorian calendar.
481 *
482 * <tr><td valign="top">{@code 'm'}
483 * <td> Month, formatted as two digits with leading zeros as necessary,
484 * i.e. {@code 01 - 13}.
485 *
486 * <tr><td valign="top">{@code 'd'}
487 * <td> Day of month, formatted as two digits with leading zeros as
488 * necessary, i.e. {@code 01 - 31}
489 *
490 * <tr><td valign="top">{@code 'e'}
491 * <td> Day of month, formatted as two digits, i.e. {@code 1 - 31}.
492 *
493 * </table>
494 *
495 * <p> The following conversion characters are used for formatting common
496 * date/time compositions.
497 *
498 * <table cellpadding=5 summary="composites">
499 *
500 * <tr><td valign="top">{@code 'R'}
501 * <td> Time formatted for the 24-hour clock as {@code "%tH:%tM"}
502 *
503 * <tr><td valign="top">{@code 'T'}
504 * <td> Time formatted for the 24-hour clock as {@code "%tH:%tM:%tS"}.
505 *
506 * <tr><td valign="top">{@code 'r'}
507 * <td> Time formatted for the 12-hour clock as {@code "%tI:%tM:%tS %Tp"}.
508 * The location of the morning or afternoon marker ({@code '%Tp'}) may be
509 * locale-dependent.
510 *
511 * <tr><td valign="top">{@code 'D'}
512 * <td> Date formatted as {@code "%tm/%td/%ty"}.
513 *
514 * <tr><td valign="top">{@code 'F'}
515 * <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a>
516 * complete date formatted as {@code "%tY-%tm-%td"}.
517 *
518 * <tr><td valign="top">{@code 'c'}
519 * <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"},
520 * e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}.
521 *
522 * </table>
523 *
524 * <p> Any characters not explicitly defined as date/time conversion suffixes
525 * are illegal and are reserved for future extensions.
526 *
527 * <h4> Flags </h4>
528 *
529 * <p> The following table summarizes the supported flags. <i>y</i> means the
530 * flag is supported for the indicated argument types.
531 *
532 * <table cellpadding=5 summary="genConv">
533 *
534 * <tr><th valign="bottom"> Flag <th valign="bottom"> General
535 * <th valign="bottom"> Character <th valign="bottom"> Integral
536 * <th valign="bottom"> Floating Point
537 * <th valign="bottom"> Date/Time
538 * <th valign="bottom"> Description
539 *
540 * <tr><td> '-' <td align="center" valign="top"> y
574 *
575 * <tr><td> ',' <td align="center" valign="top"> -
576 * <td align="center" valign="top"> -
577 * <td align="center" valign="top"> y<sup>2</sup>
578 * <td align="center" valign="top"> y<sup>5</sup>
579 * <td align="center" valign="top"> -
580 * <td> The result will include locale-specific {@linkplain
581 * java.text.DecimalFormatSymbols#getGroupingSeparator grouping separators}
582 *
583 * <tr><td> '(' <td align="center" valign="top"> -
584 * <td align="center" valign="top"> -
585 * <td align="center" valign="top"> y<sup>4</sup>
586 * <td align="center" valign="top"> y<sup>5</sup>
587 * <td align="center"> -
588 * <td> The result will enclose negative numbers in parentheses
589 *
590 * </table>
591 *
592 * <p> <sup>1</sup> Depends on the definition of {@link Formattable}.
593 *
594 * <p> <sup>2</sup> For {@code 'd'} conversion only.
595 *
596 * <p> <sup>3</sup> For {@code 'o'}, {@code 'x'}, and {@code 'X'}
597 * conversions only.
598 *
599 * <p> <sup>4</sup> For {@code 'd'}, {@code 'o'}, {@code 'x'}, and
600 * {@code 'X'} conversions applied to {@link java.math.BigInteger BigInteger}
601 * or {@code 'd'} applied to {@code byte}, {@link Byte}, {@code short}, {@link
602 * Short}, {@code int} and {@link Integer}, {@code long}, and {@link Long}.
603 *
604 * <p> <sup>5</sup> For {@code 'e'}, {@code 'E'}, {@code 'f'},
605 * {@code 'g'}, and {@code 'G'} conversions only.
606 *
607 * <p> Any characters not explicitly defined as flags are illegal and are
608 * reserved for future extensions.
609 *
610 * <h4> Width </h4>
611 *
612 * <p> The width is the minimum number of characters to be written to the
613 * output. For the line separator conversion, width is not applicable; if it
614 * is provided, an exception will be thrown.
615 *
616 * <h4> Precision </h4>
617 *
618 * <p> For general argument types, the precision is the maximum number of
619 * characters to be written to the output.
620 *
621 * <p> For the floating-point conversions {@code 'e'}, {@code 'E'}, and
622 * {@code 'f'} the precision is the number of digits after the decimal
623 * separator. If the conversion is {@code 'g'} or {@code 'G'}, then the
624 * precision is the total number of digits in the resulting magnitude after
625 * rounding. If the conversion is {@code 'a'} or {@code 'A'}, then the
626 * precision must not be specified.
627 *
628 * <p> For character, integral, and date/time argument types and the percent
629 * and line separator conversions, the precision is not applicable; if a
630 * precision is provided, an exception will be thrown.
631 *
632 * <h4> Argument Index </h4>
633 *
634 * <p> The argument index is a decimal integer indicating the position of the
635 * argument in the argument list. The first argument is referenced by
636 * "{@code 1$}", the second by "{@code 2$}", etc.
637 *
638 * <p> Another way to reference arguments by position is to use the
639 * {@code '<'} (<tt>'\u003c'</tt>) flag, which causes the argument for
640 * the previous format specifier to be re-used. For example, the following two
641 * statements would produce identical strings:
642 *
643 * <blockquote><pre>
644 * Calendar c = ...;
645 * String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
646 *
647 * String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c);
648 * </pre></blockquote>
649 *
650 * <hr>
651 * <h3><a name="detail">Details</a></h3>
652 *
653 * <p> This section is intended to provide behavioral details for formatting,
654 * including conditions and exceptions, supported data types, localization, and
655 * interactions between flags, conversions, and data types. For an overview of
656 * formatting concepts, refer to the <a href="#summary">Summary</a>
657 *
658 * <p> Any characters not explicitly defined as conversions, date/time
659 * conversion suffixes, or flags are illegal and are reserved for
660 * future extensions. Use of such a character in a format string will
661 * cause an {@link UnknownFormatConversionException} or {@link
662 * UnknownFormatFlagsException} to be thrown.
663 *
664 * <p> If the format specifier contains a width or precision with an invalid
665 * value or which is otherwise unsupported, then a {@link
666 * IllegalFormatWidthException} or {@link IllegalFormatPrecisionException}
667 * respectively will be thrown.
668 *
669 * <p> If a format specifier contains a conversion character that is not
670 * applicable to the corresponding argument, then an {@link
671 * IllegalFormatConversionException} will be thrown.
672 *
673 * <p> All specified exceptions may be thrown by any of the {@code format}
674 * methods of {@code Formatter} as well as by any {@code format} convenience
675 * methods such as {@link String#format(String,Object...) String.format} and
676 * {@link java.io.PrintStream#printf(String,Object...) PrintStream.printf}.
677 *
678 * <p> Conversions denoted by an upper-case character (i.e. {@code 'B'},
679 * {@code 'H'}, {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'},
680 * {@code 'G'}, {@code 'A'}, and {@code 'T'}) are the same as those for the
681 * corresponding lower-case conversion characters except that the result is
682 * converted to upper case according to the rules of the prevailing {@link
683 * java.util.Locale Locale}. The result is equivalent to the following
684 * invocation of {@link String#toUpperCase()}
685 *
686 * <pre>
687 * out.toUpperCase() </pre>
688 *
689 * <h4><a name="dgen">General</a></h4>
690 *
691 * <p> The following general conversions may be applied to any argument type:
692 *
693 * <table cellpadding=5 summary="dgConv">
694 *
695 * <tr><td valign="top"> {@code 'b'}
696 * <td valign="top"> <tt>'\u0062'</tt>
697 * <td> Produces either "{@code true}" or "{@code false}" as returned by
698 * {@link Boolean#toString(boolean)}.
699 *
700 * <p> If the argument is {@code null}, then the result is
701 * "{@code false}". If the argument is a {@code boolean} or {@link
702 * Boolean}, then the result is the string returned by {@link
703 * String#valueOf(boolean) String.valueOf()}. Otherwise, the result is
704 * "{@code true}".
705 *
706 * <p> If the {@code '#'} flag is given, then a {@link
707 * FormatFlagsConversionMismatchException} will be thrown.
708 *
709 * <tr><td valign="top"> {@code 'B'}
710 * <td valign="top"> <tt>'\u0042'</tt>
711 * <td> The upper-case variant of {@code 'b'}.
712 *
713 * <tr><td valign="top"> {@code 'h'}
714 * <td valign="top"> <tt>'\u0068'</tt>
715 * <td> Produces a string representing the hash code value of the object.
716 *
717 * <p> If the argument, <i>arg</i> is {@code null}, then the
718 * result is "{@code null}". Otherwise, the result is obtained
719 * by invoking {@code Integer.toHexString(arg.hashCode())}.
720 *
721 * <p> If the {@code '#'} flag is given, then a {@link
722 * FormatFlagsConversionMismatchException} will be thrown.
723 *
724 * <tr><td valign="top"> {@code 'H'}
725 * <td valign="top"> <tt>'\u0048'</tt>
726 * <td> The upper-case variant of {@code 'h'}.
727 *
728 * <tr><td valign="top"> {@code 's'}
729 * <td valign="top"> <tt>'\u0073'</tt>
730 * <td> Produces a string.
731 *
732 * <p> If the argument is {@code null}, then the result is
733 * "{@code null}". If the argument implements {@link Formattable}, then
734 * its {@link Formattable#formatTo formatTo} method is invoked.
735 * Otherwise, the result is obtained by invoking the argument's
736 * {@code toString()} method.
737 *
738 * <p> If the {@code '#'} flag is given and the argument is not a {@link
739 * Formattable} , then a {@link FormatFlagsConversionMismatchException}
740 * will be thrown.
741 *
742 * <tr><td valign="top"> {@code 'S'}
743 * <td valign="top"> <tt>'\u0053'</tt>
744 * <td> The upper-case variant of {@code 's'}.
745 *
746 * </table>
747 *
748 * <p> The following <a name="dFlags">flags</a> apply to general conversions:
749 *
750 * <table cellpadding=5 summary="dFlags">
751 *
752 * <tr><td valign="top"> {@code '-'}
753 * <td valign="top"> <tt>'\u002d'</tt>
754 * <td> Left justifies the output. Spaces (<tt>'\u0020'</tt>) will be
755 * added at the end of the converted value as required to fill the minimum
756 * width of the field. If the width is not provided, then a {@link
757 * MissingFormatWidthException} will be thrown. If this flag is not given
758 * then the output will be right-justified.
759 *
760 * <tr><td valign="top"> {@code '#'}
761 * <td valign="top"> <tt>'\u0023'</tt>
762 * <td> Requires the output use an alternate form. The definition of the
763 * form is specified by the conversion.
764 *
765 * </table>
766 *
767 * <p> The <a name="genWidth">width</a> is the minimum number of characters to
768 * be written to the
769 * output. If the length of the converted value is less than the width then
770 * the output will be padded by <tt>' '</tt> (<tt>'\u0020'</tt>)
771 * until the total number of characters equals the width. The padding is on
772 * the left by default. If the {@code '-'} flag is given, then the padding
773 * will be on the right. If the width is not specified then there is no
774 * minimum.
775 *
776 * <p> The precision is the maximum number of characters to be written to the
777 * output. The precision is applied before the width, thus the output will be
778 * truncated to {@code precision} characters even if the width is greater than
779 * the precision. If the precision is not specified then there is no explicit
780 * limit on the number of characters.
781 *
782 * <h4><a name="dchar">Character</a></h4>
783 *
784 * This conversion may be applied to {@code char} and {@link Character}. It
785 * may also be applied to the types {@code byte}, {@link Byte},
786 * {@code short}, and {@link Short}, {@code int} and {@link Integer} when
787 * {@link Character#isValidCodePoint} returns {@code true}. If it returns
788 * {@code false} then an {@link IllegalFormatCodePointException} will be
789 * thrown.
790 *
791 * <table cellpadding=5 summary="charConv">
792 *
793 * <tr><td valign="top"> {@code 'c'}
794 * <td valign="top"> <tt>'\u0063'</tt>
795 * <td> Formats the argument as a Unicode character as described in <a
796 * href="../lang/Character.html#unicode">Unicode Character
797 * Representation</a>. This may be more than one 16-bit {@code char} in
798 * the case where the argument represents a supplementary character.
799 *
800 * <p> If the {@code '#'} flag is given, then a {@link
801 * FormatFlagsConversionMismatchException} will be thrown.
802 *
803 * <tr><td valign="top"> {@code 'C'}
804 * <td valign="top"> <tt>'\u0043'</tt>
805 * <td> The upper-case variant of {@code 'c'}.
806 *
807 * </table>
808 *
809 * <p> The {@code '-'} flag defined for <a href="#dFlags">General
810 * conversions</a> applies. If the {@code '#'} flag is given, then a {@link
811 * FormatFlagsConversionMismatchException} will be thrown.
812 *
813 * <p> The width is defined as for <a href="#genWidth">General conversions</a>.
814 *
815 * <p> The precision is not applicable. If the precision is specified then an
816 * {@link IllegalFormatPrecisionException} will be thrown.
817 *
818 * <h4><a name="dnum">Numeric</a></h4>
819 *
820 * <p> Numeric conversions are divided into the following categories:
821 *
822 * <ol>
823 *
824 * <li> <a href="#dnint"><b>Byte, Short, Integer, and Long</b></a>
825 *
826 * <li> <a href="#dnbint"><b>BigInteger</b></a>
827 *
828 * <li> <a href="#dndec"><b>Float and Double</b></a>
829 *
830 * <li> <a href="#dndec"><b>BigDecimal</b></a>
831 *
832 * </ol>
833 *
834 * <p> Numeric types will be formatted according to the following algorithm:
835 *
836 * <p><b><a name="l10n algorithm"> Number Localization Algorithm</a></b>
837 *
838 * <p> After digits are obtained for the integer part, fractional part, and
839 * exponent (as appropriate for the data type), the following transformation
840 * is applied:
841 *
842 * <ol>
843 *
844 * <li> Each digit character <i>d</i> in the string is replaced by a
845 * locale-specific digit computed relative to the current locale's
846 * {@linkplain java.text.DecimalFormatSymbols#getZeroDigit() zero digit}
847 * <i>z</i>; that is <i>d - </i> {@code '0'}
848 * <i> + z</i>.
849 *
850 * <li> If a decimal separator is present, a locale-specific {@linkplain
851 * java.text.DecimalFormatSymbols#getDecimalSeparator decimal separator} is
852 * substituted.
853 *
854 * <li> If the {@code ','} (<tt>'\u002c'</tt>)
855 * <a name="l10n group">flag</a> is given, then the locale-specific {@linkplain
856 * java.text.DecimalFormatSymbols#getGroupingSeparator grouping separator} is
857 * inserted by scanning the integer part of the string from least significant
858 * to most significant digits and inserting a separator at intervals defined by
859 * the locale's {@linkplain java.text.DecimalFormat#getGroupingSize() grouping
860 * size}.
861 *
862 * <li> If the {@code '0'} flag is given, then the locale-specific {@linkplain
863 * java.text.DecimalFormatSymbols#getZeroDigit() zero digits} are inserted
864 * after the sign character, if any, and before the first non-zero digit, until
865 * the length of the string is equal to the requested field width.
866 *
867 * <li> If the value is negative and the {@code '('} flag is given, then a
868 * {@code '('} (<tt>'\u0028'</tt>) is prepended and a {@code ')'}
869 * (<tt>'\u0029'</tt>) is appended.
870 *
871 * <li> If the value is negative (or floating-point negative zero) and
872 * {@code '('} flag is not given, then a {@code '-'} (<tt>'\u002d'</tt>)
873 * is prepended.
874 *
875 * <li> If the {@code '+'} flag is given and the value is positive or zero (or
876 * floating-point positive zero), then a {@code '+'} (<tt>'\u002b'</tt>)
877 * will be prepended.
878 *
879 * </ol>
880 *
881 * <p> If the value is NaN or positive infinity the literal strings "NaN" or
882 * "Infinity" respectively, will be output. If the value is negative infinity,
883 * then the output will be "(Infinity)" if the {@code '('} flag is given
884 * otherwise the output will be "-Infinity". These values are not localized.
885 *
886 * <p><a name="dnint"><b> Byte, Short, Integer, and Long </b></a>
887 *
888 * <p> The following conversions may be applied to {@code byte}, {@link Byte},
889 * {@code short}, {@link Short}, {@code int} and {@link Integer},
890 * {@code long}, and {@link Long}.
891 *
892 * <table cellpadding=5 summary="IntConv">
893 *
894 * <tr><td valign="top"> {@code 'd'}
895 * <td valign="top"> <tt>'\u0054'</tt>
896 * <td> Formats the argument as a decimal integer. The <a
897 * href="#l10n algorithm">localization algorithm</a> is applied.
898 *
899 * <p> If the {@code '0'} flag is given and the value is negative, then
900 * the zero padding will occur after the sign.
901 *
902 * <p> If the {@code '#'} flag is given then a {@link
903 * FormatFlagsConversionMismatchException} will be thrown.
904 *
905 * <tr><td valign="top"> {@code 'o'}
906 * <td valign="top"> <tt>'\u006f'</tt>
907 * <td> Formats the argument as an integer in base eight. No localization
908 * is applied.
909 *
910 * <p> If <i>x</i> is negative then the result will be an unsigned value
911 * generated by adding 2<sup>n</sup> to the value where {@code n} is the
912 * number of bits in the type as returned by the static {@code SIZE} field
913 * in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short},
914 * {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long}
915 * classes as appropriate.
916 *
917 * <p> If the {@code '#'} flag is given then the output will always begin
918 * with the radix indicator {@code '0'}.
919 *
920 * <p> If the {@code '0'} flag is given then the output will be padded
921 * with leading zeros to the field width following any indication of sign.
922 *
923 * <p> If {@code '('}, {@code '+'}, '  ', or {@code ','} flags
924 * are given then a {@link FormatFlagsConversionMismatchException} will be
925 * thrown.
926 *
927 * <tr><td valign="top"> {@code 'x'}
928 * <td valign="top"> <tt>'\u0078'</tt>
929 * <td> Formats the argument as an integer in base sixteen. No
930 * localization is applied.
931 *
932 * <p> If <i>x</i> is negative then the result will be an unsigned value
933 * generated by adding 2<sup>n</sup> to the value where {@code n} is the
934 * number of bits in the type as returned by the static {@code SIZE} field
935 * in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short},
936 * {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long}
937 * classes as appropriate.
938 *
939 * <p> If the {@code '#'} flag is given then the output will always begin
940 * with the radix indicator {@code "0x"}.
941 *
942 * <p> If the {@code '0'} flag is given then the output will be padded to
943 * the field width with leading zeros after the radix indicator or sign (if
944 * present).
945 *
946 * <p> If {@code '('}, <tt>' '</tt>, {@code '+'}, or
947 * {@code ','} flags are given then a {@link
948 * FormatFlagsConversionMismatchException} will be thrown.
949 *
950 * <tr><td valign="top"> {@code 'X'}
951 * <td valign="top"> <tt>'\u0058'</tt>
952 * <td> The upper-case variant of {@code 'x'}. The entire string
953 * representing the number will be converted to {@linkplain
954 * String#toUpperCase upper case} including the {@code 'x'} (if any) and
955 * all hexadecimal digits {@code 'a'} - {@code 'f'}
956 * (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>).
957 *
958 * </table>
959 *
960 * <p> If the conversion is {@code 'o'}, {@code 'x'}, or {@code 'X'} and
961 * both the {@code '#'} and the {@code '0'} flags are given, then result will
962 * contain the radix indicator ({@code '0'} for octal and {@code "0x"} or
963 * {@code "0X"} for hexadecimal), some number of zeros (based on the width),
964 * and the value.
965 *
966 * <p> If the {@code '-'} flag is not given, then the space padding will occur
967 * before the sign.
968 *
969 * <p> The following <a name="intFlags">flags</a> apply to numeric integral
970 * conversions:
971 *
972 * <table cellpadding=5 summary="intFlags">
973 *
974 * <tr><td valign="top"> {@code '+'}
975 * <td valign="top"> <tt>'\u002b'</tt>
976 * <td> Requires the output to include a positive sign for all positive
977 * numbers. If this flag is not given then only negative values will
978 * include a sign.
979 *
980 * <p> If both the {@code '+'} and <tt>' '</tt> flags are given
981 * then an {@link IllegalFormatFlagsException} will be thrown.
982 *
983 * <tr><td valign="top"> <tt>' '</tt>
984 * <td valign="top"> <tt>'\u0020'</tt>
985 * <td> Requires the output to include a single extra space
986 * (<tt>'\u0020'</tt>) for non-negative values.
987 *
988 * <p> If both the {@code '+'} and <tt>' '</tt> flags are given
989 * then an {@link IllegalFormatFlagsException} will be thrown.
990 *
991 * <tr><td valign="top"> {@code '0'}
992 * <td valign="top"> <tt>'\u0030'</tt>
993 * <td> Requires the output to be padded with leading {@linkplain
994 * java.text.DecimalFormatSymbols#getZeroDigit zeros} to the minimum field
995 * width following any sign or radix indicator except when converting NaN
996 * or infinity. If the width is not provided, then a {@link
997 * MissingFormatWidthException} will be thrown.
998 *
999 * <p> If both the {@code '-'} and {@code '0'} flags are given then an
1000 * {@link IllegalFormatFlagsException} will be thrown.
1001 *
1002 * <tr><td valign="top"> {@code ','}
1003 * <td valign="top"> <tt>'\u002c'</tt>
1004 * <td> Requires the output to include the locale-specific {@linkplain
1005 * java.text.DecimalFormatSymbols#getGroupingSeparator group separators} as
1006 * described in the <a href="#l10n group">"group" section</a> of the
1007 * localization algorithm.
1008 *
1009 * <tr><td valign="top"> {@code '('}
1010 * <td valign="top"> <tt>'\u0028'</tt>
1011 * <td> Requires the output to prepend a {@code '('}
1012 * (<tt>'\u0028'</tt>) and append a {@code ')'}
1013 * (<tt>'\u0029'</tt>) to negative values.
1014 *
1015 * </table>
1016 *
1017 * <p> If no <a name="intdFlags">flags</a> are given the default formatting is
1018 * as follows:
1019 *
1020 * <ul>
1021 *
1022 * <li> The output is right-justified within the {@code width}
1023 *
1024 * <li> Negative numbers begin with a {@code '-'} (<tt>'\u002d'</tt>)
1025 *
1026 * <li> Positive numbers and zero do not include a sign or extra leading
1027 * space
1028 *
1029 * <li> No grouping separators are included
1030 *
1031 * </ul>
1032 *
1033 * <p> The <a name="intWidth">width</a> is the minimum number of characters to
1034 * be written to the output. This includes any signs, digits, grouping
1035 * separators, radix indicator, and parentheses. If the length of the
1036 * converted value is less than the width then the output will be padded by
1037 * spaces (<tt>'\u0020'</tt>) until the total number of characters equals
1038 * width. The padding is on the left by default. If {@code '-'} flag is
1039 * given then the padding will be on the right. If width is not specified then
1040 * there is no minimum.
1041 *
1042 * <p> The precision is not applicable. If precision is specified then an
1043 * {@link IllegalFormatPrecisionException} will be thrown.
1044 *
1045 * <p><a name="dnbint"><b> BigInteger </b></a>
1046 *
1047 * <p> The following conversions may be applied to {@link
1048 * java.math.BigInteger}.
1049 *
1050 * <table cellpadding=5 summary="BIntConv">
1051 *
1052 * <tr><td valign="top"> {@code 'd'}
1053 * <td valign="top"> <tt>'\u0054'</tt>
1054 * <td> Requires the output to be formatted as a decimal integer. The <a
1055 * href="#l10n algorithm">localization algorithm</a> is applied.
1056 *
1057 * <p> If the {@code '#'} flag is given {@link
1058 * FormatFlagsConversionMismatchException} will be thrown.
1059 *
1060 * <tr><td valign="top"> {@code 'o'}
1061 * <td valign="top"> <tt>'\u006f'</tt>
1062 * <td> Requires the output to be formatted as an integer in base eight.
1063 * No localization is applied.
1064 *
1065 * <p> If <i>x</i> is negative then the result will be a signed value
1066 * beginning with {@code '-'} (<tt>'\u002d'</tt>). Signed output is
1067 * allowed for this type because unlike the primitive types it is not
1068 * possible to create an unsigned equivalent without assuming an explicit
1069 * data-type size.
1070 *
1071 * <p> If <i>x</i> is positive or zero and the {@code '+'} flag is given
1072 * then the result will begin with {@code '+'} (<tt>'\u002b'</tt>).
1073 *
1074 * <p> If the {@code '#'} flag is given then the output will always begin
1075 * with {@code '0'} prefix.
1076 *
1077 * <p> If the {@code '0'} flag is given then the output will be padded
1078 * with leading zeros to the field width following any indication of sign.
1079 *
1080 * <p> If the {@code ','} flag is given then a {@link
1081 * FormatFlagsConversionMismatchException} will be thrown.
1082 *
1083 * <tr><td valign="top"> {@code 'x'}
1084 * <td valign="top"> <tt>'\u0078'</tt>
1085 * <td> Requires the output to be formatted as an integer in base
1086 * sixteen. No localization is applied.
1087 *
1088 * <p> If <i>x</i> is negative then the result will be a signed value
1089 * beginning with {@code '-'} (<tt>'\u002d'</tt>). Signed output is
1090 * allowed for this type because unlike the primitive types it is not
1091 * possible to create an unsigned equivalent without assuming an explicit
1092 * data-type size.
1093 *
1094 * <p> If <i>x</i> is positive or zero and the {@code '+'} flag is given
1095 * then the result will begin with {@code '+'} (<tt>'\u002b'</tt>).
1096 *
1097 * <p> If the {@code '#'} flag is given then the output will always begin
1098 * with the radix indicator {@code "0x"}.
1099 *
1100 * <p> If the {@code '0'} flag is given then the output will be padded to
1101 * the field width with leading zeros after the radix indicator or sign (if
1102 * present).
1103 *
1104 * <p> If the {@code ','} flag is given then a {@link
1105 * FormatFlagsConversionMismatchException} will be thrown.
1106 *
1107 * <tr><td valign="top"> {@code 'X'}
1108 * <td valign="top"> <tt>'\u0058'</tt>
1109 * <td> The upper-case variant of {@code 'x'}. The entire string
1110 * representing the number will be converted to {@linkplain
1111 * String#toUpperCase upper case} including the {@code 'x'} (if any) and
1112 * all hexadecimal digits {@code 'a'} - {@code 'f'}
1113 * (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>).
1114 *
1115 * </table>
1116 *
1117 * <p> If the conversion is {@code 'o'}, {@code 'x'}, or {@code 'X'} and
1118 * both the {@code '#'} and the {@code '0'} flags are given, then result will
1119 * contain the base indicator ({@code '0'} for octal and {@code "0x"} or
1120 * {@code "0X"} for hexadecimal), some number of zeros (based on the width),
1121 * and the value.
1122 *
1123 * <p> If the {@code '0'} flag is given and the value is negative, then the
1124 * zero padding will occur after the sign.
1125 *
1126 * <p> If the {@code '-'} flag is not given, then the space padding will occur
1127 * before the sign.
1128 *
1129 * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1130 * Long apply. The <a href="#intdFlags">default behavior</a> when no flags are
1131 * given is the same as for Byte, Short, Integer, and Long.
1132 *
1133 * <p> The specification of <a href="#intWidth">width</a> is the same as
1134 * defined for Byte, Short, Integer, and Long.
1135 *
1136 * <p> The precision is not applicable. If precision is specified then an
1137 * {@link IllegalFormatPrecisionException} will be thrown.
1138 *
1139 * <p><a name="dndec"><b> Float and Double</b></a>
1140 *
1141 * <p> The following conversions may be applied to {@code float}, {@link
1142 * Float}, {@code double} and {@link Double}.
1143 *
1144 * <table cellpadding=5 summary="floatConv">
1145 *
1146 * <tr><td valign="top"> {@code 'e'}
1147 * <td valign="top"> <tt>'\u0065'</tt>
1148 * <td> Requires the output to be formatted using <a
1149 * name="scientific">computerized scientific notation</a>. The <a
1150 * href="#l10n algorithm">localization algorithm</a> is applied.
1151 *
1152 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1153 *
1154 * <p> If <i>m</i> is NaN or infinite, the literal strings "NaN" or
1155 * "Infinity", respectively, will be output. These values are not
1156 * localized.
1157 *
1158 * <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1159 * will be {@code "+00"}.
1160 *
1161 * <p> Otherwise, the result is a string that represents the sign and
1162 * magnitude (absolute value) of the argument. The formatting of the sign
1163 * is described in the <a href="#l10n algorithm">localization
1164 * algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1165 * value.
1166 *
1167 * <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
1168 * <= <i>m</i> < 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
1169 * mathematically exact quotient of <i>m</i> and 10<sup><i>n</i></sup> so
1170 * that 1 <= <i>a</i> < 10. The magnitude is then represented as the
1171 * integer part of <i>a</i>, as a single decimal digit, followed by the
1172 * decimal separator followed by decimal digits representing the fractional
1173 * part of <i>a</i>, followed by the exponent symbol {@code 'e'}
1174 * (<tt>'\u0065'</tt>), followed by the sign of the exponent, followed
1175 * by a representation of <i>n</i> as a decimal integer, as produced by the
1176 * method {@link Long#toString(long, int)}, and zero-padded to include at
1177 * least two digits.
1178 *
1179 * <p> The number of digits in the result for the fractional part of
1180 * <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1181 * specified then the default value is {@code 6}. If the precision is less
1182 * than the number of digits which would appear after the decimal point in
1183 * the string returned by {@link Float#toString(float)} or {@link
1184 * Double#toString(double)} respectively, then the value will be rounded
1185 * using the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1186 * algorithm}. Otherwise, zeros may be appended to reach the precision.
1187 * For a canonical representation of the value, use {@link
1188 * Float#toString(float)} or {@link Double#toString(double)} as
1189 * appropriate.
1190 *
1191 * <p>If the {@code ','} flag is given, then an {@link
1192 * FormatFlagsConversionMismatchException} will be thrown.
1193 *
1194 * <tr><td valign="top"> {@code 'E'}
1195 * <td valign="top"> <tt>'\u0045'</tt>
1196 * <td> The upper-case variant of {@code 'e'}. The exponent symbol
1197 * will be {@code 'E'} (<tt>'\u0045'</tt>).
1198 *
1199 * <tr><td valign="top"> {@code 'g'}
1200 * <td valign="top"> <tt>'\u0067'</tt>
1201 * <td> Requires the output to be formatted in general scientific notation
1202 * as described below. The <a href="#l10n algorithm">localization
1203 * algorithm</a> is applied.
1204 *
1205 * <p> After rounding for the precision, the formatting of the resulting
1206 * magnitude <i>m</i> depends on its value.
1207 *
1208 * <p> If <i>m</i> is greater than or equal to 10<sup>-4</sup> but less
1209 * than 10<sup>precision</sup> then it is represented in <i><a
1210 * href="#decimal">decimal format</a></i>.
1211 *
1212 * <p> If <i>m</i> is less than 10<sup>-4</sup> or greater than or equal to
1213 * 10<sup>precision</sup>, then it is represented in <i><a
1214 * href="#scientific">computerized scientific notation</a></i>.
1215 *
1216 * <p> The total number of significant digits in <i>m</i> is equal to the
1217 * precision. If the precision is not specified, then the default value is
1218 * {@code 6}. If the precision is {@code 0}, then it is taken to be
1219 * {@code 1}.
1220 *
1221 * <p> If the {@code '#'} flag is given then an {@link
1222 * FormatFlagsConversionMismatchException} will be thrown.
1223 *
1224 * <tr><td valign="top"> {@code 'G'}
1225 * <td valign="top"> <tt>'\u0047'</tt>
1226 * <td> The upper-case variant of {@code 'g'}.
1227 *
1228 * <tr><td valign="top"> {@code 'f'}
1229 * <td valign="top"> <tt>'\u0066'</tt>
1230 * <td> Requires the output to be formatted using <a name="decimal">decimal
1231 * format</a>. The <a href="#l10n algorithm">localization algorithm</a> is
1232 * applied.
1233 *
1234 * <p> The result is a string that represents the sign and magnitude
1235 * (absolute value) of the argument. The formatting of the sign is
1236 * described in the <a href="#l10n algorithm">localization
1237 * algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1238 * value.
1239 *
1240 * <p> If <i>m</i> NaN or infinite, the literal strings "NaN" or
1241 * "Infinity", respectively, will be output. These values are not
1242 * localized.
1243 *
1244 * <p> The magnitude is formatted as the integer part of <i>m</i>, with no
1245 * leading zeroes, followed by the decimal separator followed by one or
1246 * more decimal digits representing the fractional part of <i>m</i>.
1247 *
1248 * <p> The number of digits in the result for the fractional part of
1249 * <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1250 * specified then the default value is {@code 6}. If the precision is less
1251 * than the number of digits which would appear after the decimal point in
1252 * the string returned by {@link Float#toString(float)} or {@link
1253 * Double#toString(double)} respectively, then the value will be rounded
1254 * using the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1255 * algorithm}. Otherwise, zeros may be appended to reach the precision.
1256 * For a canonical representation of the value, use {@link
1257 * Float#toString(float)} or {@link Double#toString(double)} as
1258 * appropriate.
1259 *
1260 * <tr><td valign="top"> {@code 'a'}
1261 * <td valign="top"> <tt>'\u0061'</tt>
1262 * <td> Requires the output to be formatted in hexadecimal exponential
1263 * form. No localization is applied.
1264 *
1265 * <p> The result is a string that represents the sign and magnitude
1266 * (absolute value) of the argument <i>x</i>.
1267 *
1268 * <p> If <i>x</i> is negative or a negative-zero value then the result
1269 * will begin with {@code '-'} (<tt>'\u002d'</tt>).
1270 *
1271 * <p> If <i>x</i> is positive or a positive-zero value and the
1272 * {@code '+'} flag is given then the result will begin with {@code '+'}
1273 * (<tt>'\u002b'</tt>).
1274 *
1275 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1276 *
1277 * <ul>
1278 *
1279 * <li> If the value is NaN or infinite, the literal strings "NaN" or
1280 * "Infinity", respectively, will be output.
1281 *
1282 * <li> If <i>m</i> is zero then it is represented by the string
1283 * {@code "0x0.0p0"}.
1284 *
1285 * <li> If <i>m</i> is a {@code double} value with a normalized
1286 * representation then substrings are used to represent the significand and
1287 * exponent fields. The significand is represented by the characters
1288 * {@code "0x1."} followed by the hexadecimal representation of the rest
1289 * of the significand as a fraction. The exponent is represented by
1290 * {@code 'p'} (<tt>'\u0070'</tt>) followed by a decimal string of the
1291 * unbiased exponent as if produced by invoking {@link
1292 * Integer#toString(int) Integer.toString} on the exponent value.
1293 *
1294 * <li> If <i>m</i> is a {@code double} value with a subnormal
1295 * representation then the significand is represented by the characters
1296 * {@code '0x0.'} followed by the hexadecimal representation of the rest
1297 * of the significand as a fraction. The exponent is represented by
1298 * {@code 'p-1022'}. Note that there must be at least one nonzero digit
1299 * in a subnormal significand.
1300 *
1301 * </ul>
1302 *
1303 * <p> If the {@code '('} or {@code ','} flags are given, then a {@link
1304 * FormatFlagsConversionMismatchException} will be thrown.
1305 *
1306 * <tr><td valign="top"> {@code 'A'}
1307 * <td valign="top"> <tt>'\u0041'</tt>
1308 * <td> The upper-case variant of {@code 'a'}. The entire string
1309 * representing the number will be converted to upper case including the
1310 * {@code 'x'} (<tt>'\u0078'</tt>) and {@code 'p'}
1311 * (<tt>'\u0070'</tt> and all hexadecimal digits {@code 'a'} -
1312 * {@code 'f'} (<tt>'\u0061'</tt> - <tt>'\u0066'</tt>).
1313 *
1314 * </table>
1315 *
1316 * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1317 * Long apply.
1318 *
1319 * <p> If the {@code '#'} flag is given, then the decimal separator will
1320 * always be present.
1321 *
1322 * <p> If no <a name="floatdFlags">flags</a> are given the default formatting
1323 * is as follows:
1324 *
1325 * <ul>
1326 *
1327 * <li> The output is right-justified within the {@code width}
1328 *
1329 * <li> Negative numbers begin with a {@code '-'}
1330 *
1331 * <li> Positive numbers and positive zero do not include a sign or extra
1332 * leading space
1333 *
1334 * <li> No grouping separators are included
1335 *
1336 * <li> The decimal separator will only appear if a digit follows it
1337 *
1338 * </ul>
1339 *
1340 * <p> The <a name="floatDWidth">width</a> is the minimum number of characters
1341 * to be written to the output. This includes any signs, digits, grouping
1342 * separators, decimal separators, exponential symbol, radix indicator,
1343 * parentheses, and strings representing infinity and NaN as applicable. If
1344 * the length of the converted value is less than the width then the output
1345 * will be padded by spaces (<tt>'\u0020'</tt>) until the total number of
1346 * characters equals width. The padding is on the left by default. If the
1347 * {@code '-'} flag is given then the padding will be on the right. If width
1348 * is not specified then there is no minimum.
1349 *
1350 * <p> If the <a name="floatDPrec">conversion</a> is {@code 'e'},
1351 * {@code 'E'} or {@code 'f'}, then the precision is the number of digits
1352 * after the decimal separator. If the precision is not specified, then it is
1353 * assumed to be {@code 6}.
1354 *
1355 * <p> If the conversion is {@code 'g'} or {@code 'G'}, then the precision is
1356 * the total number of significant digits in the resulting magnitude after
1357 * rounding. If the precision is not specified, then the default value is
1358 * {@code 6}. If the precision is {@code 0}, then it is taken to be
1359 * {@code 1}.
1360 *
1361 * <p> If the conversion is {@code 'a'} or {@code 'A'}, then the precision
1362 * is the number of hexadecimal digits after the decimal separator. If the
1363 * precision is not provided, then all of the digits as returned by {@link
1364 * Double#toHexString(double)} will be output.
1365 *
1366 * <p><a name="dndec"><b> BigDecimal </b></a>
1367 *
1368 * <p> The following conversions may be applied {@link java.math.BigDecimal
1369 * BigDecimal}.
1370 *
1371 * <table cellpadding=5 summary="floatConv">
1372 *
1373 * <tr><td valign="top"> {@code 'e'}
1374 * <td valign="top"> <tt>'\u0065'</tt>
1375 * <td> Requires the output to be formatted using <a
1376 * name="scientific">computerized scientific notation</a>. The <a
1377 * href="#l10n algorithm">localization algorithm</a> is applied.
1378 *
1379 * <p> The formatting of the magnitude <i>m</i> depends upon its value.
1380 *
1381 * <p> If <i>m</i> is positive-zero or negative-zero, then the exponent
1382 * will be {@code "+00"}.
1383 *
1384 * <p> Otherwise, the result is a string that represents the sign and
1385 * magnitude (absolute value) of the argument. The formatting of the sign
1386 * is described in the <a href="#l10n algorithm">localization
1387 * algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1388 * value.
1389 *
1390 * <p> Let <i>n</i> be the unique integer such that 10<sup><i>n</i></sup>
1391 * <= <i>m</i> < 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
1392 * mathematically exact quotient of <i>m</i> and 10<sup><i>n</i></sup> so
1393 * that 1 <= <i>a</i> < 10. The magnitude is then represented as the
1394 * integer part of <i>a</i>, as a single decimal digit, followed by the
1395 * decimal separator followed by decimal digits representing the fractional
1396 * part of <i>a</i>, followed by the exponent symbol {@code 'e'}
1397 * (<tt>'\u0065'</tt>), followed by the sign of the exponent, followed
1398 * by a representation of <i>n</i> as a decimal integer, as produced by the
1399 * method {@link Long#toString(long, int)}, and zero-padded to include at
1400 * least two digits.
1401 *
1402 * <p> The number of digits in the result for the fractional part of
1403 * <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1404 * specified then the default value is {@code 6}. If the precision is
1405 * less than the number of digits which would appear after the decimal
1406 * point in the string returned by {@link Float#toString(float)} or {@link
1407 * Double#toString(double)} respectively, then the value will be rounded
1408 * using the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1409 * algorithm}. Otherwise, zeros may be appended to reach the precision.
1410 * For a canonical representation of the value, use {@link
1411 * BigDecimal#toString()}.
1412 *
1413 * <p> If the {@code ','} flag is given, then an {@link
1414 * FormatFlagsConversionMismatchException} will be thrown.
1415 *
1416 * <tr><td valign="top"> {@code 'E'}
1417 * <td valign="top"> <tt>'\u0045'</tt>
1418 * <td> The upper-case variant of {@code 'e'}. The exponent symbol
1419 * will be {@code 'E'} (<tt>'\u0045'</tt>).
1420 *
1421 * <tr><td valign="top"> {@code 'g'}
1422 * <td valign="top"> <tt>'\u0067'</tt>
1423 * <td> Requires the output to be formatted in general scientific notation
1424 * as described below. The <a href="#l10n algorithm">localization
1425 * algorithm</a> is applied.
1426 *
1427 * <p> After rounding for the precision, the formatting of the resulting
1428 * magnitude <i>m</i> depends on its value.
1429 *
1430 * <p> If <i>m</i> is greater than or equal to 10<sup>-4</sup> but less
1431 * than 10<sup>precision</sup> then it is represented in <i><a
1432 * href="#decimal">decimal format</a></i>.
1433 *
1434 * <p> If <i>m</i> is less than 10<sup>-4</sup> or greater than or equal to
1435 * 10<sup>precision</sup>, then it is represented in <i><a
1436 * href="#scientific">computerized scientific notation</a></i>.
1437 *
1438 * <p> The total number of significant digits in <i>m</i> is equal to the
1439 * precision. If the precision is not specified, then the default value is
1440 * {@code 6}. If the precision is {@code 0}, then it is taken to be
1441 * {@code 1}.
1442 *
1443 * <p> If the {@code '#'} flag is given then an {@link
1444 * FormatFlagsConversionMismatchException} will be thrown.
1445 *
1446 * <tr><td valign="top"> {@code 'G'}
1447 * <td valign="top"> <tt>'\u0047'</tt>
1448 * <td> The upper-case variant of {@code 'g'}.
1449 *
1450 * <tr><td valign="top"> {@code 'f'}
1451 * <td valign="top"> <tt>'\u0066'</tt>
1452 * <td> Requires the output to be formatted using <a name="decimal">decimal
1453 * format</a>. The <a href="#l10n algorithm">localization algorithm</a> is
1454 * applied.
1455 *
1456 * <p> The result is a string that represents the sign and magnitude
1457 * (absolute value) of the argument. The formatting of the sign is
1458 * described in the <a href="#l10n algorithm">localization
1459 * algorithm</a>. The formatting of the magnitude <i>m</i> depends upon its
1460 * value.
1461 *
1462 * <p> The magnitude is formatted as the integer part of <i>m</i>, with no
1463 * leading zeroes, followed by the decimal separator followed by one or
1464 * more decimal digits representing the fractional part of <i>m</i>.
1465 *
1466 * <p> The number of digits in the result for the fractional part of
1467 * <i>m</i> or <i>a</i> is equal to the precision. If the precision is not
1468 * specified then the default value is {@code 6}. If the precision is
1469 * less than the number of digits which would appear after the decimal
1470 * point in the string returned by {@link Float#toString(float)} or {@link
1471 * Double#toString(double)} respectively, then the value will be rounded
1472 * using the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half up
1473 * algorithm}. Otherwise, zeros may be appended to reach the precision.
1474 * For a canonical representation of the value, use {@link
1475 * BigDecimal#toString()}.
1476 *
1477 * </table>
1478 *
1479 * <p> All <a href="#intFlags">flags</a> defined for Byte, Short, Integer, and
1480 * Long apply.
1481 *
1482 * <p> If the {@code '#'} flag is given, then the decimal separator will
1483 * always be present.
1484 *
1485 * <p> The <a href="#floatdFlags">default behavior</a> when no flags are
1486 * given is the same as for Float and Double.
1487 *
1488 * <p> The specification of <a href="#floatDWidth">width</a> and <a
1489 * href="#floatDPrec">precision</a> is the same as defined for Float and
1490 * Double.
1491 *
1492 * <h4><a name="ddt">Date/Time</a></h4>
1493 *
1494 * <p> This conversion may be applied to {@code long}, {@link Long}, {@link
1495 * Calendar}, and {@link Date}.
1496 *
1497 * <table cellpadding=5 summary="DTConv">
1498 *
1499 * <tr><td valign="top"> {@code 't'}
1500 * <td valign="top"> <tt>'\u0074'</tt>
1501 * <td> Prefix for date and time conversion characters.
1502 * <tr><td valign="top"> {@code 'T'}
1503 * <td valign="top"> <tt>'\u0054'</tt>
1504 * <td> The upper-case variant of {@code 't'}.
1505 *
1506 * </table>
1507 *
1508 * <p> The following date and time conversion character suffixes are defined
1509 * for the {@code 't'} and {@code 'T'} conversions. The types are similar to
1510 * but not completely identical to those defined by GNU {@code date} and
1511 * POSIX {@code strftime(3c)}. Additional conversion types are provided to
1512 * access Java-specific functionality (e.g. {@code 'L'} for milliseconds
1513 * within the second).
1514 *
1515 * <p> The following conversion characters are used for formatting times:
1516 *
1517 * <table cellpadding=5 summary="time">
1518 *
1519 * <tr><td valign="top"> {@code 'H'}
1520 * <td valign="top"> <tt>'\u0048'</tt>
1521 * <td> Hour of the day for the 24-hour clock, formatted as two digits with
1522 * a leading zero as necessary i.e. {@code 00 - 23}. {@code 00}
1523 * corresponds to midnight.
1524 *
1525 * <tr><td valign="top">{@code 'I'}
1526 * <td valign="top"> <tt>'\u0049'</tt>
1527 * <td> Hour for the 12-hour clock, formatted as two digits with a leading
1528 * zero as necessary, i.e. {@code 01 - 12}. {@code 01} corresponds to
1529 * one o'clock (either morning or afternoon).
1530 *
1531 * <tr><td valign="top">{@code 'k'}
1532 * <td valign="top"> <tt>'\u006b'</tt>
1533 * <td> Hour of the day for the 24-hour clock, i.e. {@code 0 - 23}.
1534 * {@code 0} corresponds to midnight.
1535 *
1536 * <tr><td valign="top">{@code 'l'}
1537 * <td valign="top"> <tt>'\u006c'</tt>
1538 * <td> Hour for the 12-hour clock, i.e. {@code 1 - 12}. {@code 1}
1539 * corresponds to one o'clock (either morning or afternoon).
1540 *
1541 * <tr><td valign="top">{@code 'M'}
1542 * <td valign="top"> <tt>'\u004d'</tt>
1543 * <td> Minute within the hour formatted as two digits with a leading zero
1544 * as necessary, i.e. {@code 00 - 59}.
1545 *
1546 * <tr><td valign="top">{@code 'S'}
1547 * <td valign="top"> <tt>'\u0053'</tt>
1548 * <td> Seconds within the minute, formatted as two digits with a leading
1549 * zero as necessary, i.e. {@code 00 - 60} ("{@code 60}" is a special
1550 * value required to support leap seconds).
1551 *
1552 * <tr><td valign="top">{@code 'L'}
1553 * <td valign="top"> <tt>'\u004c'</tt>
1554 * <td> Millisecond within the second formatted as three digits with
1555 * leading zeros as necessary, i.e. {@code 000 - 999}.
1556 *
1557 * <tr><td valign="top">{@code 'N'}
1558 * <td valign="top"> <tt>'\u004e'</tt>
1559 * <td> Nanosecond within the second, formatted as nine digits with leading
1560 * zeros as necessary, i.e. {@code 000000000 - 999999999}. The precision
1561 * of this value is limited by the resolution of the underlying operating
1562 * system or hardware.
1563 *
1564 * <tr><td valign="top">{@code 'p'}
1565 * <td valign="top"> <tt>'\u0070'</tt>
1566 * <td> Locale-specific {@linkplain
1567 * java.text.DateFormatSymbols#getAmPmStrings morning or afternoon} marker
1568 * in lower case, e.g."{@code am}" or "{@code pm}". Use of the
1569 * conversion prefix {@code 'T'} forces this output to upper case. (Note
1570 * that {@code 'p'} produces lower-case output. This is different from
1571 * GNU {@code date} and POSIX {@code strftime(3c)} which produce
1572 * upper-case output.)
1573 *
1574 * <tr><td valign="top">{@code 'z'}
1575 * <td valign="top"> <tt>'\u007a'</tt>
1576 * <td> <a href="http://www.ietf.org/rfc/rfc0822.txt">RFC 822</a>
1577 * style numeric time zone offset from GMT, e.g. {@code -0800}. This
1578 * value will be adjusted as necessary for Daylight Saving Time. For
1579 * {@code long}, {@link Long}, and {@link Date} the time zone used is
1580 * the {@linkplain TimeZone#getDefault() default time zone} for this
1581 * instance of the Java virtual machine.
1582 *
1583 * <tr><td valign="top">{@code 'Z'}
1584 * <td> A string representing the abbreviation for the time zone. This
1585 * value will be adjusted as necessary for Daylight Saving Time. For
1586 * {@code long}, {@link Long}, and {@link Date} the time zone used is
1587 * the {@linkplain TimeZone#getDefault() default time zone} for this
1588 * instance of the Java virtual machine. The Formatter's locale will
1589 * supersede the locale of the argument (if any).
1590 *
1591 * <tr><td valign="top">{@code 's'}
1592 * <td valign="top"> <tt>'\u0073'</tt>
1593 * <td> Seconds since the beginning of the epoch starting at 1 January 1970
1594 * {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE/1000} to
1595 * {@code Long.MAX_VALUE/1000}.
1596 *
1597 * <tr><td valign="top">{@code 'Q'}
1598 * <td valign="top"> <tt>'\u004f'</tt>
1599 * <td> Milliseconds since the beginning of the epoch starting at 1 January
1600 * 1970 {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE} to
1601 * {@code Long.MAX_VALUE}. The precision of this value is limited by
1602 * the resolution of the underlying operating system or hardware.
1603 *
1604 * </table>
1605 *
1606 * <p> The following conversion characters are used for formatting dates:
1607 *
1608 * <table cellpadding=5 summary="date">
1609 *
1610 * <tr><td valign="top">{@code 'B'}
1611 * <td valign="top"> <tt>'\u0042'</tt>
1612 * <td> Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths
1613 * full month name}, e.g. {@code "January"}, {@code "February"}.
1614 *
1615 * <tr><td valign="top">{@code 'b'}
1616 * <td valign="top"> <tt>'\u0062'</tt>
1617 * <td> Locale-specific {@linkplain
1618 * java.text.DateFormatSymbols#getShortMonths abbreviated month name},
1619 * e.g. {@code "Jan"}, {@code "Feb"}.
1620 *
1621 * <tr><td valign="top">{@code 'h'}
1622 * <td valign="top"> <tt>'\u0068'</tt>
1623 * <td> Same as {@code 'b'}.
1624 *
1625 * <tr><td valign="top">{@code 'A'}
1626 * <td valign="top"> <tt>'\u0041'</tt>
1627 * <td> Locale-specific full name of the {@linkplain
1628 * java.text.DateFormatSymbols#getWeekdays day of the week},
1629 * e.g. {@code "Sunday"}, {@code "Monday"}
1630 *
1631 * <tr><td valign="top">{@code 'a'}
1632 * <td valign="top"> <tt>'\u0061'</tt>
1633 * <td> Locale-specific short name of the {@linkplain
1634 * java.text.DateFormatSymbols#getShortWeekdays day of the week},
1635 * e.g. {@code "Sun"}, {@code "Mon"}
1636 *
1637 * <tr><td valign="top">{@code 'C'}
1638 * <td valign="top"> <tt>'\u0043'</tt>
1639 * <td> Four-digit year divided by {@code 100}, formatted as two digits
1640 * with leading zero as necessary, i.e. {@code 00 - 99}
1641 *
1642 * <tr><td valign="top">{@code 'Y'}
1643 * <td valign="top"> <tt>'\u0059'</tt> <td> Year, formatted to at least
1644 * four digits with leading zeros as necessary, e.g. {@code 0092} equals
1645 * {@code 92} CE for the Gregorian calendar.
1646 *
1647 * <tr><td valign="top">{@code 'y'}
1648 * <td valign="top"> <tt>'\u0079'</tt>
1649 * <td> Last two digits of the year, formatted with leading zeros as
1650 * necessary, i.e. {@code 00 - 99}.
1651 *
1652 * <tr><td valign="top">{@code 'j'}
1653 * <td valign="top"> <tt>'\u006a'</tt>
1654 * <td> Day of year, formatted as three digits with leading zeros as
1655 * necessary, e.g. {@code 001 - 366} for the Gregorian calendar.
1656 * {@code 001} corresponds to the first day of the year.
1657 *
1658 * <tr><td valign="top">{@code 'm'}
1659 * <td valign="top"> <tt>'\u006d'</tt>
1660 * <td> Month, formatted as two digits with leading zeros as necessary,
1661 * i.e. {@code 01 - 13}, where "{@code 01}" is the first month of the
1662 * year and ("{@code 13}" is a special value required to support lunar
1663 * calendars).
1664 *
1665 * <tr><td valign="top">{@code 'd'}
1666 * <td valign="top"> <tt>'\u0064'</tt>
1667 * <td> Day of month, formatted as two digits with leading zeros as
1668 * necessary, i.e. {@code 01 - 31}, where "{@code 01}" is the first day
1669 * of the month.
1670 *
1671 * <tr><td valign="top">{@code 'e'}
1672 * <td valign="top"> <tt>'\u0065'</tt>
1673 * <td> Day of month, formatted as two digits, i.e. {@code 1 - 31} where
1674 * "{@code 1}" is the first day of the month.
1675 *
1676 * </table>
1677 *
1678 * <p> The following conversion characters are used for formatting common
1679 * date/time compositions.
1680 *
1681 * <table cellpadding=5 summary="composites">
1682 *
1683 * <tr><td valign="top">{@code 'R'}
1684 * <td valign="top"> <tt>'\u0052'</tt>
1685 * <td> Time formatted for the 24-hour clock as {@code "%tH:%tM"}
1686 *
1687 * <tr><td valign="top">{@code 'T'}
1688 * <td valign="top"> <tt>'\u0054'</tt>
1689 * <td> Time formatted for the 24-hour clock as {@code "%tH:%tM:%tS"}.
1690 *
1691 * <tr><td valign="top">{@code 'r'}
1692 * <td valign="top"> <tt>'\u0072'</tt>
1693 * <td> Time formatted for the 12-hour clock as {@code "%tI:%tM:%tS
1694 * %Tp"}. The location of the morning or afternoon marker
1695 * ({@code '%Tp'}) may be locale-dependent.
1696 *
1697 * <tr><td valign="top">{@code 'D'}
1698 * <td valign="top"> <tt>'\u0044'</tt>
1699 * <td> Date formatted as {@code "%tm/%td/%ty"}.
1700 *
1701 * <tr><td valign="top">{@code 'F'}
1702 * <td valign="top"> <tt>'\u0046'</tt>
1703 * <td> <a href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a>
1704 * complete date formatted as {@code "%tY-%tm-%td"}.
1705 *
1706 * <tr><td valign="top">{@code 'c'}
1707 * <td valign="top"> <tt>'\u0063'</tt>
1708 * <td> Date and time formatted as {@code "%ta %tb %td %tT %tZ %tY"},
1709 * e.g. {@code "Sun Jul 20 16:17:00 EDT 1969"}.
1710 *
1711 * </table>
1712 *
1713 * <p> The {@code '-'} flag defined for <a href="#dFlags">General
1714 * conversions</a> applies. If the {@code '#'} flag is given, then a {@link
1715 * FormatFlagsConversionMismatchException} will be thrown.
1716 *
1717 * <p> The <a name="dtWidth">width</a> is the minimum number of characters to
1718 * be written to the output. If the length of the converted value is less than
1719 * the {@code width} then the output will be padded by spaces
1720 * (<tt>'\u0020'</tt>) until the total number of characters equals width.
1721 * The padding is on the left by default. If the {@code '-'} flag is given
1722 * then the padding will be on the right. If width is not specified then there
1723 * is no minimum.
1724 *
1725 * <p> The precision is not applicable. If the precision is specified then an
1726 * {@link IllegalFormatPrecisionException} will be thrown.
1727 *
1728 * <h4><a name="dper">Percent</a></h4>
1729 *
1730 * <p> The conversion does not correspond to any argument.
1731 *
1732 * <table cellpadding=5 summary="DTConv">
1733 *
1734 * <tr><td valign="top">{@code '%'}
1735 * <td> The result is a literal {@code '%'} (<tt>'\u0025'</tt>)
1736 *
1737 * <p> The <a name="dtWidth">width</a> is the minimum number of characters to
1738 * be written to the output including the {@code '%'}. If the length of the
1739 * converted value is less than the {@code width} then the output will be
1740 * padded by spaces (<tt>'\u0020'</tt>) until the total number of
1741 * characters equals width. The padding is on the left. If width is not
1742 * specified then just the {@code '%'} is output.
1743 *
1744 * <p> The {@code '-'} flag defined for <a href="#dFlags">General
1745 * conversions</a> applies. If any other flags are provided, then a
1746 * {@link FormatFlagsConversionMismatchException} will be thrown.
1747 *
1748 * <p> The precision is not applicable. If the precision is specified an
1749 * {@link IllegalFormatPrecisionException} will be thrown.
1750 *
1751 * </table>
1752 *
1753 * <h4><a name="dls">Line Separator</a></h4>
1754 *
1755 * <p> The conversion does not correspond to any argument.
1756 *
1757 * <table cellpadding=5 summary="DTConv">
1758 *
1759 * <tr><td valign="top">{@code 'n'}
1760 * <td> the platform-specific line separator as returned by {@link
1761 * System#getProperty System.getProperty("line.separator")}.
1762 *
1763 * </table>
1764 *
1765 * <p> Flags, width, and precision are not applicable. If any are provided an
1766 * {@link IllegalFormatFlagsException}, {@link IllegalFormatWidthException},
1767 * and {@link IllegalFormatPrecisionException}, respectively will be thrown.
1768 *
1769 * <h4><a name="dpos">Argument Index</a></h4>
1770 *
1771 * <p> Format specifiers can reference arguments in three ways:
1772 *
1773 * <ul>
1774 *
1775 * <li> <i>Explicit indexing</i> is used when the format specifier contains an
1776 * argument index. The argument index is a decimal integer indicating the
1777 * position of the argument in the argument list. The first argument is
1778 * referenced by "{@code 1$}", the second by "{@code 2$}", etc. An argument
1779 * may be referenced more than once.
1780 *
1781 * <p> For example:
1782 *
1783 * <blockquote><pre>
1784 * formatter.format("%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s",
1785 * "a", "b", "c", "d")
1786 * // -> "d c b a d c b a"
1787 * </pre></blockquote>
1788 *
1789 * <li> <i>Relative indexing</i> is used when the format specifier contains a
1790 * {@code '<'} (<tt>'\u003c'</tt>) flag which causes the argument for
1791 * the previous format specifier to be re-used. If there is no previous
1792 * argument, then a {@link MissingFormatArgumentException} is thrown.
1793 *
1794 * <blockquote><pre>
1795 * formatter.format("%s %s %<s %<s", "a", "b", "c", "d")
1796 * // -> "a b b b"
1797 * // "c" and "d" are ignored because they are not referenced
1798 * </pre></blockquote>
1799 *
1800 * <li> <i>Ordinary indexing</i> is used when the format specifier contains
1801 * neither an argument index nor a {@code '<'} flag. Each format specifier
1802 * which uses ordinary indexing is assigned a sequential implicit index into
1803 * argument list which is independent of the indices used by explicit or
1804 * relative indexing.
1805 *
1806 * <blockquote><pre>
1807 * formatter.format("%s %s %s %s", "a", "b", "c", "d")
1808 * // -> "a b c d"
1809 * </pre></blockquote>
1810 *
1811 * </ul>
1812 *
1813 * <p> It is possible to have a format string which uses all forms of indexing,
1814 * for example:
1815 *
1816 * <blockquote><pre>
1817 * formatter.format("%2$s %s %<s %s", "a", "b", "c", "d")
1818 * // -> "b a a b"
1819 * // "c" and "d" are ignored because they are not referenced
1820 * </pre></blockquote>
1821 *
1822 * <p> The maximum number of arguments is limited by the maximum dimension of a
1823 * Java array as defined by the <a
1824 * href="http://java.sun.com/docs/books/vmspec/">Java Virtual Machine
1825 * Specification</a>. If the argument index is does not correspond to an
1826 * available argument, then a {@link MissingFormatArgumentException} is thrown.
1827 *
1828 * <p> If there are more arguments than format specifiers, the extra arguments
1829 * are ignored.
1830 *
1831 * <p> Unless otherwise specified, passing a {@code null} argument to any
1832 * method or constructor in this class will cause a {@link
1833 * NullPointerException} to be thrown.
1834 *
1835 * @author Iris Clark
1836 * @since 1.5
1837 */
1838 public final class Formatter implements Closeable, Flushable {
1839 private Appendable a;
1840 private Locale l;
1841
1842 private IOException lastException;
1843
1844 private char zero = '0';
1845 private static double scaleUp;
1846
1847 // 1 (sign) + 19 (max # sig digits) + 1 ('.') + 1 ('e') + 1 (sign)
1848 // + 3 (max # exp digits) + 4 (error) = 30
1849 private static final int MAX_FD_CHARS = 30;
1850
1851 // Initialize internal data.
1859 * Constructs a new formatter.
1860 *
1861 * <p> The destination of the formatted output is a {@link StringBuilder}
1862 * which may be retrieved by invoking {@link #out out()} and whose
1863 * current content may be converted into a string by invoking {@link
1864 * #toString toString()}. The locale used is the {@linkplain
1865 * Locale#getDefault() default locale} for this instance of the Java
1866 * virtual machine.
1867 */
1868 public Formatter() {
1869 init(new StringBuilder(), Locale.getDefault());
1870 }
1871
1872 /**
1873 * Constructs a new formatter with the specified destination.
1874 *
1875 * <p> The locale used is the {@linkplain Locale#getDefault() default
1876 * locale} for this instance of the Java virtual machine.
1877 *
1878 * @param a
1879 * Destination for the formatted output. If {@code a} is
1880 * {@code null} then a {@link StringBuilder} will be created.
1881 */
1882 public Formatter(Appendable a) {
1883 if (a == null)
1884 a = new StringBuilder();
1885 init(a, Locale.getDefault());
1886 }
1887
1888 /**
1889 * Constructs a new formatter with the specified locale.
1890 *
1891 * <p> The destination of the formatted output is a {@link StringBuilder}
1892 * which may be retrieved by invoking {@link #out out()} and whose current
1893 * content may be converted into a string by invoking {@link #toString
1894 * toString()}.
1895 *
1896 * @param l
1897 * The {@linkplain java.util.Locale locale} to apply during
1898 * formatting. If {@code l} is {@code null} then no localization
1899 * is applied.
1900 */
1901 public Formatter(Locale l) {
1902 init(new StringBuilder(), l);
1903 }
1904
1905 /**
1906 * Constructs a new formatter with the specified destination and locale.
1907 *
1908 * @param a
1909 * Destination for the formatted output. If {@code a} is
1910 * {@code null} then a {@link StringBuilder} will be created.
1911 *
1912 * @param l
1913 * The {@linkplain java.util.Locale locale} to apply during
1914 * formatting. If {@code l} is {@code null} then no localization
1915 * is applied.
1916 */
1917 public Formatter(Appendable a, Locale l) {
1918 if (a == null)
1919 a = new StringBuilder();
1920 init(a, l);
1921 }
1922
1923 /**
1924 * Constructs a new formatter with the specified file name.
1925 *
1926 * <p> The charset used is the {@linkplain
1927 * java.nio.charset.Charset#defaultCharset() default charset} for this
1928 * instance of the Java virtual machine.
1929 *
1930 * <p> The locale used is the {@linkplain Locale#getDefault() default
1931 * locale} for this instance of the Java virtual machine.
1932 *
1933 * @param fileName
1934 * The name of the file to use as the destination of this
1987 {
1988 this(fileName, csn, Locale.getDefault());
1989 }
1990
1991 /**
1992 * Constructs a new formatter with the specified file name, charset, and
1993 * locale.
1994 *
1995 * @param fileName
1996 * The name of the file to use as the destination of this
1997 * formatter. If the file exists then it will be truncated to
1998 * zero size; otherwise, a new file will be created. The output
1999 * will be written to the file and is buffered.
2000 *
2001 * @param csn
2002 * The name of a supported {@linkplain java.nio.charset.Charset
2003 * charset}
2004 *
2005 * @param l
2006 * The {@linkplain java.util.Locale locale} to apply during
2007 * formatting. If {@code l} is {@code null} then no localization
2008 * is applied.
2009 *
2010 * @throws FileNotFoundException
2011 * If the given file name does not denote an existing, writable
2012 * regular file and a new regular file of that name cannot be
2013 * created, or if some other error occurs while opening or
2014 * creating the file
2015 *
2016 * @throws SecurityException
2017 * If a security manager is present and {@link
2018 * SecurityManager#checkWrite checkWrite(fileName)} denies write
2019 * access to the file
2020 *
2021 * @throws UnsupportedEncodingException
2022 * If the named charset is not supported
2023 */
2024 public Formatter(String fileName, String csn, Locale l)
2025 throws FileNotFoundException, UnsupportedEncodingException
2026 {
2027 init(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(fileName), csn)),
2095 {
2096 this(file, csn, Locale.getDefault());
2097 }
2098
2099 /**
2100 * Constructs a new formatter with the specified file, charset, and
2101 * locale.
2102 *
2103 * @param file
2104 * The file to use as the destination of this formatter. If the
2105 * file exists then it will be truncated to zero size; otherwise,
2106 * a new file will be created. The output will be written to the
2107 * file and is buffered.
2108 *
2109 * @param csn
2110 * The name of a supported {@linkplain java.nio.charset.Charset
2111 * charset}
2112 *
2113 * @param l
2114 * The {@linkplain java.util.Locale locale} to apply during
2115 * formatting. If {@code l} is {@code null} then no localization
2116 * is applied.
2117 *
2118 * @throws FileNotFoundException
2119 * If the given file object does not denote an existing, writable
2120 * regular file and a new regular file of that name cannot be
2121 * created, or if some other error occurs while opening or
2122 * creating the file
2123 *
2124 * @throws SecurityException
2125 * If a security manager is present and {@link
2126 * SecurityManager#checkWrite checkWrite(file.getPath())} denies
2127 * write access to the file
2128 *
2129 * @throws UnsupportedEncodingException
2130 * If the named charset is not supported
2131 */
2132 public Formatter(File file, String csn, Locale l)
2133 throws FileNotFoundException, UnsupportedEncodingException
2134 {
2135 init(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file), csn)),
2195 public Formatter(OutputStream os, String csn)
2196 throws UnsupportedEncodingException
2197 {
2198 this(os, csn, Locale.getDefault());
2199 }
2200
2201 /**
2202 * Constructs a new formatter with the specified output stream, charset,
2203 * and locale.
2204 *
2205 * @param os
2206 * The output stream to use as the destination of this formatter.
2207 * The output will be buffered.
2208 *
2209 * @param csn
2210 * The name of a supported {@linkplain java.nio.charset.Charset
2211 * charset}
2212 *
2213 * @param l
2214 * The {@linkplain java.util.Locale locale} to apply during
2215 * formatting. If {@code l} is {@code null} then no localization
2216 * is applied.
2217 *
2218 * @throws UnsupportedEncodingException
2219 * If the named charset is not supported
2220 */
2221 public Formatter(OutputStream os, String csn, Locale l)
2222 throws UnsupportedEncodingException
2223 {
2224 init(new BufferedWriter(new OutputStreamWriter(os, csn)), l);
2225 }
2226
2227 private void setZero() {
2228 if ((l != null) && !l.equals(Locale.US)) {
2229 DecimalFormatSymbols dfs = DecimalFormatSymbols.getInstance(l);
2230 zero = dfs.getZeroDigit();
2231 }
2232 }
2233
2234 /**
2235 * Returns the locale set by the construction of this formatter.
2236 *
2237 * <p> The {@link #format(java.util.Locale,String,Object...) format} method
2238 * for this object which has a locale argument does not change this value.
2239 *
2240 * @return {@code null} if no localization is applied, otherwise a
2241 * locale
2242 *
2243 * @throws FormatterClosedException
2244 * If this formatter has been closed by invoking its {@link
2245 * #close()} method
2246 */
2247 public Locale locale() {
2248 ensureOpen();
2249 return l;
2250 }
2251
2252 /**
2253 * Returns the destination for the output.
2254 *
2255 * @return The destination for the output
2256 *
2257 * @throws FormatterClosedException
2258 * If this formatter has been closed by invoking its {@link
2259 * #close()} method
2260 */
2261 public Appendable out() {
2262 ensureOpen();
2263 return a;
2264 }
2265
2266 /**
2267 * Returns the result of invoking {@code toString()} on the destination
2268 * for the output. For example, the following code formats text into a
2269 * {@link StringBuilder} then retrieves the resultant string:
2270 *
2271 * <blockquote><pre>
2272 * Formatter f = new Formatter();
2273 * f.format("Last reboot at %tc", lastRebootDate);
2274 * String s = f.toString();
2275 * // -> s == "Last reboot at Sat Jan 01 00:00:00 PST 2000"
2276 * </pre></blockquote>
2277 *
2278 * <p> An invocation of this method behaves in exactly the same way as the
2279 * invocation
2280 *
2281 * <pre>
2282 * out().toString() </pre>
2283 *
2284 * <p> Depending on the specification of {@code toString} for the {@link
2285 * Appendable}, the returned string may or may not contain the characters
2286 * written to the destination. For instance, buffers typically return
2287 * their contents in {@code toString()}, but streams cannot since the
2288 * data is discarded.
2289 *
2290 * @return The result of invoking {@code toString()} on the destination
2291 * for the output
2292 *
2293 * @throws FormatterClosedException
2294 * If this formatter has been closed by invoking its {@link
2295 * #close()} method
2296 */
2297 public String toString() {
2298 ensureOpen();
2299 return a.toString();
2300 }
2301
2302 /**
2303 * Flushes this formatter. If the destination implements the {@link
2304 * java.io.Flushable} interface, its {@code flush} method will be invoked.
2305 *
2306 * <p> Flushing a formatter writes any buffered output in the destination
2307 * to the underlying stream.
2308 *
2309 * @throws FormatterClosedException
2310 * If this formatter has been closed by invoking its {@link
2311 * #close()} method
2312 */
2313 public void flush() {
2314 ensureOpen();
2315 if (a instanceof Flushable) {
2316 try {
2317 ((Flushable)a).flush();
2318 } catch (IOException ioe) {
2319 lastException = ioe;
2320 }
2321 }
2322 }
2323
2324 /**
2325 * Closes this formatter. If the destination implements the {@link
2326 * java.io.Closeable} interface, its {@code close} method will be invoked.
2327 *
2328 * <p> Closing a formatter allows it to release resources it may be holding
2329 * (such as open files). If the formatter is already closed, then invoking
2330 * this method has no effect.
2331 *
2332 * <p> Attempting to invoke any methods except {@link #ioException()} in
2333 * this formatter after it has been closed will result in a {@link
2334 * FormatterClosedException}.
2335 */
2336 public void close() {
2337 if (a == null)
2338 return;
2339 try {
2340 if (a instanceof Closeable)
2341 ((Closeable)a).close();
2342 } catch (IOException ioe) {
2343 lastException = ioe;
2344 } finally {
2345 a = null;
2346 }
2347 }
2348
2349 private void ensureOpen() {
2350 if (a == null)
2351 throw new FormatterClosedException();
2352 }
2353
2354 /**
2355 * Returns the {@code IOException} last thrown by this formatter's {@link
2356 * Appendable}.
2357 *
2358 * <p> If the destination's {@code append()} method never throws
2359 * {@code IOException}, then this method will always return {@code null}.
2360 *
2361 * @return The last exception thrown by the Appendable or {@code null} if
2362 * no such exception exists.
2363 */
2364 public IOException ioException() {
2365 return lastException;
2366 }
2367
2368 /**
2369 * Writes a formatted string to this object's destination using the
2370 * specified format string and arguments. The locale used is the one
2371 * defined during the construction of this formatter.
2372 *
2373 * @param format
2374 * A format string as described in <a href="#syntax">Format string
2375 * syntax</a>.
2376 *
2377 * @param args
2378 * Arguments referenced by the format specifiers in the format
2379 * string. If there are more arguments than format specifiers, the
2380 * extra arguments are ignored. The maximum number of arguments is
2381 * limited by the maximum dimension of a Java array as defined by
2389 * illegal conditions. For specification of all possible
2390 * formatting errors, see the <a href="#detail">Details</a>
2391 * section of the formatter class specification.
2392 *
2393 * @throws FormatterClosedException
2394 * If this formatter has been closed by invoking its {@link
2395 * #close()} method
2396 *
2397 * @return This formatter
2398 */
2399 public Formatter format(String format, Object ... args) {
2400 return format(l, format, args);
2401 }
2402
2403 /**
2404 * Writes a formatted string to this object's destination using the
2405 * specified locale, format string, and arguments.
2406 *
2407 * @param l
2408 * The {@linkplain java.util.Locale locale} to apply during
2409 * formatting. If {@code l} is {@code null} then no localization
2410 * is applied. This does not change this object's locale that was
2411 * set during construction.
2412 *
2413 * @param format
2414 * A format string as described in <a href="#syntax">Format string
2415 * syntax</a>
2416 *
2417 * @param args
2418 * Arguments referenced by the format specifiers in the format
2419 * string. If there are more arguments than format specifiers, the
2420 * extra arguments are ignored. The maximum number of arguments is
2421 * limited by the maximum dimension of a Java array as defined by
2422 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
2423 * Virtual Machine Specification</a>
2424 *
2425 * @throws IllegalFormatException
2426 * If a format string contains an illegal syntax, a format
2427 * specifier that is incompatible with the given arguments,
2428 * insufficient arguments given the format string, or other
2429 * illegal conditions. For specification of all possible
4179 }
4180 return f;
4181 }
4182
4183 // parse those flags which may be provided by users
4184 private static Flags parse(char c) {
4185 switch (c) {
4186 case '-': return LEFT_JUSTIFY;
4187 case '#': return ALTERNATE;
4188 case '+': return PLUS;
4189 case ' ': return LEADING_SPACE;
4190 case '0': return ZERO_PAD;
4191 case ',': return GROUP;
4192 case '(': return PARENTHESES;
4193 case '<': return PREVIOUS;
4194 default:
4195 throw new UnknownFormatFlagsException(String.valueOf(c));
4196 }
4197 }
4198
4199 // Returns a string representation of the current {@code Flags}.
4200 public static String toString(Flags f) {
4201 return f.toString();
4202 }
4203
4204 public String toString() {
4205 StringBuilder sb = new StringBuilder();
4206 if (contains(LEFT_JUSTIFY)) sb.append('-');
4207 if (contains(UPPERCASE)) sb.append('^');
4208 if (contains(ALTERNATE)) sb.append('#');
4209 if (contains(PLUS)) sb.append('+');
4210 if (contains(LEADING_SPACE)) sb.append(' ');
4211 if (contains(ZERO_PAD)) sb.append('0');
4212 if (contains(GROUP)) sb.append(',');
4213 if (contains(PARENTHESES)) sb.append('(');
4214 if (contains(PREVIOUS)) sb.append('<');
4215 return sb.toString();
4216 }
4217 }
4218
4219 private static class Conversion {
|