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

  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.
  `final 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 Details

  - ### 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 Details

  - ### 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.