Class SciFormatter

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

public final class SciFormatter extends Object implements Closeable, Flushable
An interpreter for printf-style format strings that can use standard scientific notation for real numbers. This class is nearly identical to the class java.util.Formatter. The main difference is that the 'e', 'E', 'g', and 'G' conversions will accept the '#' flag indicating an alternative representation that replaces 'e' or 'E' with a multiplication sign, followed by 10, followed by the exponent displayed using superscripts. For the exponent, a leading '+' and leading '0' characters are not shown.

When the format is 'E' (as opposed to 'e') and the "#' flag is used, the number before the multiplication sign and the multiplication sign are dropped when when the value is 10 raised to an integer exponent. There are a few exceptions: the number -10, 1, 0, and 10 are shown as integers. The rationale is that some journals have standards for graphs where the multiplication sign is not allowed for such numbers when they are used for labeling an axis on a graph.

For example,

format("%3.3g %#3.3g" 20000.0, 20000.0)
will produce the output
2.000e+04 2.000×104

The class Formatter (as tested using Java 1.7) behaves erratically when only some of the conversions specify an argument position. Thus

formatter = new Formatter(); formatter.format("1 2 3 = %3$d %2$d %1$d", 3, 2, 1); System.out.println(formatter.toString()); formatter = new Formatter(); formatter.format("1 2 3 = %3$d %d %1$d", 3, 2, 1); System.out.println(formatter.toString());
will produce
1 2 3 = 1 2 3 1 2 3 = 1 3 3
even though the %d argument is the second conversion. SciFormatter handles both cases identically:
SciFormatter formatter = new SciFormatter(); formatter.format("1 2 3 = %3$d %2$d %1$d", 3, 2, 1); System.out.println(formatter.toString()); formatter = new SciFormatter(); formatter.format("1 2 3 = %3$d %d %1$d", 3, 2, 1); System.out.println(formatter.toString());
will produce
1 2 3 = 1 2 3 1 2 3 = 1 2 3

The class SciFormatter does not extend Formatter because Formatter is a final class. Aside from the use of '#' in the 'g', 'G', 'e', and 'E' conversions, the format string is identical to that used by Formatter and the constructors and methods of SciFormatter have the same signatures as those for 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.

For the 'e', 'E', 'g', and 'G' formats with the '#' flag, the Unicode characters used in addition to the ones in the ASCII character set are the following:

  • '⁰' - 0 as a superscript.
  • '¹' - 1 as a superscript.
  • '²' - 2 as a superscript.
  • '³' - 3 as a superscript.
  • '⁴' - 4 as a superscript.
  • '⁵' - 5 as a superscript.
  • '⁶' - 6 as a superscript.
  • '⁷' - 7 as a superscript.
  • '⁸' - 8 as a superscript.
  • '⁹' - 9 as a superscript.
  • '⁻' - a minus sign as a superscript
  • '×' - a multiplication sign

Note: for Java 7, Formatter has a bug that prevents formats such as "%3.1g" or "%3.1e" from working when formatting the number 0.0 - an exception is thrown. This bug seems to have been fixed in Java 8. SciFormatter has a work around that handles this specific case for Java 7. If System.getProperties("java.version") does not return a string starting with "1.7", the work around will not be used.

See Also:
  • Constructor Details

    • SciFormatter

      public SciFormatter()
      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.

    • SciFormatter

      public SciFormatter(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.
    • SciFormatter

      public SciFormatter(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.
    • SciFormatter

      public SciFormatter(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
    • SciFormatter

      public SciFormatter(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
    • SciFormatter

      public SciFormatter(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
    • SciFormatter

      public SciFormatter(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.
    • SciFormatter

      public SciFormatter(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.
    • SciFormatter

      public SciFormatter(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
    • SciFormatter

      public SciFormatter(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
    • SciFormatter

      public SciFormatter(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.
    • SciFormatter

      public SciFormatter(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
    • SciFormatter

      public SciFormatter(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
    • SciFormatter

      public SciFormatter(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

      public SciFormatter format(Locale l, String format, Object... args) throws IllegalFormatException, FormatterClosedException
      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

      public SciFormatter format(String format, Object... args) throws IllegalFormatException, FormatterClosedException
      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

      public SciFormatter format(String format, Object arg1, Object arg2) throws IllegalFormatException, FormatterClosedException
      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 SciFormatter 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 SciFormatter 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 SciFormatter 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 SciFormatter 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 SciFormatter 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 SciFormatter 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 SciFormatter 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 SciFormatter 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 SciFormatter 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:
      l - the locale
      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

      public SciFormatter format(Locale l, String format, Object arg1, Object arg2) throws IllegalFormatException, FormatterClosedException
      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
      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 SciFormatter 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
      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 SciFormatter 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
      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 SciFormatter 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
      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 SciFormatter 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
      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 SciFormatter 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
      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 SciFormatter 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
      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 SciFormatter 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
      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 SciFormatter 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
      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 SciFormatter 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
      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