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 and Description
    --- | ---
    `protected` | `AbstractInternationalString()` Constructs an international string.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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.

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