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

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.