Module org.apache.sis.util
Package org.apache.sis.io

# Class TabularFormat<T>

Object
Format
CompoundFormat<T>
TabularFormat<T>

Type Parameters:
  `T` - the base type of objects parsed and formatted by this class.

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `Localized`

Direct Known Subclasses:
  `FeatureFormat`, `LocationFormat`, `ParameterFormat`, `StatisticsFormat`, `TreeTableFormat`

public abstract class TabularFormat<T> extends CompoundFormat<T>
Base class for parser and formatter of tabular data, providing control on line and column separators. The line separator is specified by a string. But the column separator is specified by a pattern which provide some control on the character to repeat, and on the strings to insert before and after the repeated character. See the following methods for details:

- `setLineSeparator(String)`
- `setColumnSeparatorPattern(String)`

## Note for subclass implementions

This base class takes care of splitting a column separator pattern into its components (`beforeFill`, `fillCharacter` and `columnSeparator`) for easier usage in `format(…)` method implementations. Subclasses can use those fields like below:

Formatting table without border:

    TableAppender table = new TableAppender(out, "");
    // ... do some work, then add a column separator:
    table.append(beforeFill);
    table.nextColumn(fillCharacter);
    table.append(columnSeparator);

Formatting table with a border:

    TableAppender table = new TableAppender(out, columnSeparator);
    // ... do some work, then add a column separator:
    table.append(beforeFill);
    table.nextColumn(fillCharacter);

Since:
  0.3
See Also:
  - `TableAppender`
  - Serialized Form

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class Format

  `Format​.Field`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected String`
  `beforeFill`
  The string to write before the `fillCharacter`, or an empty string if none.
  `protected String`
  `columnSeparator`
  The string to write after the `fillCharacter`, or an empty string if none.
  `protected char`
  `fillCharacter`
  The character to repeat after the content of a cell for alignment with the next column.
  `protected String`
  `lineSeparator`
  The line separator to use for formatting the tree.
  `protected boolean`
  `omitTrailingNulls`
  `true` if the trailing `null` values shall be omitted at formatting time.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TabularFormat(Locale locale, TimeZone timezone)`
  Creates a new tabular format.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TabularFormat<T>`
  `clone()`
  Returns a clone of this format.
  `protected Matcher`
  `getColumnSeparatorMatcher(CharSequence text)`
  Returns a matcher for the column separators in the given text.
  `String`
  `getColumnSeparatorPattern()`
  Returns the pattern of characters used in column separators.
  `String`
  `getLineSeparator()`
  Returns the current line separator.
  `void`
  `setColumnSeparatorPattern(String pattern)`
  Sets the pattern of the characters to insert between the columns.
  `void`
  `setLineSeparator(String separator)`
  Sets the line separator.

  ### Methods inherited from class CompoundFormat

  `createFormat, format, format, getFormat, getLocale, getLocale, getTimeZone, getValueType, parse, parseObject, parseObject`

  ### Methods inherited from class Format

  `format, formatToCharacterIterator`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### lineSeparator

    protected String lineSeparator
    The line separator to use for formatting the tree. The default value is system-dependent.
    See Also:
      - `getLineSeparator()`
      - `setLineSeparator(String)`

  - ### columnSeparator

    protected String columnSeparator
    The string to write after the `fillCharacter`, or an empty string if none. This is the sequence of characters after the "`[ ]`" pair of brackets in the pattern given to the `setColumnSeparatorPattern(String)` method.

  - ### fillCharacter

    protected char fillCharacter
    The character to repeat after the content of a cell for alignment with the next column. This is the character between the "`[ ]`" pair of brackets in the pattern given to the `setColumnSeparatorPattern(String)` method.

    Subclasses will typically use this value in calls to `TableAppender​.nextColumn(char)`.

  - ### beforeFill

    protected String beforeFill
    The string to write before the `fillCharacter`, or an empty string if none. This is the sequence of characters before the "`[ ]`" pair of brackets in the pattern given to the `setColumnSeparatorPattern(String)` method.

  - ### omitTrailingNulls

    protected boolean omitTrailingNulls
    `true` if the trailing `null` values shall be omitted at formatting time. This flag is controlled by the presence or absence of the `'?'` character at the beginning of the pattern given to the `setColumnSeparatorPattern(String)` method.

- ## Constructor Details

  - ### TabularFormat

    public TabularFormat(Locale locale, TimeZone timezone)
    Creates a new tabular format.
    Parameters:
      `locale` - the locale to use for numbers, dates and angles formatting, or `null` for the root locale.
      `timezone` - the timezone, or `null` for UTC.

- ## Method Details

  - ### getLineSeparator

    public String getLineSeparator()
    Returns the current line separator. The default value is system-dependent.
    Returns:
      the current line separator.

  - ### setLineSeparator

    public void setLineSeparator(String separator)
    Sets the line separator. Cannot be a null or empty string.
    Parameters:
      `separator` - the new line separator.

  - ### getColumnSeparatorPattern

    public String getColumnSeparatorPattern()
    Returns the pattern of characters used in column separators. Those characters will be used only if more than one column is formatted. See `setColumnSeparatorPattern(String)` for a description of the pattern syntax.
    Returns:
      the pattern of the current column separator.

  - ### setColumnSeparatorPattern

    public void setColumnSeparatorPattern(String pattern) throws IllegalArgumentException
    Sets the pattern of the characters to insert between the columns. The pattern shall contain exactly one occurrence of the `"[ ]"` pair of bracket, with exactly one character between them. This character will be repeated as many time as needed for columns alignment.

    The formatting pattern can optionally be followed by a regular expression to be used at parsing time. If omitted, the parsing pattern will be inferred from the formatting pattern. If specified, then the `parse` method will invoke the `Matcher​.find()` method for determining the column boundaries.

    The characters listed below have special meaning in the pattern. Other characters are appended as-is between the columns.

    Reserved characters
    Character(s) | Meaning
    --- | ---
    `'?'` | Omit the column separator for trailing null values.
    `"[ ]"` | Repeat the character between bracket as needed.
    `'/'` | Separate the formatting pattern from the parsing pattern.
    `'\\'` | Escape any of the characters listed in this table.

    #### Restrictions

    - If present, `'?'` shall be the first character in the pattern.
    - The repeated character (specified inside the pair of brackets) is mandatory.
    - In the current implementation, the repeated character must be in the Basic Multilanguage Plane.
    - If `'/'` is present, anything on its right side shall be compliant with the `Pattern` syntax.

    #### Example

    The `"?……[…] "` pattern means "If the next value is non-null, then insert the `"……"` string, repeat the `'…'` character as many time as needed (may be zero), then insert a space".
    Parameters:
      `pattern` - the pattern of the new column separator.
    Throws:
      `IllegalArgumentException` - if the given pattern is illegal.

  - ### getColumnSeparatorMatcher

    protected Matcher getColumnSeparatorMatcher(CharSequence text)
    Returns a matcher for the column separators in the given text. This method is invoked by subclasses in their `parse(…)` implementations.
    Parameters:
      `text` - the text for which to get a matcher.
    Returns:
      a matcher for the column separators in the given text.

  - ### clone

    public TabularFormat<T> clone()
    Returns a clone of this format.
    Overrides:
      `clone` in class `CompoundFormat<T>`
    Returns:
      a clone of this format.