CVSROOT: /cvsroot/classpath Module name: classpath Branch: generics Changes by: Andrew John Hughes <gnu_andrew> 06/06/04 22:38:58
Modified files: . : ChangeLog java/util : Formattable.java FormattableFlags.java Formatter.java Log message: 2006-06-04 Andrew John Hughes <[EMAIL PROTECTED]> * java/util/Formattable.java, * java/util/FormattableFlags.java, * java/util/Formatter.java: Documented. CVSWeb URLs: http://cvs.savannah.gnu.org/viewcvs/classpath/ChangeLog?cvsroot=classpath&only_with_tag=generics&r1=1.2386.2.264&r2=1.2386.2.265 http://cvs.savannah.gnu.org/viewcvs/classpath/java/util/Formattable.java?cvsroot=classpath&only_with_tag=generics&r1=1.1.2.1&r2=1.1.2.2 http://cvs.savannah.gnu.org/viewcvs/classpath/java/util/FormattableFlags.java?cvsroot=classpath&only_with_tag=generics&r1=1.1.2.2&r2=1.1.2.3 http://cvs.savannah.gnu.org/viewcvs/classpath/java/util/Formatter.java?cvsroot=classpath&only_with_tag=generics&r1=1.1.2.4&r2=1.1.2.5 Patches: Index: ChangeLog =================================================================== RCS file: /cvsroot/classpath/classpath/ChangeLog,v retrieving revision 1.2386.2.264 retrieving revision 1.2386.2.265 diff -u -b -r1.2386.2.264 -r1.2386.2.265 --- ChangeLog 4 Jun 2006 21:26:33 -0000 1.2386.2.264 +++ ChangeLog 4 Jun 2006 22:38:56 -0000 1.2386.2.265 @@ -1,3 +1,10 @@ +2006-06-04 Andrew John Hughes <[EMAIL PROTECTED]> + + * java/util/Formattable.java, + * java/util/FormattableFlags.java, + * java/util/Formatter.java: + Documented. + 2006-06-04 Tom Tromey <[EMAIL PROTECTED]> * javax/naming/Context.java (list): Genericized. Index: java/util/Formattable.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/Attic/Formattable.java,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -b -r1.1.2.1 -r1.1.2.2 --- java/util/Formattable.java 25 Sep 2005 02:55:13 -0000 1.1.2.1 +++ java/util/Formattable.java 4 Jun 2006 22:38:58 -0000 1.1.2.2 @@ -38,9 +38,55 @@ package java.util; -/** @since 1.5 */ +/** + * <p> + * The <code>Formattable</code> interface is used to provide customised + * formatting to arbitrary objects via the [EMAIL PROTECTED] Formatter}. The + * [EMAIL PROTECTED] #formatTo} method is called for <code>Formattable</code> + * objects used with the 's' conversion operator, allowing the object + * to provide its own formatting of its internal data. + * </p> + * <p> + * Thread safety is left up to the implementing class. Thus, + * [EMAIL PROTECTED] Formattable} objects are not guaranteed to be thread-safe, + * and users should make their own provisions for multiple thread access. + * </p> + * + * @author Tom Tromey ([EMAIL PROTECTED]) + * @author Andrew John Hughes ([EMAIL PROTECTED]) + * @since 1.5 + */ public interface Formattable { + + /** + * Formats the object using the supplied formatter to the specification + * provided by the given flags, width and precision. + * + * @param formatter the formatter to use for formatting the object. + * The formatter gives access to the output stream + * and locale via [EMAIL PROTECTED] Formatter#out()} and + * [EMAIL PROTECTED] Formatter#locale()} respectively. + * @param flags a bit mask constructed from the flags in the + * [EMAIL PROTECTED] FormattableFlags} class. When no flags + * are set, the implementing class should use its + * defaults. + * @param width the minimum number of characters to include. + * A value of -1 indicates no minimum. The remaining + * space is padded with ' ' either on the left + * (the default) or right (if left justification is + * specified by the flags). + * @param precision the maximum number of characters to include. + * A value of -1 indicates no maximum. This value + * is applied prior to the minimum (the width). Thus, + * a value may meet the minimum width initially, but + * not when the width value is applied, due to + * characters being removed by the precision value. + * @throws IllegalFormatException if there is a problem with + * the syntax of the format + * specification or a mismatch + * between it and the arguments. + */ public void formatTo(Formatter formatter, int flags, int width, int precision); } Index: java/util/FormattableFlags.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/Attic/FormattableFlags.java,v retrieving revision 1.1.2.2 retrieving revision 1.1.2.3 diff -u -b -r1.1.2.2 -r1.1.2.3 --- java/util/FormattableFlags.java 25 Sep 2005 02:55:13 -0000 1.1.2.2 +++ java/util/FormattableFlags.java 4 Jun 2006 22:38:58 -0000 1.1.2.3 @@ -38,19 +38,82 @@ package java.util; -/** @since 1.5 */ +/** + * This class contains a set of flags used + * by the [EMAIL PROTECTED] Formattable#formatTo()} method. + * They are used to modify the output of the + * [EMAIL PROTECTED] Formattable}. The interpretation and + * validation of the flags is left to the + * particular [EMAIL PROTECTED] Formattable}. + * + * @author Tom Tromey ([EMAIL PROTECTED]) + * @author Andrew John Hughes ([EMAIL PROTECTED]) + * @since 1.5 + */ public class FormattableFlags { + + /** + * Requires the output to be left-justified. Any spaces + * required to meet the specified width will be added to + * the right of the output. The default output is + * right-justified, where spaces are added to the left. + * The output is as for the format specifier + * '-' ('\u002d'). + */ public static final int LEFT_JUSTIFY = 1; + + /** + * Requires the output to be in uppercase. The output + * should be the same as the result from calling + * [EMAIL PROTECTED] String#toUpperCase(java.util.Locale)} with + * the formatting locale. The output is as for the + * format specifier '^' ('\u005e'). + */ public static final int UPPERCASE = 2; + + /** + * Requires the use of an alternate form, as specified + * in the documentation of [EMAIL PROTECTED] Formattable}. + * The output is as for the format specifier + * '#' ('\u0023'). + */ public static final int ALTERNATE = 4; // Used internally by Formatter. // Changes here must be reflected in the FLAGS string there. + + /** + * Requires the output to always include a '+' sign. + * The output is as for the format specifier '+'. + */ static final int PLUS = 8; + + /** + * Requires the output to include a leading space on + * positive value. The output is as for the format + * specifier ' '. + */ static final int SPACE = 16; + + /** + * Requires the output to be zero-padded. The output + * is as for the format specifier '0'. + */ static final int ZERO = 32; + + /** + * Requires the output to include locale-specific + * grouping operators. The output is as for the + * format specifier ','. + */ static final int COMMA = 64; + + /** + * Requires the output to include negative numbers + * enclosed in parentheses. The output is as for + * the format specifier '('. + */ static final int PAREN = 128; // Not instantiable. Index: java/util/Formatter.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/Attic/Formatter.java,v retrieving revision 1.1.2.4 retrieving revision 1.1.2.5 diff -u -b -r1.1.2.4 -r1.1.2.5 --- java/util/Formatter.java 20 Mar 2006 01:03:50 -0000 1.1.2.4 +++ java/util/Formatter.java 4 Jun 2006 22:38:58 -0000 1.1.2.5 @@ -54,116 +54,334 @@ import gnu.classpath.SystemProperties; -/** @since 1.5 */ +/** + * <p> + * A Java formatter for <code>printf</code>-style format strings, + * as seen in the C programming language. This differs from the + * C interpretation of such strings by performing much stricter + * checking of format specifications and their corresponding + * arguments. While unknown conversions will be ignored in C, + * and invalid conversions will only produce compiler warnings, + * the Java version utilises a full range of run-time exceptions to + * handle these cases. The Java version is also more customisable + * by virtue of the provision of the [EMAIL PROTECTED] Formattable} interface, + * which allows an arbitrary class to be formatted by the formatter. + * </p> + * <p> + * The formatter is accessible by more convienient static methods. + * For example, streams now have appropriate format methods + * (the equivalent of <code>fprintf</code>) as do <code>String</code> + * objects (the equivalent of <code>sprintf</code>). + * </p> + * <p> + * <strong>Note</strong>: the formatter is not thread-safe. For + * multi-threaded access, external synchronization should be provided. + * </p> + * + * @author Tom Tromey ([EMAIL PROTECTED]) + * @author Andrew John Hughes ([EMAIL PROTECTED]) + * @since 1.5 + */ public final class Formatter implements Closeable, Flushable { + + /** + * The output of the formatter. + */ private Appendable out; + + /** + * The locale used by the formatter. + */ private Locale locale; + + /** + * Whether or not the formatter is closed. + */ private boolean closed; + + /** + * The last I/O exception thrown by the output stream. + */ private IOException ioException; // Some state used when actually formatting. + /** + * The format string. + */ private String format; + + /** + * The current index into the string. + */ private int index; + + /** + * The length of the format string. + */ private int length; + + /** + * The formatting locale. + */ private Locale fmtLocale; // Note that we include '-' twice. The flags are ordered to // correspond to the values in FormattableFlags, and there is no // flag (in the sense of this field used when parsing) for // UPPERCASE; the second '-' serves as a placeholder. + /** + * A string used to index into the formattable flags. + */ private static final String FLAGS = "--#+ 0,("; + /** + * The system line separator. + */ private static final String lineSeparator = SystemProperties.getProperty("line.separator"); + /** + * The type of numeric output format for a [EMAIL PROTECTED] BigDecimal}. + */ public enum BigDecimalLayoutForm { DECIMAL_FLOAT, SCIENTIFIC } + /** + * Constructs a new <code>Formatter</code> using the default + * locale and a [EMAIL PROTECTED] StringBuilder} as the output stream. + */ public Formatter() { - this.out = new StringBuilder(); + this(null, Locale.getDefault()); } + /** + * Constructs a new <code>Formatter</code> using the specified + * locale and a [EMAIL PROTECTED] StringBuilder} as the output stream. + * If the locale is <code>null</code>, then no localization + * is applied. + * + * @param loc the locale to use. + */ public Formatter(Locale loc) { - this.out = new StringBuilder(); - this.locale = loc; + this(null, loc); } + /** + * Constructs a new <code>Formatter</code> using the default + * locale and the specified output stream. + * + * @param app the output stream to use. + */ public Formatter(Appendable app) { - this(app, null); + this(app, Locale.getDefault()); } + /** + * Constructs a new <code>Formatter</code> using the specified + * locale and the specified output stream. If the locale is + * <code>null</code>, then no localization is applied. + * + * @param app the output stream to use. + * @param loc the locale to use. + */ public Formatter(Appendable app, Locale loc) { this.out = app == null ? new StringBuilder() : app; this.locale = loc; } - public Formatter(File file) throws FileNotFoundException + /** + * Constructs a new <code>Formatter</code> using the default + * locale and character set, with the specified file as the + * output stream. + * + * @param file the file to use for output. + * @throws FileNotFoundException if the file does not exist + * and can not be created. + * @throws SecurityException if a security manager is present + * and doesn't allow writing to the file. + */ + public Formatter(File file) + throws FileNotFoundException { - this.out = new OutputStreamWriter(new FileOutputStream(file)); + this(new OutputStreamWriter(new FileOutputStream(file))); } + /** + * Constructs a new <code>Formatter</code> using the default + * locale, with the specified file as the output stream + * and the supplied character set. + * + * @param file the file to use for output. + * @param charset the character set to use for output. + * @throws FileNotFoundException if the file does not exist + * and can not be created. + * @throws SecurityException if a security manager is present + * and doesn't allow writing to the file. + * @throws UnsupportedEncodingException if the supplied character + * set is not supported. + */ public Formatter(File file, String charset) throws FileNotFoundException, UnsupportedEncodingException { - this(file, charset, null); + this(file, charset, Locale.getDefault()); } + /** + * Constructs a new <code>Formatter</code> using the specified + * file as the output stream with the supplied character set + * and locale. If the locale is <code>null</code>, then no + * localization is applied. + * + * @param file the file to use for output. + * @param charset the character set to use for output. + * @param loc the locale to use. + * @throws FileNotFoundException if the file does not exist + * and can not be created. + * @throws SecurityException if a security manager is present + * and doesn't allow writing to the file. + * @throws UnsupportedEncodingException if the supplied character + * set is not supported. + */ public Formatter(File file, String charset, Locale loc) throws FileNotFoundException, UnsupportedEncodingException { - this.out = new OutputStreamWriter(new FileOutputStream(file), charset); + this(new OutputStreamWriter(new FileOutputStream(file), charset), + loc); } + /** + * Constructs a new <code>Formatter</code> using the default + * locale and character set, with the specified output stream. + * + * @param out the output stream to use. + */ public Formatter(OutputStream out) { - this.out = new OutputStreamWriter(out); + this(new OutputStreamWriter(out)); } + /** + * Constructs a new <code>Formatter</code> using the default + * locale, with the specified file output stream and the + * supplied character set. + * + * @param out the output stream. + * @param charset the character set to use for output. + * @throws UnsupportedEncodingException if the supplied character + * set is not supported. + */ public Formatter(OutputStream out, String charset) throws UnsupportedEncodingException { - this(out, charset, null); + this(out, charset, Locale.getDefault()); } + /** + * Constructs a new <code>Formatter</code> using the specified + * output stream with the supplied character set and locale. + * If the locale is <code>null</code>, then no localization is + * applied. + * + * @param file the output stream. + * @param charset the character set to use for output. + * @param loc the locale to use. + * @throws UnsupportedEncodingException if the supplied character + * set is not supported. + */ public Formatter(OutputStream out, String charset, Locale loc) throws UnsupportedEncodingException { - this.out = new OutputStreamWriter(out, charset); - this.locale = loc; + this(new OutputStreamWriter(out, charset), loc); } + /** + * Constructs a new <code>Formatter</code> using the default + * locale with the specified output stream. The character + * set used is that of the output stream. + * + * @param out the output stream to use. + */ public Formatter(PrintStream out) { - this.out = out; + this((Appendable) out); } + /** + * Constructs a new <code>Formatter</code> using the default + * locale and character set, with the specified file as the + * output stream. + * + * @param file the file to use for output. + * @throws FileNotFoundException if the file does not exist + * and can not be created. + * @throws SecurityException if a security manager is present + * and doesn't allow writing to the file. + */ public Formatter(String file) throws FileNotFoundException { - this.out = new OutputStreamWriter(new FileOutputStream(file)); + this(new OutputStreamWriter(new FileOutputStream(file))); } + /** + * Constructs a new <code>Formatter</code> using the default + * locale, with the specified file as the output stream + * and the supplied character set. + * + * @param file the file to use for output. + * @param charset the character set to use for output. + * @throws FileNotFoundException if the file does not exist + * and can not be created. + * @throws SecurityException if a security manager is present + * and doesn't allow writing to the file. + * @throws UnsupportedEncodingException if the supplied character + * set is not supported. + */ public Formatter(String file, String charset) throws FileNotFoundException, UnsupportedEncodingException { - this(file, charset, null); + this(file, charset, Locale.getDefault()); } + /** + * Constructs a new <code>Formatter</code> using the specified + * file as the output stream with the supplied character set + * and locale. If the locale is <code>null</code>, then no + * localization is applied. + * + * @param file the file to use for output. + * @param charset the character set to use for output. + * @param loc the locale to use. + * @throws FileNotFoundException if the file does not exist + * and can not be created. + * @throws SecurityException if a security manager is present + * and doesn't allow writing to the file. + * @throws UnsupportedEncodingException if the supplied character + * set is not supported. + */ public Formatter(String file, String charset, Locale loc) throws FileNotFoundException, UnsupportedEncodingException { - this.out = new OutputStreamWriter(new FileOutputStream(file), charset); - this.locale = loc; + this(new OutputStreamWriter(new FileOutputStream(file), charset), + loc); } + /** + * Closes the formatter, so as to release used resources. + * If the underlying output stream supports the [EMAIL PROTECTED] Closeable} + * interface, then this is also closed. Attempts to use + * a formatter instance, via any method other than + * [EMAIL PROTECTED] #ioException()}, after closure results in a + * [EMAIL PROTECTED] FormatterClosedException}. + */ public void close() { if (closed) @@ -181,6 +399,13 @@ closed = true; } + /** + * Flushes the formatter, writing any cached data to the output + * stream. If the underlying output stream supports the + * [EMAIL PROTECTED] Flushable} interface, it is also flushed. + * + * @throws FormatterClosedException if the formatter is closed. + */ public void flush() { if (closed) @@ -199,6 +424,9 @@ /** * Return the name corresponding to a flag. + * + * @param flags the flag to return the name of. + * @return the name of the flag. */ private String getName(int flags) { @@ -210,6 +438,10 @@ /** * Verify the flags passed to a conversion. + * + * @param flags the flags to verify. + * @param allowed the allowed flags mask. + * @param conversion the conversion character. */ private void checkFlags(int flags, int allowed, char conversion) { @@ -220,7 +452,9 @@ } /** - * Throw an exception is a precision was specified. + * Throw an exception if a precision was specified. + * + * @param precision the precision value (-1 indicates not specified). */ private void noPrecision(int precision) { @@ -230,6 +464,11 @@ /** * Apply the numeric localization algorithm to a StringBuilder. + * + * @param builder the builder to apply to. + * @param flags the formatting flags to use. + * @param width the width of the numeric value. + * @param isNegative true if the value is negative. */ private void applyLocalization(StringBuilder builder, int flags, int width, boolean isNegative) @@ -301,6 +540,12 @@ /** * A helper method that handles emitting a String after applying * precision, width, justification, and upper case flags. + * + * @param arg the string to emit. + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @throws IOException if the output stream throws an I/O error. */ private void genericFormat(String arg, int flags, int width, int precision) throws IOException @@ -332,7 +577,16 @@ } } - /** Emit a boolean. */ + /** + * Emit a boolean. + * + * @param arg the boolean to emit. + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @param conversion the conversion character. + * @throws IOException if the output stream throws an I/O error. + */ private void booleanFormat(Object arg, int flags, int width, int precision, char conversion) throws IOException @@ -348,7 +602,16 @@ genericFormat(result, flags, width, precision); } - /** Emit a hash code. */ + /** + * Emit a hash code. + * + * @param arg the hash code to emit. + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @param conversion the conversion character. + * @throws IOException if the output stream throws an I/O error. + */ private void hashCodeFormat(Object arg, int flags, int width, int precision, char conversion) throws IOException @@ -360,7 +623,16 @@ flags, width, precision); } - /** Emit via a String or Formattable conversion. */ + /** + * Emit a String or Formattable conversion. + * + * @param arg the String or Formattable to emit. + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @param conversion the conversion character. + * @throws IOException if the output stream throws an I/O error. + */ private void stringFormat(Object arg, int flags, int width, int precision, char conversion) throws IOException @@ -385,7 +657,16 @@ } } - /** Emit a character value. */ + /** + * Emit a character. + * + * @param arg the character to emit. + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @param conversion the conversion character. + * @throws IOException if the output stream throws an I/O error. + */ private void characterFormat(Object arg, int flags, int width, int precision, char conversion) throws IOException @@ -414,7 +695,14 @@ genericFormat(result, flags, width, precision); } - /** Emit a '%'. */ + /** + * Emit a '%'. + * + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @throws IOException if the output stream throws an I/O error. + */ private void percentFormat(int flags, int width, int precision) throws IOException { @@ -423,7 +711,14 @@ genericFormat("%", flags, width, precision); } - /** Emit a newline. */ + /** + * Emit a newline. + * + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @throws IOException if the output stream throws an I/O error. + */ private void newLineFormat(int flags, int width, int precision) throws IOException { @@ -437,6 +732,14 @@ /** * Helper method to do initial formatting and checking for integral * conversions. + * + * @param arg the formatted argument. + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @param radix the radix of the number. + * @param conversion the conversion character. + * @return the result. */ private StringBuilder basicIntegralConversion(Object arg, int flags, int width, int precision, @@ -501,7 +804,17 @@ return new StringBuilder(result); } - /** Emit a hex or octal value. */ + /** + * Emit a hex or octal value. + * + * @param arg the hexadecimal or octal value. + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @param radix the radix of the number. + * @param conversion the conversion character. + * @throws IOException if the output stream throws an I/O error. + */ private void hexOrOctalConversion(Object arg, int flags, int width, int precision, int radix, char conversion) @@ -573,7 +886,16 @@ out.append(result); } - /** Emit a decimal value. */ + /** + * Emit a decimal value. + * + * @param arg the hexadecimal or octal value. + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @param conversion the conversion character. + * @throws IOException if the output stream throws an I/O error. + */ private void decimalConversion(Object arg, int flags, int width, int precision, char conversion) throws IOException @@ -593,7 +915,14 @@ genericFormat(builder.toString(), flags, width, precision); } - /** Emit a single date or time conversion to a StringBuilder. */ + /** + * Emit a single date or time conversion to a StringBuilder. + * + * @param builder the builder to write to. + * @param cal the calendar to use in the conversion. + * @param conversion the formatting character to specify the type of data. + * @param syms the date formatting symbols. + */ private void singleDateTimeConversion(StringBuilder builder, Calendar cal, char conversion, DateFormatSymbols syms) @@ -777,7 +1106,17 @@ } } - /** Emit a date or time value. */ + /** + * Emit a date or time value. + * + * @param arg the date or time value. + * @param flags the formatting flags to use. + * @param width the width to use. + * @param precision the precision to use. + * @param conversion the conversion character. + * @param subConversion the sub conversion character. + * @throws IOException if the output stream throws an I/O error. + */ private void dateTimeConversion(Object arg, int flags, int width, int precision, char conversion, char subConversion) @@ -824,6 +1163,8 @@ /** * Advance the internal parsing index, and throw an exception * on overrun. + * + * @throws IllegalArgumentException on overrun. */ private void advance() { @@ -838,6 +1179,8 @@ /** * Parse an integer appearing in the format string. Will return -1 * if no integer was found. + * + * @return the parsed integer. */ private int parseInt() { @@ -853,6 +1196,8 @@ * Parse the argument index. Returns -1 if there was no index, 0 if * we should re-use the previous index, and a positive integer to * indicate an absolute index. + * + * @return the parsed argument index. */ private int parseArgumentIndex() { @@ -882,6 +1227,8 @@ * Parse a set of flags and return a bit mask of values from * FormattableFlags. Will throw an exception if a flag is * duplicated. + * + * @return the parsed flags. */ private int parseFlags() { @@ -905,6 +1252,8 @@ /** * Parse the width part of a format string. Returns -1 if no width * was specified. + * + * @return the parsed width. */ private int parseWidth() { @@ -914,6 +1263,8 @@ /** * If the current character is '.', parses the precision part of a * format string. Returns -1 if no precision was specified. + * + * @return the parsed precision. */ private int parsePrecision() { @@ -927,6 +1278,23 @@ return precision; } + /** + * Outputs a formatted string based on the supplied specification, + * <code>fmt</code>, and its arguments using the specified locale. + * The locale of the formatter does not change as a result; the + * specified locale is just used for this particular formatting + * operation. If the locale is <code>null</code>, then no + * localization is applied. + * + * @param loc the locale to use for this format. + * @param fmt the format specification. + * @param args the arguments to apply to the specification. + * @throws IllegalFormatException if there is a problem with + * the syntax of the format + * specification or a mismatch + * between it and the arguments. + * @throws FormatterClosedException if the formatter is closed. + */ public Formatter format(Locale loc, String fmt, Object... args) { if (closed) @@ -1058,16 +1426,41 @@ return this; } + /** + * Outputs a formatted string based on the supplied specification, + * <code>fmt</code>, and its arguments using the formatter's locale. + * + * @param fmt the format specification. + * @param args the arguments to apply to the specification. + * @throws IllegalFormatException if there is a problem with + * the syntax of the format + * specification or a mismatch + * between it and the arguments. + * @throws FormatterClosedException if the formatter is closed. + */ public Formatter format(String format, Object... args) { return format(locale, format, args); } + /** + * Returns the last I/O exception thrown by the + * <code>append()</code> operation of the underlying + * output stream. + * + * @return the last I/O exception. + */ public IOException ioException() { return ioException; } + /** + * Returns the locale used by this formatter. + * + * @return the formatter's locale. + * @throws FormatterClosedException if the formatter is closed. + */ public Locale locale() { if (closed) @@ -1075,6 +1468,12 @@ return locale; } + /** + * Returns the output stream used by this formatter. + * + * @return the formatter's output stream. + * @throws FormatterClosedException if the formatter is closed. + */ public Appendable out() { if (closed) @@ -1082,6 +1481,15 @@ return out; } + /** + * Returns the result of applying [EMAIL PROTECTED] Object#toString()} + * to the underlying output stream. The results returned + * depend on the particular [EMAIL PROTECTED] Appendable} being used. + * For example, a [EMAIL PROTECTED] StringBuilder} will return the + * formatted output but an I/O stream will not. + * + * @throws FormatterClosedException if the formatter is closed. + */ public String toString() { if (closed)