Package org.apache.sis.util.iso

## Class AbstractInternationalString

- Object
- - AbstractInternationalString

- All Implemented Interfaces:
    `CharSequence`, `Comparable<InternationalString>`, `Formattable`, `InternationalString`
  Direct Known Subclasses:
    `DefaultInternationalString`, `ResourceInternationalString`, `SimpleInternationalString`

      public abstract class AbstractInternationalString
      extends Object
      implements InternationalString, Formattable

  Base class for character strings that has been internationalized into several locales. The `InternationalString` interface is used instead of the `String` class whenever an attribute needs to be internationalization capable.

  The default value (as returned by `toString()` and other `CharSequence` methods) is the string in the current system-wide default locale. The natural ordering is defined by the value returned by `toString()`.

  Substituting a free text by a code list
  The ISO standard allows to substitute some character strings in the "free text" domain by a `CodeList` value. This can be done with:
  - `Types​.getCodeTitle(CodeList)` for getting the `InternationalString` instance to store in a metadata property.
  - `Types​.forCodeTitle(CharSequence)` for retrieving the `CodeList` previously stored as an `InternationalString`.
  Since:
    0.3

  Defined in the `sis-utility` module

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AbstractInternationalString()` | Constructs an international string.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `char` | `charAt​(int index)` | Returns the character of the string in the default locale at the specified index.
    `int` | `compareTo​(InternationalString object)` | Compares this string with the specified object for order.
    `void` | `formatTo​(Formatter formatter, int flags, int width, int precision)` | Formats this international string using the given formatter.
    `int` | `length()` | Returns the length of the string in the default locale.
    `CharSequence` | `subSequence​(int start, int end)` | Returns a subsequence of the string in the default locale.
    `String` | `toString()` | Returns this string in the default locale.
    `abstract String` | `toString​(Locale locale)` | Returns this string in the given locale.

    - ### Methods inherited from class Object

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

    - ### Methods inherited from interface CharSequence

      `chars, codePoints`

- - ### Constructor Detail

    - #### AbstractInternationalString

          protected AbstractInternationalString()

      Constructs an international string.

  - ### Method Detail

    - #### length

          public int length()

      Returns the length of the string in the default locale. This is the length of the string returned by `toString()`.
      Specified by:
        `length` in interface `CharSequence`
      Returns:
        length of the string in the default locale.

    - #### charAt

          public char charAt​(int index)
                      throws IndexOutOfBoundsException

      Returns the character of the string in the default locale at the specified index. This is a character of the string returned by `toString()`.
      Specified by:
        `charAt` in interface `CharSequence`
      Parameters:
        `index` - the index of the character.
      Returns:
        the character at the specified index.
      Throws:
        `IndexOutOfBoundsException` - if the specified index is out of bounds.

    - #### subSequence

          public CharSequence subSequence​(int start,
                                          int end)

      Returns a subsequence of the string in the default locale. The subsequence is a `String` object starting with the character value at the specified index and ending with the character value at index `end - 1`.
      Specified by:
        `subSequence` in interface `CharSequence`
      Parameters:
        `start` - the start index, inclusive.
        `end` - the end index, exclusive.
      Returns:
        the specified subsequence.
      Throws:
        `IndexOutOfBoundsException` - if `start` or `end` is out of range.

    - #### toString

          public abstract String toString​(Locale locale)

      Returns this string in the given locale. If no string is available in the given locale, then some fallback locale is used. The fallback locale is implementation-dependent, and is not necessarily the same than the default locale used by the `toString()` method.
      Handling of `Locale​.ROOT` argument value
      `Locale​.ROOT` can be given to this method for requesting a "unlocalized" string, typically some programmatic values like enumerations or identifiers. While identifiers often look like English words, `Locale​.ROOT` is not considered synonymous to `Locale​.ENGLISH` because the values may differ in the way numbers and dates are formatted (e.g. using the ISO 8601 standard for dates instead than English conventions).
      Handling of `null` argument value
      The `Locale​.ROOT` constant is new in Java 6. Some other libraries designed for Java 5 use the `null` value for "unlocalized" strings. Apache SIS accepts `null` value for inter-operability with those libraries. However the behavior is implementation dependent: some subclasses will take `null` as a synonymous of the system default locale, while other subclasses will take `null` as a synonymous of the root locale. In order to ensure determinist behavior, client code are encouraged to specify only non-null values.
      Specified by:
        `toString` in interface `InternationalString`
      Parameters:
        `locale` - the desired locale for the string to be returned.
      Returns:
        the string in the given locale if available, or in an implementation-dependent fallback locale otherwise.
      See Also:
        `Locale​.getDefault()`, `Locale​.ROOT`

    - #### toString

          public String toString()

      Returns this string in the default locale. Invoking this method is equivalent to invoking `toString(Locale​.getDefault())`.

      All methods from `CharSequence` operate on this string. This string is also used as the criterion for natural ordering.

      Specified by:
        `toString` in interface `CharSequence`
      Specified by:
        `toString` in interface `InternationalString`
      Overrides:
        `toString` in class `Object`
      Returns:
        the string in the default locale.

    - #### formatTo

          public void formatTo​(Formatter formatter,
                               int flags,
                               int width,
                               int precision)

      Formats this international string using the given formatter. This method appends the string obtained by:

      > `toString(formatter.Formatter​.locale())`

      Specified by:
        `formatTo` in interface `Formattable`
      Parameters:
        `formatter` - the formatter to use for formatting this string.
        `flags` - a bitmask of `FormattableFlags` values.
        `width` - the minimum number of characters, or -1 if none.
        `precision` - the maximum number of characters (before expanding to the `width`), or -1 for no restriction.

    - #### compareTo

          public int compareTo​(InternationalString object)

      Compares this string with the specified object for order. This method compares the string in the default locale, as returned by `toString()`.
      Specified by:
        `compareTo` in interface `Comparable<InternationalString>`
      Parameters:
        `object` - the string to compare with this string.
      Returns:
        a negative number if this string is before the given string, a positive number if after, or 0 if equals.