Package net.lax1dude.eaglercraft.v1_8

Class HFormatter

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable
    public final class HFormatter
extends java.lang.Object
implements java.io.Closeable, java.io.Flushable

    The Formatter class is a String-formatting utility that is designed to work like the printf function of the C programming language. Its key methods are the format methods which create a formatted String by replacing a set of placeholders (format tokens) with formatted values. The style used to format each value is determined by the format token used. For example, the call
    format("My decimal value is %d and my String is %s.", 3, "Hello");
    returns the String
    My decimal value is 3 and my String is Hello.

    The format token consists of a percent sign, optionally followed by flags and precision arguments, and then a single character that indicates the type of value being formatted. If the type is a time/date, then the type character t is followed by an additional character that indicates how the date is to be formatted. The two characters <$ immediately following the % sign indicate that the previous value should be used again instead of moving on to the next value argument. A number n and a dollar sign immediately following the % sign make n the next argument to be used.

    The available choices are the following:

    Text value types
    s String format("%s, %s", "hello", "Hello"); hello, Hello
    S, s String to capitals format("%S, %S", "hello", "Hello"); HELLO, HELLO
    c Character format("%c, %c", 'd', 0x65); d, e
    C Character to capitals format("%C, %C", 'd', 0x65); D, E
    Text option flags
    The value between the option and the type character indicates the minimum width in characters of the formatted value
    - Left justify (width value is required) format("%-3C, %3C", 'd', 0x65); D , E
    Integer types
    d int, formatted as decimal format("%d, %d"1$, 35, 0x10); 35, 16
    o int, formatted as octal format("%o, %o", 8, 010); 10, 10
    X, x int, formatted as hexidecimal format("%x, %X", 10, 10); a, A
    Integer option flags
    The value between the option and the type character indicates the minimum width in characters of the formatted value
    + lead with the number's sign format("%+d, %+4d", 5, 5); +5, +5
    - Left justify (width value is required) format("%-6dx", 5); 5 x
    # Print the leading characters that indicate hexidecimal or octal (for use only with hex and octal types) format("%#o", 010); 010
    A space indicates that non-negative numbers should have a leading space. format("x% d% 5d", 4, 4); x 4 4
    0 Pad the number with leading zeros (width value is required) format("%07d, %03d", 4, 5555); 0000004, 5555
    ( Put parentheses around negative numbers (decimal only) format("%(d, %(d, %(6d", 12, -12, -12); 12, (12), (12)
    Float types
    A value immediately following the % symbol gives the minimum width in characters of the formatted value; if it is followed by a period and another integer, then the second value gives the precision (6 by default).
    f float (or double) formatted as a decimal, where the precision indicates the number of digits after the decimal. format("%f %<.1f %<1.5f %<10f %<6.0f", 123.456f); 123.456001 123.5 123.45600 123.456001 123
    E, e float (or double) formatted in decimal exponential notation, where the precision indicates the number of significant digits. format("%E %<.1e %<1.5E %<10E %<6.0E", 123.456f); 1.234560E+02 1.2e+02 1.23456E+02 1.234560E+02 1E+02
    G, g float (or double) formatted in decimal exponential notation , where the precision indicates the maximum number of significant digits. format("%G %<.1g %<1.5G %<10G %<6.0G", 123.456f); 123.456 1e+02 123.46 123.456 1E+02
    A, a float (or double) formatted as a hexidecimal in exponential notation, where the precision indicates the number of significant digits. format("%A %<.1a %<1.5A %<10A %<6.0A", 123.456f); 0X1.EDD2F2P6 0x1.fp6 0X1.EDD2FP6 0X1.EDD2F2P6 0X1.FP6
    Float-type option flags
    See the Integer-type options. The options for float-types are the same as for integer types with one addition:
    , Use a comma in place of a decimal if the locale requires it. format(new Locale("fr"), "%,7.2f", 6.03f); 6,03
    Date types
    t, T Date format(new Locale("fr"), "%tB %TB", Calendar.getInstance(), Calendar.getInstance()); avril AVRIL
    Date format precisions
    The format precision character follows the t.
    A, a The day of the week format("%ta %tA", cal, cal); Tue Tuesday
    b, B, h The name of the month format("%tb %<tB %<th", cal, cal, cal); Apr April Apr
    C The century format("%tC\n", cal); 20
    d, e The day of the month (with or without leading zeros) format("%td %te", cal, cal); 01 1
    F The complete date formatted as YYYY-MM-DD format("%tF", cal); 2008-04-01
    D The complete date formatted as MM/DD/YY (not corrected for locale) format(new Locale("en_US"), "%tD", cal);<br/> format(new Locale("en_UK"), " %tD", cal); 04/01/08 04/01/08
    j The number of the day (from the beginning of the year). format("%tj\n", cal); 092
    m The number of the month format("%tm\n", cal); 04
    y, Y The year format("%ty %tY", cal, cal); 08 2008
    H, I, k, l The hour of the day, in 12 or 24 hour format, with or without a leading zero format("%tH %tI %tk %tl", cal, cal, cal, cal); 16 04 16 4
    p a.m. or p.m. format("%tp %Tp", cal, cal); pm PM
    M, S, L, N The minutes, seconds, milliseconds, and nanoseconds format("%tM %tS %tL %tN", cal, cal, cal, cal); 08 17 359 359000000
    Z, z The time zone: its abbreviation or offset from GMT format("%tZ %tz", cal, cal); CEST +0100
    R, r, T The complete time format("%tR %tr %tT", cal, cal, cal); 16:15 04:15:32 PM 16:15:32
    s, Q The number of seconds or milliseconds from "the epoch" (1 January 1970 00:00:00 UTC) format("%ts %tQ", cal, cal); 1207059412 1207059412656
    c The complete time and date format("%tc", cal); Tue Apr 01 16:19:17 CEST 2008
    Other data types
    B, b Boolean format("%b, %B", true, false); true, FALSE
    H, h Hashcode format("%h, %H", obj, obj); 190d11, 190D11
    n line separator format("first%nsecond", "???"); first<br/> second
    Escape sequences
    % Escape the % character format("%d%%, %d", 50, 60); 50%, 60

    An instance of Formatter can be created to write the formatted output to standard types of output streams. Its functionality can also be accessed through the format methods of an output stream or of String:
    System.out.println(HString.format("%ty\n", cal));
    System.out.format("%ty\n", cal);

    The class is not multi-threaded safe. The user is responsible for maintaining a thread-safe design if a Formatter is accessed by multiple threads.

    Since:
    1.5

    • Constructor Summary

      Constructors 
      Constructor Description
      HFormatter()
      Constructs a Formatter.
      HFormatter​(java.io.File file)
      Constructs a Formatter whose output is written to the specified File.
      HFormatter​(java.io.File file, java.lang.String csn)
      Constructs a Formatter with the given charset, and whose output is written to the specified File.
      HFormatter​(java.io.File file, java.lang.String csn, java.util.Locale l)
      Constructs a Formatter with the given Locale and charset, and whose output is written to the specified File.
      HFormatter​(java.io.OutputStream os)
      Constructs a Formatter whose output is written to the specified OutputStream.
      HFormatter​(java.io.OutputStream os, java.lang.String csn)
      Constructs a Formatter with the given charset, and whose output is written to the specified OutputStream.
      HFormatter​(java.io.OutputStream os, java.lang.String csn, java.util.Locale l)
      Constructs a Formatter with the given Locale and charset, and whose output is written to the specified OutputStream.
      HFormatter​(java.io.PrintStream ps)
      Constructs a Formatter whose output is written to the specified PrintStream.
      HFormatter​(java.lang.Appendable a)
      Constructs a Formatter whose output will be written to the specified Appendable.
      HFormatter​(java.lang.Appendable a, java.util.Locale l)
      Constructs a Formatter with the specified Locale and whose output will be written to the specified Appendable.
      HFormatter​(java.lang.String fileName)
      Constructs a Formatter whose output is written to the specified file.
      HFormatter​(java.lang.String fileName, java.lang.String csn)
      Constructs a Formatter whose output is written to the specified file.
      HFormatter​(java.lang.String fileName, java.lang.String csn, java.util.Locale l)
      Constructs a Formatter with the given Locale and charset, and whose output is written to the specified file.
      HFormatter​(java.util.Locale l)
      Constructs a Formatter with the specified Locale.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Closes the Formatter.
      void flush()
      Flushes the Formatter.
      HFormatter format​(java.lang.String format, java.lang.Object... args)
      Writes a formatted string to the output destination of the Formatter.
      HFormatter format​(java.util.Locale l, java.lang.String format, java.lang.Object... args)
      Writes a formatted string to the output destination of the Formatter.
      java.io.IOException ioException()
      Returns the last IOException thrown by the Formatter's output destination.
      java.util.Locale locale()
      Returns the Locale of the Formatter.
      java.lang.Appendable out()
      Returns the output destination of the Formatter.
      java.lang.String toString()
      Returns the content by calling the toString() method of the output destination.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • HFormatter

        public HFormatter()
        Constructs a Formatter. The output is written to a StringBuilder which can be acquired by invoking out() and whose content can be obtained by calling toString(). The Locale for the Formatter is the default Locale.

      • HFormatter

        public HFormatter​(java.lang.Appendable a)
        Constructs a Formatter whose output will be written to the specified Appendable. The locale for the Formatter is the default Locale.
        Parameters:
        a - the output destination of the Formatter. If a is null, then a StringBuilder will be used.

      • HFormatter

        public HFormatter​(java.util.Locale l)
        Constructs a Formatter with the specified Locale. The output is written to a StringBuilder which can be acquired by invoking out() and whose content can be obtained by calling toString().
        Parameters:
        l - the Locale of the Formatter. If l is null, then no localization will be used.

      • HFormatter

        public HFormatter​(java.lang.Appendable a,
                  java.util.Locale l)
        Constructs a Formatter with the specified Locale and whose output will be written to the specified Appendable.
        Parameters:
        a - the output destination of the Formatter. If a is null, then a StringBuilder will be used.
        l - the Locale of the Formatter. If l is null, then no localization will be used.

      • HFormatter

        public HFormatter​(java.lang.String fileName)
           throws java.io.FileNotFoundException
        Constructs a Formatter whose output is written to the specified file. The charset of the Formatter is the default charset. The Locale for the Formatter is the default Locale.
        Parameters:
        fileName - the filename of the file that is used as the output destination for the Formatter. The file will be truncated to zero size if the file exists, or else a new file will be created. The output of the Formatter is buffered.
        Throws:
        java.io.FileNotFoundException - if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file.
        java.lang.SecurityException - if there is a SecurityManager in place which denies permission to write to the file in checkWrite(file.getPath()).

      • HFormatter

        public HFormatter​(java.lang.String fileName,
                  java.lang.String csn)
           throws java.io.FileNotFoundException,
                  java.io.UnsupportedEncodingException
        Constructs a Formatter whose output is written to the specified file. The Locale for the Formatter is the default Locale.
        Parameters:
        fileName - the filename of the file that is used as the output destination for the Formatter. The file will be truncated to zero size if the file exists, or else a new file will be created. The output of the Formatter is buffered.
        csn - the name of the charset for the Formatter.
        Throws:
        java.io.FileNotFoundException - if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file.
        java.lang.SecurityException - if there is a SecurityManager in place which denies permission to write to the file in checkWrite(file.getPath()).
        java.io.UnsupportedEncodingException - if the charset with the specified name is not supported.

      • HFormatter

        public HFormatter​(java.lang.String fileName,
                  java.lang.String csn,
                  java.util.Locale l)
           throws java.io.FileNotFoundException,
                  java.io.UnsupportedEncodingException
        Constructs a Formatter with the given Locale and charset, and whose output is written to the specified file.
        Parameters:
        fileName - the filename of the file that is used as the output destination for the Formatter. The file will be truncated to zero size if the file exists, or else a new file will be created. The output of the Formatter is buffered.
        csn - the name of the charset for the Formatter.
        l - the Locale of the Formatter. If l is null, then no localization will be used.
        Throws:
        java.io.FileNotFoundException - if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file.
        java.lang.SecurityException - if there is a SecurityManager in place which denies permission to write to the file in checkWrite(file.getPath()).
        java.io.UnsupportedEncodingException - if the charset with the specified name is not supported.

      • HFormatter

        public HFormatter​(java.io.File file)
           throws java.io.FileNotFoundException
        Constructs a Formatter whose output is written to the specified File. The charset of the Formatter is the default charset. The Locale for the Formatter is the default Locale.
        Parameters:
        file - the File that is used as the output destination for the Formatter. The File will be truncated to zero size if the File exists, or else a new File will be created. The output of the Formatter is buffered.
        Throws:
        java.io.FileNotFoundException - if the File is not a normal and writable File, or if a new File cannot be created, or if any error rises when opening or creating the File.
        java.lang.SecurityException - if there is a SecurityManager in place which denies permission to write to the File in checkWrite(file.getPath()).

      • HFormatter

        public HFormatter​(java.io.File file,
                  java.lang.String csn)
           throws java.io.FileNotFoundException,
                  java.io.UnsupportedEncodingException
        Constructs a Formatter with the given charset, and whose output is written to the specified File. The Locale for the Formatter is the default Locale.
        Parameters:
        file - the File that is used as the output destination for the Formatter. The File will be truncated to zero size if the File exists, or else a new File will be created. The output of the Formatter is buffered.
        csn - the name of the charset for the Formatter.
        Throws:
        java.io.FileNotFoundException - if the File is not a normal and writable File, or if a new File cannot be created, or if any error rises when opening or creating the File.
        java.lang.SecurityException - if there is a SecurityManager in place which denies permission to write to the File in checkWrite(file.getPath()).
        java.io.UnsupportedEncodingException - if the charset with the specified name is not supported.

      • HFormatter

        public HFormatter​(java.io.File file,
                  java.lang.String csn,
                  java.util.Locale l)
           throws java.io.FileNotFoundException,
                  java.io.UnsupportedEncodingException
        Constructs a Formatter with the given Locale and charset, and whose output is written to the specified File.
        Parameters:
        file - the File that is used as the output destination for the Formatter. The File will be truncated to zero size if the File exists, or else a new File will be created. The output of the Formatter is buffered.
        csn - the name of the charset for the Formatter.
        l - the Locale of the Formatter. If l is null, then no localization will be used.
        Throws:
        java.io.FileNotFoundException - if the File is not a normal and writable File, or if a new File cannot be created, or if any error rises when opening or creating the File.
        java.lang.SecurityException - if there is a SecurityManager in place which denies permission to write to the File in checkWrite(file.getPath()).
        java.io.UnsupportedEncodingException - if the charset with the specified name is not supported.

      • HFormatter

        public HFormatter​(java.io.OutputStream os)
        Constructs a Formatter whose output is written to the specified OutputStream. The charset of the Formatter is the default charset. The Locale for the Formatter is the default Locale.
        Parameters:
        os - the stream to be used as the destination of the Formatter.

      • HFormatter

        public HFormatter​(java.io.OutputStream os,
                  java.lang.String csn)
           throws java.io.UnsupportedEncodingException
        Constructs a Formatter with the given charset, and whose output is written to the specified OutputStream. The Locale for the Formatter is the default Locale.
        Parameters:
        os - the stream to be used as the destination of the Formatter.
        csn - the name of the charset for the Formatter.
        Throws:
        java.io.UnsupportedEncodingException - if the charset with the specified name is not supported.

      • HFormatter

        public HFormatter​(java.io.OutputStream os,
                  java.lang.String csn,
                  java.util.Locale l)
           throws java.io.UnsupportedEncodingException
        Constructs a Formatter with the given Locale and charset, and whose output is written to the specified OutputStream.
        Parameters:
        os - the stream to be used as the destination of the Formatter.
        csn - the name of the charset for the Formatter.
        l - the Locale of the Formatter. If l is null, then no localization will be used.
        Throws:
        java.io.UnsupportedEncodingException - if the charset with the specified name is not supported.

      • HFormatter

        public HFormatter​(java.io.PrintStream ps)
        Constructs a Formatter whose output is written to the specified PrintStream. The charset of the Formatter is the default charset. The Locale for the Formatter is the default Locale.
        Parameters:
        ps - the PrintStream used as destination of the Formatter. If ps is null, then a NullPointerException will be raised.

    • Method Detail

      • locale

        public java.util.Locale locale()
        Returns the Locale of the Formatter.
        Returns:
        the Locale for the Formatter or null for no Locale.
        Throws:
        java.util.FormatterClosedException - if the Formatter has been closed.

      • out

        public java.lang.Appendable out()
        Returns the output destination of the Formatter.
        Returns:
        the output destination of the Formatter.
        Throws:
        java.util.FormatterClosedException - if the Formatter has been closed.

      • toString

        public java.lang.String toString()
        Returns the content by calling the toString() method of the output destination.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the content by calling the toString() method of the output destination.
        Throws:
        java.util.FormatterClosedException - if the Formatter has been closed.

      • flush

        public void flush()
        Flushes the Formatter. If the output destination is Flushable, then the method flush() will be called on that destination.
        Specified by:
        flush in interface java.io.Flushable
        Throws:
        java.util.FormatterClosedException - if the Formatter has been closed.

      • close

        public void close()
        Closes the Formatter. If the output destination is Closeable, then the method close() will be called on that destination. If the Formatter has been closed, then calling the this method will have no effect. Any method but the ioException() that is called after the Formatter has been closed will raise a FormatterClosedException.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable

      • ioException

        public java.io.IOException ioException()
        Returns the last IOException thrown by the Formatter's output destination. If the append() method of the destination does not throw IOExceptions, the ioException() method will always return null.
        Returns:
        the last IOException thrown by the Formatter's output destination.

      • format

        public HFormatter format​(java.lang.String format,
                         java.lang.Object... args)
        Writes a formatted string to the output destination of the Formatter.
        Parameters:
        format - a format string.
        args - the arguments list used in the format() method. If there are more arguments than those specified by the format string, then the additional arguments are ignored.
        Returns:
        this Formatter.
        Throws:
        java.util.IllegalFormatException - if the format string is illegal or incompatible with the arguments, or if fewer arguments are sent than those required by the format string, or any other illegal situation.
        java.util.FormatterClosedException - if the Formatter has been closed.

      • format

        public HFormatter format​(java.util.Locale l,
                         java.lang.String format,
                         java.lang.Object... args)
        Writes a formatted string to the output destination of the Formatter.
        Parameters:
        l - the Locale used in the method. If locale is null, then no localization will be applied. This parameter does not influence the Locale specified during construction.
        format - a format string.
        args - the arguments list used in the format() method. If there are more arguments than those specified by the format string, then the additional arguments are ignored.
        Returns:
        this Formatter.
        Throws:
        java.util.IllegalFormatException - if the format string is illegal or incompatible with the arguments, or if fewer arguments are sent than those required by the format string, or any other illegal situation.
        java.util.FormatterClosedException - if the Formatter has been closed.