/* * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.util; import java.io.BufferedWriter;import java.io.Closeable;import java.io.IOException;import java.io.File;import java.io.FileOutputStream;import java.io.FileNotFoundException;import java.io.Flushable;import java.io.OutputStream;import java.io.OutputStreamWriter;import java.io.PrintStream;import java.io.UnsupportedEncodingException;import java.math.BigDecimal;import java.math.BigInteger;import java.math.MathContext;import java.math.RoundingMode;import java.nio.charset.Charset;import java.nio.charset.IllegalCharsetNameException;import java.nio.charset.UnsupportedCharsetException;import java.text.DateFormatSymbols;import java.text.DecimalFormat;import java.text.DecimalFormatSymbols;import java.text.NumberFormat;import java.util.regex.Matcher;import java.util.regex.Pattern; import sun.misc.FpUtils;import sun.misc.DoubleConsts;import sun.misc.FormattedFloatingDecimal; /** * An interpreter for printf-style format strings.  This class provides support * for layout justification and alignment, common formats for numeric, string, * and date/time data, and locale-specific output.  Common Java types such as * {@code byte}, {@link java.math.BigDecimal BigDecimal}, and {@link Calendar} * are supported.  Limited formatting customization for arbitrary user types is * provided through the {@link Formattable} interface. * * <p> Formatters are not necessarily safe for multithreaded access.  Thread * safety is optional and is the responsibility of users of methods in this * class. * * <p> Formatted printing for the Java language is heavily inspired by C's * {@code printf}.  Although the format strings are similar to C, some * customizations have been made to accommodate the Java language and exploit * some of its features.  Also, Java formatting is more strict than C's; for * example, if a conversion is incompatible with a flag, an exception will be * thrown.  In C inapplicable flags are silently ignored.  The format strings * are thus intended to be recognizable to C programmers but not necessarily * completely compatible with those in C. * * <p> Examples of expected usage: * * <blockquote><pre> *   StringBuilder sb = new StringBuilder(); *   // Send all output to the Appendable object sb *   Formatter formatter = new Formatter(sb, Locale.US); * *   // Explicit argument indices may be used to re-order output. *   formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d") *   // -&gt; " d  c  b  a" * *   // Optional locale as the first argument can be used to get *   // locale-specific formatting of numbers.  The precision and width can be *   // given to round and align the value. *   formatter.format(Locale.FRANCE, "e = %+10.4f", Math.E); *   // -&gt; "e =    +2,7183" * *   // The '(' numeric flag may be used to format negative numbers with *   // parentheses rather than a minus sign.  Group separators are *   // automatically inserted. *   formatter.format("Amount gained or lost since last statement: $ %(,.2f", *                    balanceDelta); *   // -&gt; "Amount gained or lost since last statement: $ (6,217.58)" * </pre></blockquote> * * <p> Convenience methods for common formatting requests exist as illustrated * by the following invocations: * * <blockquote><pre> *   // Writes a formatted string to System.out. *   System.out.format("Local time: %tT", Calendar.getInstance()); *   // -&gt; "Local time: 13:34:18" * *   // Writes formatted output to System.err. *   System.err.printf("Unable to open file '%1$s': %2$s", *                     fileName, exception.getMessage()); *   // -&gt; "Unable to open file 'food': No such file or directory" * </pre></blockquote> * * <p> Like C's {@code sprintf(3)}, Strings may be formatted using the static * method {@link String#format(String,Object...) String.format}: * * <blockquote><pre> *   // Format a string containing a date. *   import java.util.Calendar; *   import java.util.GregorianCalendar; *   import static java.util.Calendar.*; * *   Calendar c = new GregorianCalendar(1995, MAY, 23); *   String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c); *   // -&gt; s == "Duke's Birthday: May 23, 1995" * </pre></blockquote> * * <h3><a name="org">Organization</a></h3> * * <p> This specification is divided into two sections.  The first section, <a * href="#summary">Summary</a>, covers the basic formatting concepts.  This * section is intended for users who want to get started quickly and are * familiar with formatted printing in other programming languages.  The second * section, <a href="#detail">Details</a>, covers the specific implementation * details.  It is intended for users who want more precise specification of * formatting behavior. * * <h3><a name="summary">Summary</a></h3> * * <p> This section is intended to provide a brief overview of formatting * concepts.  For precise behavioral details, refer to the <a * href="#detail">Details</a> section. * * <h4><a name="syntax">Format String Syntax</a></h4> * * <p> Every method which produces formatted output requires a <i>format * string</i> and an <i>argument list</i>.  The format string is a {@link * String} which may contain fixed text and one or more embedded <i>format * specifiers</i>.  Consider the following example: * * <blockquote><pre> *   Calendar c = ...; *   String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c); * </pre></blockquote> * * This format string is the first argument to the {@code format} method.  It * contains three format specifiers "{@code %1$tm}", "{@code %1$te}", and * "{@code %1$tY}" which indicate how the arguments should be processed and * where they should be inserted in the text.  The remaining portions of the * format string are fixed text including {@code "Dukes Birthday: "} and any * other spaces or punctuation. * * The argument list consists of all arguments passed to the method after the * format string.  In the above example, the argument list is of size one and * consists of the {@link java.util.Calendar Calendar} object {@code c}. * * <ul> * * <li> The format specifiers for general, character, and numeric types have * the following syntax: * * <blockquote><pre> *   %[argument_index$][flags][width][.precision]conversion * </pre></blockquote> * * <p> The optional <i>argument_index</i> is a decimal integer indicating the * position of the argument in the argument list.  The first argument is * referenced by "{@code 1$}", the second by "{@code 2$}", etc. * * <p> The optional <i>flags</i> is a set of characters that modify the output * format.  The set of valid flags depends on the conversion. * * <p> The optional <i>width</i> is a non-negative decimal integer indicating * the minimum number of characters to be written to the output. * * <p> The optional <i>precision</i> is a non-negative decimal integer usually * used to restrict the number of characters.  The specific behavior depends on * the conversion. * * <p> The required <i>conversion</i> is a character indicating how the * argument should be formatted.  The set of valid conversions for a given * argument depends on the argument's data type. * * <li> The format specifiers for types which are used to represents dates and * times have the following syntax: * * <blockquote><pre> *   %[argument_index$][flags][width]conversion * </pre></blockquote> * * <p> The optional <i>argument_index</i>, <i>flags</i> and <i>width</i> are * defined as above. * * <p> The required <i>conversion</i> is a two character sequence.  The first * character is {@code 't'} or {@code 'T'}.  The second character indicates * the format to be used.  These characters are similar to but not completely * identical to those defined by GNU {@code date} and POSIX * {@code strftime(3c)}. * * <li> The format specifiers which do not correspond to arguments have the * following syntax: * * <blockquote><pre> *   %[flags][width]conversion * </pre></blockquote> * * <p> The optional <i>flags</i> and <i>width</i> is defined as above. * * <p> The required <i>conversion</i> is a character indicating content to be * inserted in the output. * * </ul> * * <h4> Conversions </h4> * * <p> Conversions are divided into the following categories: * * <ol> * * <li> <b>General</b> - may be applied to any argument * type * * <li> <b>Character</b> - may be applied to basic types which represent * Unicode characters: {@code char}, {@link Character}, {@code byte}, {@link * Byte}, {@code short}, and {@link Short}. This conversion may also be * applied to the types {@code int} and {@link Integer} when {@link * Character#isValidCodePoint} returns {@code true} * * <li> <b>Numeric</b> * * <ol> * * <li> <b>Integral</b> - may be applied to Java integral types: {@code byte}, * {@link Byte}, {@code short}, {@link Short}, {@code int} and {@link * Integer}, {@code long}, {@link Long}, and {@link java.math.BigInteger * BigInteger} * * <li><b>Floating Point</b> - may be applied to Java floating-point types: * {@code float}, {@link Float}, {@code double}, {@link Double}, and {@link * java.math.BigDecimal BigDecimal} * * </ol> * * <li> <b>Date/Time</b> - may be applied to Java types which are capable of * encoding a date or time: {@code long}, {@link Long}, {@link Calendar}, and * {@link Date}. * * <li> <b>Percent</b> - produces a literal {@code '%'} * (<tt>'&#92;u0025'</tt>) * * <li> <b>Line Separator</b> - produces the platform-specific line separator * * </ol> * * <p> The following table summarizes the supported conversions.  Conversions * denoted by an upper-case character (i.e. {@code 'B'}, {@code 'H'}, * {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'}, {@code 'G'}, * {@code 'A'}, and {@code 'T'}) are the same as those for the corresponding * lower-case conversion characters except that the result is converted to * upper case according to the rules of the prevailing {@link java.util.Locale * Locale}.  The result is equivalent to the following invocation of {@link * String#toUpperCase()} * * <pre> *    out.toUpperCase() </pre> * * <table cellpadding=5 summary="genConv"> * * <tr><th valign="bottom"> Conversion *     <th valign="bottom"> Argument Category *     <th valign="bottom"> Description * * <tr><td valign="top"> {@code 'b'}, {@code 'B'} *     <td valign="top"> general *     <td> If the argument <i>arg</i> is {@code null}, then the result is *     "{@code false}".  If <i>arg</i> is a {@code boolean} or {@link *     Boolean}, then the result is the string returned by {@link *     String#valueOf(boolean) String.valueOf(arg)}.  Otherwise, the result is *     "true". * * <tr><td valign="top"> {@code 'h'}, {@code 'H'} *     <td valign="top"> general *     <td> If the argument <i>arg</i> is {@code null}, then the result is *     "{@code null}".  Otherwise, the result is obtained by invoking *     {@code Integer.toHexString(arg.hashCode())}. * * <tr><td valign="top"> {@code 's'}, {@code 'S'} *     <td valign="top"> general *     <td> If the argument <i>arg</i> is {@code null}, then the result is *     "{@code null}".  If <i>arg</i> implements {@link Formattable}, then *     {@link Formattable#formatTo arg.formatTo} is invoked. Otherwise, the *     result is obtained by invoking {@code arg.toString()}. * * <tr><td valign="top">{@code 'c'}, {@code 'C'} *     <td valign="top"> character *     <td> The result is a Unicode character * * <tr><td valign="top">{@code 'd'} *     <td valign="top"> integral *     <td> The result is formatted as a decimal integer * * <tr><td valign="top">{@code 'o'} *     <td valign="top"> integral *     <td> The result is formatted as an octal integer * * <tr><td valign="top">{@code 'x'}, {@code 'X'} *     <td valign="top"> integral *     <td> The result is formatted as a hexadecimal integer * * <tr><td valign="top">{@code 'e'}, {@code 'E'} *     <td valign="top"> floating point *     <td> The result is formatted as a decimal number in computerized *     scientific notation * * <tr><td valign="top">{@code 'f'} *     <td valign="top"> floating point *     <td> The result is formatted as a decimal number * * <tr><td valign="top">{@code 'g'}, {@code 'G'} *     <td valign="top"> floating point *     <td> The result is formatted using computerized scientific notation or *     decimal format, depending on the precision and the value after rounding. * * <tr><td valign="top">{@code 'a'}, {@code 'A'} *     <td valign="top"> floating point *     <td> The result is formatted as a hexadecimal floating-point number with *     a significand and an exponent * * <tr><td valign="top">{@code 't'}, {@code 'T'} *     <td valign="top"> date/time *     <td> Prefix for date and time conversion characters.  See <a *     href="#dt">Date/Time Conversions</a>. * * <tr><td valign="top">{@code '%'} *     <td valign="top"> percent *     <td> The result is a literal {@code '%'} (<tt>'&#92;u0025'</tt>) * * <tr><td valign="top">{@code 'n'} *     <td valign="top"> line separator *     <td> The result is the platform-specific line separator * * </table> * * <p> Any characters not explicitly defined as conversions are illegal and are * reserved for future extensions. * * <h4><a name="dt">Date/Time Conversions</a></h4> * * <p> The following date and time conversion suffix characters are defined for * the {@code 't'} and {@code 'T'} conversions.  The types are similar to but * not completely identical to those defined by GNU {@code date} and POSIX * {@code strftime(3c)}.  Additional conversion types are provided to access * Java-specific functionality (e.g. {@code 'L'} for milliseconds within the * second). * * <p> The following conversion characters are used for formatting times: * * <table cellpadding=5 summary="time"> * * <tr><td valign="top"> {@code 'H'} *     <td> Hour of the day for the 24-hour clock, formatted as two digits with *     a leading zero as necessary i.e. {@code 00 - 23}. * * <tr><td valign="top">{@code 'I'} *     <td> Hour for the 12-hour clock, formatted as two digits with a leading *     zero as necessary, i.e.  {@code 01 - 12}. * * <tr><td valign="top">{@code 'k'} *     <td> Hour of the day for the 24-hour clock, i.e. {@code 0 - 23}. * * <tr><td valign="top">{@code 'l'} *     <td> Hour for the 12-hour clock, i.e. {@code 1 - 12}. * * <tr><td valign="top">{@code 'M'} *     <td> Minute within the hour formatted as two digits with a leading zero *     as necessary, i.e.  {@code 00 - 59}. * * <tr><td valign="top">{@code 'S'} *     <td> Seconds within the minute, formatted as two digits with a leading *     zero as necessary, i.e. {@code 00 - 60} ("{@code 60}" is a special *     value required to support leap seconds). * * <tr><td valign="top">{@code 'L'} *     <td> Millisecond within the second formatted as three digits with *     leading zeros as necessary, i.e. {@code 000 - 999}. * * <tr><td valign="top">{@code 'N'} *     <td> Nanosecond within the second, formatted as nine digits with leading *     zeros as necessary, i.e. {@code 000000000 - 999999999}. * * <tr><td valign="top">{@code 'p'} *     <td> Locale-specific {@linkplain *     java.text.DateFormatSymbols#getAmPmStrings morning or afternoon} marker *     in lower case, e.g."{@code am}" or "{@code pm}". Use of the conversion *     prefix {@code 'T'} forces this output to upper case. * * <tr><td valign="top">{@code 'z'} *     <td> <a href="http://www.ietf.org/rfc/rfc0822.txt">RFC&nbsp;822</a> *     style numeric time zone offset from GMT, e.g. {@code -0800}.  This *     value will be adjusted as necessary for Daylight Saving Time.  For *     {@code long}, {@link Long}, and {@link Date} the time zone used is *     the {@linkplain TimeZone#getDefault() default time zone} for this *     instance of the Java virtual machine. * * <tr><td valign="top">{@code 'Z'} *     <td> A string representing the abbreviation for the time zone.  This *     value will be adjusted as necessary for Daylight Saving Time.  For *     {@code long}, {@link Long}, and {@link Date} the  time zone used is *     the {@linkplain TimeZone#getDefault() default time zone} for this *     instance of the Java virtual machine.  The Formatter's locale will *     supersede the locale of the argument (if any). * * <tr><td valign="top">{@code 's'} *     <td> Seconds since the beginning of the epoch starting at 1 January 1970 *     {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE/1000} to *     {@code Long.MAX_VALUE/1000}. * * <tr><td valign="top">{@code 'Q'} *     <td> Milliseconds since the beginning of the epoch starting at 1 January *     1970 {@code 00:00:00} UTC, i.e. {@code Long.MIN_VALUE} to *     {@code Long.MAX_VALUE}. * * </table> * * <p> The following conversion characters are used for formatting dates: * * <table cellpadding=5 summary="date"> * * <tr><td valign="top">{@code 'B'} *     <td> Locale-specific {@linkplain java.text.DateFormatSymbols#getMonths *     full month name}, e.g. {@code "January"}, {@code "February"}. * * <tr><td valign="top">{@code 'b'} *     <td> Locale-specific {@linkplain *     java.text.DateFormatSymbols#getShortMonths abbreviated month name}, *     e.g. {@code "Jan"}, {@code "Feb"}. * * <tr><td valign="top">{@code 'h'} *     <td> Same as {@code 'b'}. * * <tr><td valign="top">{@code 'A'} *     <td> Locale-specific full name of the {@linkplain *     java.text.DateFormatSymbols#getWeekdays day of the week}, *     e.g. {@code "Sunday"}, {@code "Monday"} * * <tr><td valign="top">{@code 'a'} *     <td> Locale-specific short name of the {@linkplain *     java.text.DateFormatSymbols#getShortWeekdays day of the week}, *     e.g. {@code "Sun"}, {@code "Mon"} * * <tr><td valign="top">{@code 'C'} *     <td> Four-digit year divided by {@code 100}, formatted as two digits *     with leading zero as necessary, i.e. {@code 00 - 99} * * <tr><td valign="top">{@code 'Y'} *     <td> Year, formatted as at least four digits with leading zeros as *     necessary, e.g. {@code 0092} equals {@code 92} CE for the Gregorian *     calendar. * * <tr><td valign="top">{@code 'y'} *     <td> Last two digits of the year, formatted with leading zeros as *     necessary, i.e. {@code 00 - 99}. * * <tr><td valign="top">{@code 'j'} *     <td> Day of year, formatted as three digits with leading zeros as *     necessary, e.g. {@code 001 - 366} for the Gregorian calendar. * * <tr><td valign="top">{@code 'm'} *     <td> Month, formatted as two digits with leading zeros as necessary, *     i.e. {@code 01 - 13}. * * <tr><td valign="top">{@code 'd'} *     <td> Day of month, formatted as two digits with leading zeros as *     necessary, i.e. {@code 01 - 31} * * <tr><td valign="top">{@code 'e'} *     <td> Day of month, formatted as two digits, i.e. {@code 1 - 31}. * * </table> * * <p> The following conversion characters are used for formatting common * date/time compositions. * * <table cellpadding=5 summary="composites"> * * <tr><td valign="top">{@code 'R'} *     <td> Time formatted for the 24-hour clock as {@code "%tH:%tM"}

Lines 1–500 of 4441. Load more