Package org.apache.sis.io

## Class TableAppender

- Object
- - TableAppender

- All Implemented Interfaces:
    `Flushable`, `Appendable`

      public class TableAppender
      extends Object
      implements Flushable

  An `Appendable` which formats the text as a table suitable for displaying in devices using a monospaced font. Columns are separated by tabulations (`'\t'`) and rows are separated by line or paragraph separators. The content of every table cells are stored in memory until the `flush()` method is invoked. When invoked, `flush()` copies the cell contents to the underlying stream or buffer while replacing tabulations by some amount of spaces and drawing borders. The exact number of spaces is computed from the cell widths.

  For example, the following code:

  >     TableAppender table = new TableAppender(System.out);
  >     table.nextLine('═');
  >     table.append("English\tFrench\tr.e.d.\n");
  >     table.nextLine('-');
  >     table.append("Mercury\tMercure\t0.382\n")
  >          .append("Venus\tVénus\t0.949\n")
  >          .append("Earth\tTerre\t1.00\n")
  >          .append("Mars\tMars\t0.532\n");
  >     table.nextLine('═');
  >     table.flush();

  produces the following output:

  >     ╔═════════╤═════════╤════════╗
  >     ║ English │ French  │ r.e.d. ║
  >     ╟─────────┼─────────┼────────╢
  >     ║ Mercury │ Mercure │ 0.382  ║
  >     ║ Venus   │ Vénus   │ 0.949  ║
  >     ║ Earth   │ Terre   │ 1.00   ║
  >     ║ Mars    │ Mars    │ 0.532  ║
  >     ╚═════════╧═════════╧════════╝

  Since:
    0.3
  See Also:
    `TreeTableFormat`

  Defined in the `sis-utility` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static byte` | `ALIGN_CENTER` | A possible value for cell alignment.
    `static byte` | `ALIGN_LEFT` | A possible value for cell alignment.
    `static byte` | `ALIGN_RIGHT` | A possible value for cell alignment.
    `protected Appendable` | `out` | The underlying character output stream or buffer.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TableAppender()` | Creates a new table formatter writing in an internal buffer with a default column separator.
    `TableAppender​(Appendable out)` | Creates a new table formatter writing in the given output with a default column separator.
    `TableAppender​(Appendable out, String separator)` | Creates a new table formatter writing in the given output with the specified column separator.
    `TableAppender​(Appendable out, String leftBorder, String separator, String rightBorder)` | Creates a new table formatter writing in the given output with the specified column separator and border.
    `TableAppender​(String separator)` | Creates a new table formatter writing in an internal buffer with the specified column separator.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `TableAppender` | `append​(char c)` | Writes a single character.
    `TableAppender` | `append​(CharSequence sequence)` | Appends the specified character sequence.
    `TableAppender` | `append​(CharSequence sequence, int start, int end)` | Writes a portion of a character sequence.
    `void` | `appendHorizontalSeparator()` | Writes an horizontal separator using the `'─'` character.
    `void` | `flush()` | Flushes the table content to the underlying stream or buffer.
    `byte` | `getCellAlignment()` | Returns the alignment of the text inside the current cell.
    `int` | `getColumnCount()` | Returns the number of columns in this table.
    `String` | `getLineSeparator()` | Returns the line separator between table rows.
    `int` | `getRowCount()` | Returns the number of rows in this table.
    `boolean` | `isMultiLinesCells()` | Returns `true` if EOL characters are used for line feeds inside current cells.
    `void` | `nextColumn()` | Moves one column to the right.
    `void` | `nextColumn​(char fill)` | Moves one column to the right, filling remaining space with the given character.
    `void` | `nextLine()` | Moves to the first column on the next row.
    `void` | `nextLine​(char fill)` | Moves to the first column on the next row, filling every remaining cell in the current row with the specified character.
    `void` | `setCellAlignment​(byte alignment)` | Sets the alignment of the text inside the current cell.
    `void` | `setMultiLinesCells​(boolean multiLines)` | Sets the desired behavior for EOL and tabulations characters.
    `String` | `toString()` | Returns the content of this `TableAppender` as a string if possible.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### ALIGN_LEFT

          public static final byte ALIGN_LEFT

      A possible value for cell alignment. This specifies that the text is aligned to the left indent and extra whitespace should be placed on the right.
      See Also:
        Constant Field Values

    - #### ALIGN_CENTER

          public static final byte ALIGN_CENTER

      A possible value for cell alignment. This specifies that the text is aligned to the center and extra whitespace should be placed equally on the left and right.
      See Also:
        Constant Field Values

    - #### ALIGN_RIGHT

          public static final byte ALIGN_RIGHT

      A possible value for cell alignment. This specifies that the text is aligned to the right indent and extra whitespace should be placed on the left.
      See Also:
        Constant Field Values

    - #### out

          protected final Appendable out

      The underlying character output stream or buffer.

  - ### Constructor Detail

    - #### TableAppender

          public TableAppender()

      Creates a new table formatter writing in an internal buffer with a default column separator. The default is a vertical double line for the left and right table borders, and a single line between the columns.

    - #### TableAppender

          public TableAppender​(String separator)

      Creates a new table formatter writing in an internal buffer with the specified column separator.
      Parameters:
        `separator` - string to write between columns.

    - #### TableAppender

          public TableAppender​(Appendable out)

      Creates a new table formatter writing in the given output with a default column separator. The default is a vertical double line for the left and right table borders, and a single line between the columns.
      Parameters:
        `out` - the underlying stream or buffer to write to.

    - #### TableAppender

          public TableAppender​(Appendable out,
                               String separator)

      Creates a new table formatter writing in the given output with the specified column separator.
      Parameters:
        `out` - the underlying stream or buffer to write to.
        `separator` - string to write between columns.

    - #### TableAppender

          public TableAppender​(Appendable out,
                               String leftBorder,
                               String separator,
                               String rightBorder)

      Creates a new table formatter writing in the given output with the specified column separator and border.
      Parameters:
        `out` - the underlying stream or buffer to write to.
        `leftBorder` - string to write on the left side of the table.
        `separator` - string to write between columns.
        `rightBorder` - string to write on the right side of the table.
      Since:
        0.8

  - ### Method Detail

    - #### isMultiLinesCells

          public boolean isMultiLinesCells()

      Returns `true` if EOL characters are used for line feeds inside current cells.
      Returns:
        `true` if EOL characters are to be write inside the cell.

    - #### setMultiLinesCells

          public void setMultiLinesCells​(boolean multiLines)

      Sets the desired behavior for EOL and tabulations characters.
      - If `true`, then tabulations, line and paragraph separator characters are copied into the current cell. Subsequent writing operations will continue inside the same cell.
      - If `false`, then tabulations move to next column and EOL move to the first cell of next row (i.e. tabulation and EOL are equivalent to `nextColumn()` and `nextLine()` calls respectively).
      The default value is `false`.
      Parameters:
        `multiLines` - `true` true if EOL are used for line feeds inside current cells, or `false` if EOL move to the next row.

    - #### getCellAlignment

          public byte getCellAlignment()

      Returns the alignment of the text inside the current cell. The default value is `ALIGN_LEFT`.
      Returns:
        current cell alignment as one of the `ALIGN_LEFT`, `ALIGN_RIGHT` or `ALIGN_CENTER` constants.

    - #### setCellAlignment

          public void setCellAlignment​(byte alignment)

      Sets the alignment of the text inside the current cell. The alignments of any cell written prior this method call are left unchanged. The new alignment will apply to the next cells too until this `setCellAlignment(…)` method is invoked again with a different value.

      If this method is never invoked, then the default alignment is `ALIGN_LEFT`.

      Parameters:
        `alignment` - the new cell alignment as one of the `ALIGN_LEFT`, `ALIGN_RIGHT` or `ALIGN_CENTER` constants.

    - #### getLineSeparator

          public String getLineSeparator()

      Returns the line separator between table rows. This is the first line separator found in the text formatted as a table, or the system default if no line separator was found in the text to format.
      Returns:
        the line separator between table rows.
      Since:
        1.0

    - #### getRowCount

          public int getRowCount()

      Returns the number of rows in this table. This count is reset to 0 by `flush()`.
      Returns:
        the number of rows in this table.

    - #### getColumnCount

          public int getColumnCount()

      Returns the number of columns in this table.
      Returns:
        the number of columns in this table.

    - #### append

          public TableAppender append​(char c)

      Writes a single character. If `isMultiLinesCells()` is `false` (which is the default), then:
      - Tabulations (`'\t'`) are replaced by calls to `nextColumn()`.
      - line or paragraph separators are replaced by calls to `nextLine()`.
      Specified by:
        `append` in interface `Appendable`
      Parameters:
        `c` - character to write.
      Returns:
        `this`.

    - #### append

          public TableAppender append​(CharSequence sequence)

      Appends the specified character sequence.
      Specified by:
        `append` in interface `Appendable`
      Parameters:
        `sequence` - the character sequence to append, or `null`.
      Returns:
        a reference to this `Appendable`.

    - #### append

          public TableAppender append​(CharSequence sequence,
                                      int start,
                                      int end)

      Writes a portion of a character sequence. Tabulations and line separators are interpreted as by `append(char)`.
      Specified by:
        `append` in interface `Appendable`
      Parameters:
        `sequence` - the character sequence to be written.
        `start` - index from which to start reading characters.
        `end` - index of the character following the last character to read.
      Returns:
        `this`.

    - #### appendHorizontalSeparator

          public void appendHorizontalSeparator()

      Writes an horizontal separator using the `'─'` character.
      See Also:
        `nextLine(char)`

    - #### nextColumn

          public void nextColumn()

      Moves one column to the right. The subsequent writing operations will occur in a new cell on the same row.

    - #### nextColumn

          public void nextColumn​(char fill)

      Moves one column to the right, filling remaining space with the given character. The subsequent writing operations will occur in a new cell on the same row.

      Calling `nextColumn('*')` from the first character in a cell is a convenient way to put a pad value in this cell.

      Parameters:
        `fill` - character filling the cell (default to whitespace).

    - #### nextLine

          public void nextLine()

      Moves to the first column on the next row. The subsequent writing operations will occur on a new row.

    - #### nextLine

          public void nextLine​(char fill)

      Moves to the first column on the next row, filling every remaining cell in the current row with the specified character. The subsequent writing operations will occur on a new row.

      Calling `nextLine('-')` or `nextLine('═')` from the first column of a row is a convenient way to fill this row with a line separator.

      Parameters:
        `fill` - character filling the rest of the line (default to whitespace). This character may be use as a row separator.
      See Also:
        `appendHorizontalSeparator()`

    - #### flush

          public void flush()
                     throws IOException

      Flushes the table content to the underlying stream or buffer. This method should not be called before the table is completed (otherwise, columns may have the wrong width).
      Specified by:
        `flush` in interface `Flushable`
      Throws:
        `IOException` - if an output operation failed.

    - #### toString

          public String toString()

      Returns the content of this `TableAppender` as a string if possible.
      - If this `TableAppender` has been created without explicit `Appendable`, then this method always returns the current table content formatted as a string.
      - Otherwise, if `out` implements `CharSequence` or is directly or indirectly a wrapper around a `CharSequence`, returns its `toString()` representation. The string will contain this table content only if `flush()` has been invoked prior this `toString()` method.
      - Otherwise returns the localized "Unavailable content" string.
      Returns:
        the content of this `Appendable`, or a localized message for unavailable content.
      See Also:
        `IO​.content(Appendable)`