Package org.apache.sis.math

## Class StatisticsFormat

- Object
- - Format
  - - CompoundFormat<T>
    - - TabularFormat<Statistics>
      - - StatisticsFormat

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

      public class StatisticsFormat
      extends TabularFormat<Statistics>

  Formats a `Statistics` object. By default, newly created `StatisticsFormat` instances will format statistical values in a tabular format using spaces as the column separator.
  Example:

  >     Number of values:     8726
  >     Minimum value:       6.853
  >     Maximum value:       8.259
  >     Mean value:          7.421
  >     Root Mean Square:    7.846
  >     Standard deviation:  6.489

  Limitations:

  - The current implementation can only format features — parsing is not yet implemented.
  - `StatisticsFormat`, like most `java​.text​.Format` subclasses, is not thread-safe.
  Since:
    0.3
  See Also:
    `Statistics​.toString()`, Serialized Form

  Defined in the `sis-utility` module

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class Format

      `Format​.Field`

  - ### Field Summary

    - ### Fields inherited from class TabularFormat

      `beforeFill, columnSeparator, fillCharacter, lineSeparator, omitTrailingNulls`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `StatisticsFormat​(Locale locale, Locale headerLocale, TimeZone timezone)` | Constructs a new format for the given numeric and header locales.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `StatisticsFormat` | `clone()` | Returns a clone of this format.
    `StringBuffer` | `format​(Object object, StringBuffer toAppendTo, FieldPosition pos)` | Formats the given statistics.
    `void` | `format​(Statistics[] stats, Appendable toAppendTo)` | Formats the given statistics in a tabular format.
    `void` | `format​(Statistics stats, Appendable toAppendTo)` | Formats a localized string representation of the given statistics.
    `int` | `getBorderWidth()` | Returns the "width" of the border to drawn around the table, in number of lines.
    `static StatisticsFormat` | `getInstance()` | Returns an instance for the current system default locale.
    `static StatisticsFormat` | `getInstance​(Locale locale)` | Returns an instance for the given locale.
    `Locale` | `getLocale​(Locale.Category category)` | Returns the locale for the given category.
    `Class<Statistics>` | `getValueType()` | Returns the type of objects formatted by this class.
    `boolean` | `isForAllPopulation()` | Returns `true` if this formatter shall consider that the statistics where computed using the totality of the populations under study.
    `Statistics` | `parse​(CharSequence text, ParsePosition pos)` | Not yet supported.
    `void` | `setBorderWidth​(int borderWidth)` | Sets the "width" of the border to drawn around the table, in number of lines.
    `void` | `setForAllPopulation​(boolean allPopulation)` | Sets whether this formatter shall consider that the statistics where computed using the totality of the populations under study.

    - ### Methods inherited from class TabularFormat

      `getColumnSeparatorMatcher, getColumnSeparatorPattern, getLineSeparator, setColumnSeparatorPattern, setLineSeparator`

    - ### Methods inherited from class CompoundFormat

      `createFormat, getFormat, getLocale, getTimeZone, parseObject, parseObject`

    - ### Methods inherited from class Format

      `format, formatToCharacterIterator`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### StatisticsFormat

          public StatisticsFormat​(Locale locale,
                                  Locale headerLocale,
                                  TimeZone timezone)

      Constructs a new format for the given numeric and header locales. The timezone is used only if the values added to the `Statistics` are dates.
      Parameters:
        `locale` - the locale to use for numbers, dates and angles formatting, or `null` for the root locale.
        `headerLocale` - the locale for row and column headers. Usually same as `locale`.
        `timezone` - the timezone, or `null` for UTC.

  - ### Method Detail

    - #### getInstance

          public static StatisticsFormat getInstance()

      Returns an instance for the current system default locale.
      Returns:
        a statistics format instance for the current default locale.

    - #### getInstance

          public static StatisticsFormat getInstance​(Locale locale)

      Returns an instance for the given locale.
      Parameters:
        `locale` - the locale for which to get a `StatisticsFormat` instance.
      Returns:
        a statistics format instance for the given locale.

    - #### getLocale

          public Locale getLocale​(Locale.Category category)

      Returns the locale for the given category. This method implements the following mapping:
      - `Locale​.Category​.DISPLAY` — the `headerLocale` given at construction time.
      - `Locale​.Category​.FORMAT` — the `locale` given at construction time, used for all values below the header row.
      Overrides:
        `getLocale` in class `CompoundFormat<Statistics>`
      Parameters:
        `category` - the category for which a locale is desired.
      Returns:
        the locale for the given category (never `null`).
      Since:
        0.4

    - #### getValueType

          public final Class<Statistics> getValueType()

      Returns the type of objects formatted by this class.
      Specified by:
        `getValueType` in class `CompoundFormat<Statistics>`
      Returns:
        `Statistics​.class`

    - #### isForAllPopulation

          public boolean isForAllPopulation()

      Returns `true` if this formatter shall consider that the statistics where computed using the totality of the populations under study. This information impacts the standard deviation values to be formatted.
      Returns:
        `true` if the statistics to format where computed using the totality of the populations under study.
      See Also:
        `Statistics​.standardDeviation(boolean)`

    - #### setForAllPopulation

          public void setForAllPopulation​(boolean allPopulation)

      Sets whether this formatter shall consider that the statistics where computed using the totality of the populations under study. The default value is `false`.
      Parameters:
        `allPopulation` - `true` if the statistics to format where computed using the totality of the populations under study.
      See Also:
        `Statistics​.standardDeviation(boolean)`

    - #### getBorderWidth

          public int getBorderWidth()

      Returns the "width" of the border to drawn around the table, in number of lines. The default width is 0, which stands for no border.
      Returns:
        the border "width" in number of lines.

    - #### setBorderWidth

          public void setBorderWidth​(int borderWidth)

      Sets the "width" of the border to drawn around the table, in number of lines. The value can be any of the following:
      - 0 (the default) for no border
      - 1 for single line (`│`,`─`)
      - 2 for double lines (`║`,`═`)
      Parameters:
        `borderWidth` - the border width, in number of lines.

    - #### parse

          public Statistics parse​(CharSequence text,
                                  ParsePosition pos)
                           throws ParseException

      Not yet supported.
      Specified by:
        `parse` in class `CompoundFormat<Statistics>`
      Parameters:
        `text` - the character sequence for the object to parse.
        `pos` - the position where to start the parsing. On return, the position where the parsing stopped or where an error occurred.
      Returns:
        currently never return.
      Throws:
        `ParseException` - currently always thrown.

    - #### format

          public StringBuffer format​(Object object,
                                     StringBuffer toAppendTo,
                                     FieldPosition pos)

      Formats the given statistics. This method will delegates to one of the following methods, depending on the type of the given object:
      - `format(Statistics, Appendable)`
      - `format(Statistics[], Appendable)`
      Overrides:
        `format` in class `CompoundFormat<Statistics>`
      Parameters:
        `object` - the object to format.
        `toAppendTo` - where to format the object.
        `pos` - ignored in current implementation.
      Returns:
        the given buffer, returned for convenience.

    - #### format

          public void format​(Statistics stats,
                             Appendable toAppendTo)
                      throws IOException

      Formats a localized string representation of the given statistics. If statistics on differences are associated to the given object, they will be formatted too.
      Specified by:
        `format` in class `CompoundFormat<Statistics>`
      Parameters:
        `stats` - the statistics to format.
        `toAppendTo` - where to format the statistics.
      Throws:
        `IOException` - if an error occurred while writing to the given appendable.

    - #### format

          public void format​(Statistics[] stats,
                             Appendable toAppendTo)
                      throws IOException

      Formats the given statistics in a tabular format. This method does not check for the statistics on differences - if such statistics are wanted, they must be included in the given array.
      Parameters:
        `stats` - the statistics to format.
        `toAppendTo` - where to format the statistics.
      Throws:
        `IOException` - if an error occurred while writing to the given appendable.

    - #### clone

          public StatisticsFormat clone()

      Returns a clone of this format.
      Overrides:
        `clone` in class `TabularFormat<Statistics>`
      Returns:
        a clone of this format.