1881 * relative indexing.
1882 *
1883 * <blockquote><pre>
1884 * formatter.format("%s %s %s %s", "a", "b", "c", "d")
1885 * // -> "a b c d"
1886 * </pre></blockquote>
1887 *
1888 * </ul>
1889 *
1890 * <p> It is possible to have a format string which uses all forms of indexing,
1891 * for example:
1892 *
1893 * <blockquote><pre>
1894 * formatter.format("%2$s %s %<s %s", "a", "b", "c", "d")
1895 * // -> "b a a b"
1896 * // "c" and "d" are ignored because they are not referenced
1897 * </pre></blockquote>
1898 *
1899 * <p> The maximum number of arguments is limited by the maximum dimension of a
1900 * Java array as defined by
1901 * <cite>The Java™ Virtual Machine Specification</cite>.
1902 * If the argument index does not correspond to an
1903 * available argument, then a {@link MissingFormatArgumentException} is thrown.
1904 *
1905 * <p> If there are more arguments than format specifiers, the extra arguments
1906 * are ignored.
1907 *
1908 * <p> Unless otherwise specified, passing a {@code null} argument to any
1909 * method or constructor in this class will cause a {@link
1910 * NullPointerException} to be thrown.
1911 *
1912 * @author Iris Clark
1913 * @since 1.5
1914 */
1915 public final class Formatter implements Closeable, Flushable {
1916 private Appendable a;
1917 private final Locale l;
1918
1919 private IOException lastException;
1920
1921 private final char zero;
2572 * no such exception exists.
2573 */
2574 public IOException ioException() {
2575 return lastException;
2576 }
2577
2578 /**
2579 * Writes a formatted string to this object's destination using the
2580 * specified format string and arguments. The locale used is the one
2581 * defined during the construction of this formatter.
2582 *
2583 * @param format
2584 * A format string as described in <a href="#syntax">Format string
2585 * syntax</a>.
2586 *
2587 * @param args
2588 * Arguments referenced by the format specifiers in the format
2589 * string. If there are more arguments than format specifiers, the
2590 * extra arguments are ignored. The maximum number of arguments is
2591 * limited by the maximum dimension of a Java array as defined by
2592 * <cite>The Java™ Virtual Machine Specification</cite>.
2593 *
2594 * @throws IllegalFormatException
2595 * If a format string contains an illegal syntax, a format
2596 * specifier that is incompatible with the given arguments,
2597 * insufficient arguments given the format string, or other
2598 * illegal conditions. For specification of all possible
2599 * formatting errors, see the <a href="#detail">Details</a>
2600 * section of the formatter class specification.
2601 *
2602 * @throws FormatterClosedException
2603 * If this formatter has been closed by invoking its {@link
2604 * #close()} method
2605 *
2606 * @return This formatter
2607 */
2608 public Formatter format(String format, Object ... args) {
2609 return format(l, format, args);
2610 }
2611
2612 /**
2613 * Writes a formatted string to this object's destination using the
2614 * specified locale, format string, and arguments.
2615 *
2616 * @param l
2617 * The {@linkplain java.util.Locale locale} to apply during
2618 * formatting. If {@code l} is {@code null} then no localization
2619 * is applied. This does not change this object's locale that was
2620 * set during construction.
2621 *
2622 * @param format
2623 * A format string as described in <a href="#syntax">Format string
2624 * syntax</a>
2625 *
2626 * @param args
2627 * Arguments referenced by the format specifiers in the format
2628 * string. If there are more arguments than format specifiers, the
2629 * extra arguments are ignored. The maximum number of arguments is
2630 * limited by the maximum dimension of a Java array as defined by
2631 * <cite>The Java™ Virtual Machine Specification</cite>.
2632 *
2633 * @throws IllegalFormatException
2634 * If a format string contains an illegal syntax, a format
2635 * specifier that is incompatible with the given arguments,
2636 * insufficient arguments given the format string, or other
2637 * illegal conditions. For specification of all possible
2638 * formatting errors, see the <a href="#detail">Details</a>
2639 * section of the formatter class specification.
2640 *
2641 * @throws FormatterClosedException
2642 * If this formatter has been closed by invoking its {@link
2643 * #close()} method
2644 *
2645 * @return This formatter
2646 */
2647 public Formatter format(Locale l, String format, Object ... args) {
2648 ensureOpen();
2649
2650 // index of last argument referenced
2651 int last = -1;
|
1881 * relative indexing.
1882 *
1883 * <blockquote><pre>
1884 * formatter.format("%s %s %s %s", "a", "b", "c", "d")
1885 * // -> "a b c d"
1886 * </pre></blockquote>
1887 *
1888 * </ul>
1889 *
1890 * <p> It is possible to have a format string which uses all forms of indexing,
1891 * for example:
1892 *
1893 * <blockquote><pre>
1894 * formatter.format("%2$s %s %<s %s", "a", "b", "c", "d")
1895 * // -> "b a a b"
1896 * // "c" and "d" are ignored because they are not referenced
1897 * </pre></blockquote>
1898 *
1899 * <p> The maximum number of arguments is limited by the maximum dimension of a
1900 * Java array as defined by
1901 * <cite>The Java Virtual Machine Specification</cite>.
1902 * If the argument index does not correspond to an
1903 * available argument, then a {@link MissingFormatArgumentException} is thrown.
1904 *
1905 * <p> If there are more arguments than format specifiers, the extra arguments
1906 * are ignored.
1907 *
1908 * <p> Unless otherwise specified, passing a {@code null} argument to any
1909 * method or constructor in this class will cause a {@link
1910 * NullPointerException} to be thrown.
1911 *
1912 * @author Iris Clark
1913 * @since 1.5
1914 */
1915 public final class Formatter implements Closeable, Flushable {
1916 private Appendable a;
1917 private final Locale l;
1918
1919 private IOException lastException;
1920
1921 private final char zero;
2572 * no such exception exists.
2573 */
2574 public IOException ioException() {
2575 return lastException;
2576 }
2577
2578 /**
2579 * Writes a formatted string to this object's destination using the
2580 * specified format string and arguments. The locale used is the one
2581 * defined during the construction of this formatter.
2582 *
2583 * @param format
2584 * A format string as described in <a href="#syntax">Format string
2585 * syntax</a>.
2586 *
2587 * @param args
2588 * Arguments referenced by the format specifiers in the format
2589 * string. If there are more arguments than format specifiers, the
2590 * extra arguments are ignored. The maximum number of arguments is
2591 * limited by the maximum dimension of a Java array as defined by
2592 * <cite>The Java Virtual Machine Specification</cite>.
2593 *
2594 * @throws IllegalFormatException
2595 * If a format string contains an illegal syntax, a format
2596 * specifier that is incompatible with the given arguments,
2597 * insufficient arguments given the format string, or other
2598 * illegal conditions. For specification of all possible
2599 * formatting errors, see the <a href="#detail">Details</a>
2600 * section of the formatter class specification.
2601 *
2602 * @throws FormatterClosedException
2603 * If this formatter has been closed by invoking its {@link
2604 * #close()} method
2605 *
2606 * @return This formatter
2607 */
2608 public Formatter format(String format, Object ... args) {
2609 return format(l, format, args);
2610 }
2611
2612 /**
2613 * Writes a formatted string to this object's destination using the
2614 * specified locale, format string, and arguments.
2615 *
2616 * @param l
2617 * The {@linkplain java.util.Locale locale} to apply during
2618 * formatting. If {@code l} is {@code null} then no localization
2619 * is applied. This does not change this object's locale that was
2620 * set during construction.
2621 *
2622 * @param format
2623 * A format string as described in <a href="#syntax">Format string
2624 * syntax</a>
2625 *
2626 * @param args
2627 * Arguments referenced by the format specifiers in the format
2628 * string. If there are more arguments than format specifiers, the
2629 * extra arguments are ignored. The maximum number of arguments is
2630 * limited by the maximum dimension of a Java array as defined by
2631 * <cite>The Java Virtual Machine Specification</cite>.
2632 *
2633 * @throws IllegalFormatException
2634 * If a format string contains an illegal syntax, a format
2635 * specifier that is incompatible with the given arguments,
2636 * insufficient arguments given the format string, or other
2637 * illegal conditions. For specification of all possible
2638 * formatting errors, see the <a href="#detail">Details</a>
2639 * section of the formatter class specification.
2640 *
2641 * @throws FormatterClosedException
2642 * If this formatter has been closed by invoking its {@link
2643 * #close()} method
2644 *
2645 * @return This formatter
2646 */
2647 public Formatter format(Locale l, String format, Object ... args) {
2648 ensureOpen();
2649
2650 // index of last argument referenced
2651 int last = -1;
|