[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[commit-cp] classpath ChangeLog java/util/Formattable.java ... [generics
|
From: |
Andrew John Hughes |
|
Subject: |
[commit-cp] classpath ChangeLog java/util/Formattable.java ... [generics] |
|
Date: |
Sun, 04 Jun 2006 22:39:00 +0000 |
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 <address@hidden>
* 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 <address@hidden>
+
+ * java/util/Formattable.java,
+ * java/util/FormattableFlags.java,
+ * java/util/Formatter.java:
+ Documented.
+
2006-06-04 Tom Tromey <address@hidden>
* 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 address@hidden Formatter}. The
+ * address@hidden #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,
+ * address@hidden Formattable} objects are not guaranteed to be thread-safe,
+ * and users should make their own provisions for multiple thread access.
+ * </p>
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @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 address@hidden Formatter#out()} and
+ * address@hidden Formatter#locale()} respectively.
+ * @param flags a bit mask constructed from the flags in the
+ * address@hidden 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 address@hidden Formattable#formatTo()} method.
+ * They are used to modify the output of the
+ * address@hidden Formattable}. The interpretation and
+ * validation of the flags is left to the
+ * particular address@hidden Formattable}.
+ *
+ * @author Tom Tromey (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @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
+ * address@hidden 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 address@hidden 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 address@hidden 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 (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @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 address@hidden BigDecimal}.
+ */
public enum BigDecimalLayoutForm
{
DECIMAL_FLOAT,
SCIENTIFIC
}
+ /**
+ * Constructs a new <code>Formatter</code> using the default
+ * locale and a address@hidden 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 address@hidden 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 address@hidden Closeable}
+ * interface, then this is also closed. Attempts to use
+ * a formatter instance, via any method other than
+ * address@hidden #ioException()}, after closure results in a
+ * address@hidden 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
+ * address@hidden 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 address@hidden Object#toString()}
+ * to the underlying output stream. The results returned
+ * depend on the particular address@hidden Appendable} being used.
+ * For example, a address@hidden 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)
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [commit-cp] classpath ChangeLog java/util/Formattable.java ... [generics],
Andrew John Hughes <=