Class VarArgsFormatter

java.lang.Object
org.bzdev.util.VarArgsFormatter
All Implemented Interfaces:
Closeable, Flushable, AutoCloseable

public final class VarArgsFormatter extends Object implements Closeable, Flushable
An interpreter for printf-style format strings with support for use by scripting languages that do not support variable numbers of arguments.

The behavior class is identical to the class java.util.Formatter.

The method and constructor documentation has been copied verbatim from the Open JDK 1.7 documentation as we cannot use inheritance to find it. A series of methods named format have been added to explicitly handle up to 11 arguments. These methods are provided for use with scripting languages that do not recognize Java methods that use a variable number of arguments.

Note: The Nashorn ECMAScript implementation does not need to use this class as it handles format methods properly - the way Java does. Furthermore, ECMAScript numbers are turned into the appropriate Java types. By contrast Rhino (at least, the version used when this class was tested), does not understand methods with a variable number of arguments. VarArgsFormatter will work with it, but when the format string expects an integer, a Double will not be converted to an integer type unless rounding it produces the same value.

Also note that one may have to explicitly flush the output stream.

See Also:
  • Constructor Details

    • VarArgsFormatter

      public VarArgsFormatter()
      Constructs a new formatter.

      The destination of the formatted output is a StringBuilder which may be retrieved by invoking out() and whose current content may be converted into a string by invoking toString(). The locale used is the default locale for this instance of the Java virtual machine.

    • VarArgsFormatter

      public VarArgsFormatter(Appendable a)
      Constructs a new formatter with the specified destination.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      a - Destination for the formatted output. If a is null then a StringBuilder will be created.
    • VarArgsFormatter

      public VarArgsFormatter(Appendable a, Locale l)
      Constructs a new formatter with the specified destination and locale.
      Parameters:
      a - Destination for the formatted output. If a is null then a StringBuilder will be created.
      l - the locale to apply during formatting. If l is null then no localization is applied.
    • VarArgsFormatter

      public VarArgsFormatter(File file) throws FileNotFoundException
      Constructs a new formatter with the specified file.

      The charset used is the default charset for this instance of the Java virtual machine.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      file - The file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      Throws:
      FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
    • VarArgsFormatter

      public VarArgsFormatter(File file, String csn) throws FileNotFoundException, UnsupportedEncodingException
      Constructs a new formatter with the specified file and charset.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      file - The file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      csn - The name of a supported charset
      Throws:
      FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
      UnsupportedEncodingException - If the named charset is not supported
    • VarArgsFormatter

      public VarArgsFormatter(File file, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException
      Constructs a new formatter with the specified file, charset, and locale.
      Parameters:
      file - The file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      csn - The name of a supported charset
      l - The locale to apply during formatting. If l is null then no localization is applied.
      Throws:
      FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
      UnsupportedEncodingException - If the named charset is not supported
    • VarArgsFormatter

      public VarArgsFormatter(Locale l)
      Constructs a new formatter with the specified locale.

      The destination of the formatted output is a StringBuilder which may be retrieved by invoking out() and whose current content may be converted into a string by invoking toString().

      Parameters:
      l - The locale to apply during formatting. If l is null then no localization is applied.
    • VarArgsFormatter

      public VarArgsFormatter(OutputStream os)
      Constructs a new formatter with the specified output stream.

      The charset used is the default charset for this instance of the Java virtual machine.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      os - The output stream to use as the destination of this formatter. The output will be buffered.
    • VarArgsFormatter

      public VarArgsFormatter(OutputStream os, String csn) throws UnsupportedEncodingException
      Constructs a new formatter with the specified output stream and charset.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      os - The output stream to use as the destination of this formatter. The output will be buffered.
      csn - The name of a supported charset
      Throws:
      UnsupportedEncodingException - If the named charset is not supported
    • VarArgsFormatter

      public VarArgsFormatter(OutputStream os, String csn, Locale l) throws UnsupportedEncodingException
      Constructs a new formatter with the specified output stream, charset, and locale.
      Parameters:
      os - The output stream to use as the destination of this formatter. The output will be buffered.
      csn - The name of a supported charset
      l - The locale to apply during formatting. If l is null then no localization is applied.
      Throws:
      UnsupportedEncodingException - If the named charset is not supported
    • VarArgsFormatter

      public VarArgsFormatter(PrintStream ps)
      Constructs a new formatter with the specified print stream.

      The locale used is the default locale for this instance of the Java virtual machine.

      Characters are written to the given PrintStream object and are therefore encoded using that object's charset.

      Parameters:
      ps - The stream to use as the destination of this formatter.
    • VarArgsFormatter

      public VarArgsFormatter(String fileName) throws FileNotFoundException
      Constructs a new formatter with the specified file name.

      The charset used is the default charset for this instance of the Java virtual machine.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      fileName - The name of the file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      Throws:
      FileNotFoundException - If the given file name does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
    • VarArgsFormatter

      public VarArgsFormatter(String fileName, String csn) throws FileNotFoundException, UnsupportedEncodingException
      Constructs a new formatter with the specified file name and charset.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      fileName - The name of the file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      csn - The name of a supported charset
      Throws:
      FileNotFoundException - If the given file name does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
      UnsupportedEncodingException - If the named charset is not supported
    • VarArgsFormatter

      public VarArgsFormatter(String fileName, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException
      Constructs a new formatter with the specified file name, charset, and locale.
      Parameters:
      fileName - The name of the file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      csn - The name of a supported charset
      l - The locale to apply during formatting. If l is null then no localization is applied.
      Throws:
      FileNotFoundException - If the given file name does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
      UnsupportedEncodingException - If the named charset is not supported
  • Method Details

    • setStrictMode

      public void setStrictMode(boolean value)
      Set strict mode. When strict mode is turned on (it is off by default), an error will occur when a format directive expects an integer but the value's type is Double. When strict mode is turned off, an error will occur when a format directive expects an integer and is given a Double whose value is not one that one expects for an integer.
      Parameters:
      value - true if strict mode is to be turned on; false to turn it off.
    • getStrictMode

      public boolean getStrictMode()
      Get strict mode. When strict mode is turned on (it is off by default), an error will occur when a format directive expects an integer but the value's type is Double. When strict mode is turned off, an error will occur when a format directive expects an integer and is given a Double whose value is not one that one expects for an integer.
      Returns:
      true if strict mode is on; false if it is off.
    • close

      public void close()
      Closes this formatter. If the destination implements the Closeable interface, its close method will be invoked.

      Closing a formatter allows it to release resources it may be holding (such as open files). If the formatter is already closed, then invoking this method has no effect.

      Attempting to invoke any methods except ioException() in this formatter after it has been closed will result in a FormatterClosedException.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
    • flush

      public void flush()
      Flushes this formatter. If the destination implements the Flushable interface, its flush method will be invoked.

      Flushing a formatter writes any buffered output in the destination to the underlying stream.

      Specified by:
      flush in interface Flushable
      Throws:
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • locale

      public Locale locale()
      Returns the locale set by the construction of this formatter.

      The format method for this object which has a locale argument does not change this value.

      Returns:
      null if no localization is applied, otherwise a locale
      Throws:
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      Writes a formatted string to this object's destination using the specified locale, format string, and arguments.
      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied. This does not change this object's locale that was set during construction.
      format - a format string as described in Formatter
      args - arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by The Java™ Virtual Machine Specification.
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      Writes a formatted string to this object's destination using the specified format string and arguments. The locale used is the one defined during the construction of this formatter.
      Parameters:
      format - A format string as described in Formatter
      args - Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by The Java™ Virtual Machine Specification.
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      Writes a formatted string to this object's destination using the specified format string and no arguments. The locale used is the one defined during the construction of this formatter.
      Parameters:
      format - A format string as described in Formatter
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      Writes a formatted string to this object's destination using the specified format string and one argument. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      Writes a formatted string to this object's destination using the specified format string and two arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(String format, Object arg1, Object arg2, Object arg3) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified format string and three arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(String format, Object arg1, Object arg2, Object arg3, Object arg4) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified format string and four arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified format string and five arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified format string and six arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified format string and seven arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7, Object arg8) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified format string and eight arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      arg8 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7, Object arg8, Object arg9) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified format string and nine arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      arg8 - the first argument used by the format string
      arg9 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7, Object arg8, Object arg9, Object arg10) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified format string and ten arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      arg8 - the first argument used by the format string
      arg9 - the first argument used by the format string
      arg10 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7, Object arg8, Object arg9, Object arg10, Object arg11) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified format string and eleven arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      arg8 - the first argument used by the format string
      arg9 - the first argument used by the format string
      arg10 - the first argument used by the format string
      arg11 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      Writes a formatted string to this object's destination using the specified locale and format string with no arguments.
      Parameters:
      l - The locale to apply during formatting. If l is null then no localization is applied. This does not change this object's locale that was set during construction.
      format - A format string as described in Formatter
      Returns:
      this formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      Writes a formatted string to this object's destination using the specified locale, format string and one argument. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      format - A format string as described in Formatter
      l - the locale to apply during formatting. If l is null then no localization is applied.
      arg1 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      Writes a formatted string to this object's destination using the specified locale, format string and two arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - A format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(Locale l, String format, Object arg1, Object arg2, Object arg3) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string and three arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - a format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(Locale l, String format, Object arg1, Object arg2, Object arg3, Object arg4) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string and four arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - a format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(Locale l, String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string and five arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - a format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(Locale l, String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string and six arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - a format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(Locale l, String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string and seven arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - a format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(Locale l, String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7, Object arg8) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string and eight arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - a format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      arg8 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(Locale l, String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7, Object arg8, Object arg9) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string and nine arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - a format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      arg8 - the first argument used by the format string
      arg9 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(Locale l, String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7, Object arg8, Object arg9, Object arg10) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string and ten arguments. The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - a format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      arg8 - the first argument used by the format string
      arg9 - the first argument used by the format string
      arg10 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • format

      public VarArgsFormatter format(Locale l, String format, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5, Object arg6, Object arg7, Object arg8, Object arg9, Object arg10, Object arg11) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string and eleven arguments. * The locale used is the one defined during the construction of this formatter. If there are more arguments than format specifiers, the extra arguments are ignored.

      This method duplicates the behavior of the method format(String,Object...) and is provided because some scripting languages do not recognize Java methods that have a variable number of arguments.

      Parameters:
      l - the locale to apply during formatting. If l is null then no localization is applied.
      format - a format string as described in Formatter
      arg1 - the first argument used by the format string
      arg2 - the first argument used by the format string
      arg3 - the first argument used by the format string
      arg4 - the first argument used by the format string
      arg5 - the first argument used by the format string
      arg6 - the first argument used by the format string
      arg7 - the first argument used by the format string
      arg8 - the first argument used by the format string
      arg9 - the first argument used by the format string
      arg10 - the first argument used by the format string
      arg11 - the first argument used by the format string
      Returns:
      this formatter
      Throws:
      IllegalFormatException - if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - if this formatter has been closed by invoking its close() method
    • ioException

      public IOException ioException()
      Returns the IOException last thrown by this formatter's Appendable.

      If the destination's append() method never throws IOException, then this method will always return null.

      Returns:
      the last exception thrown by the Appendable or null if no such exception exists.
    • out

      public Appendable out()
      Returns the destination for the output.
      Returns:
      The destination for the output
      Throws:
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • toString

      public String toString()
      Returns the result of invoking toString() on the destination for the output. For example, the following code formats text into a StringBuilder (created by Formatter's zero-argument constructor) and then retrieves the resultant string:
         Formatter f = new Formatter();
         f.format("Last reboot at %tc", lastRebootDate);
         String s = f.toString();
         // -> s == "Last reboot at Sat Jan 01 00:00:00 PST 2000"
       

      An invocation of this method behaves in exactly the same way as the invocation

           out().toString() 

      Depending on the specification of toString for the Appendable, the returned string may or may not contain the characters written to the destination. For instance, buffers typically return their contents in toString(), but streams cannot since the data is discarded.

      Overrides:
      toString in class Object
      Returns:
      The result of invoking toString() on the destination for the output
      Throws:
      FormatterClosedException - If this formatter has been closed by invoking its close() method