org.crosswire.common.util

## Class Language

- java.lang.Object
- - org.crosswire.common.util.Language

- All Implemented Interfaces:
    Comparable<Language>

      public class Language
      extends Object
      implements Comparable<Language>

  An immutable Language by specification. The specifier consists of up to three parts:
  - LL - An iso639-2 or iso639-3 language code
  - SSSS - A 4-letter iso15924 script code
  - CC - A 2-letter iso3166 country code
  Note: This is a subset of the BCP-47 standard.
  Author:
    DM Smith
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `Language.CanonicalUtils` Converts substrings to the canonical representation for language code, script and country.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private String` | `code` The lower case iso639 language code.
    `private String` | `country` The UPPER case iso3166 country code.
    `static Language` | `DEFAULT_LANG` The default language is English.
    `static String` | `DEFAULT_LANG_CODE` The default language code is en for English.
    `private String` | `found` The effective specification.
    `private String` | `given` The original specification provided by the user.
    `private boolean` | `knowsDirection`
    `private boolean` | `ltor`
    `private String` | `name` The name as defined by Languages.
    `private String` | `script` The Title case iso15924 script code.
    `static String` | `UNKNOWN_LANG_CODE` The language code for invalid language specifications is und for Undetermined.
    `private boolean` | `valid` Flag to store whether the code is valid.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Language(String specification)` A single language defined by an ISO-639 code.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private boolean` | `compareStrings(String a, String b)` Equal if both a and b are the same.
    `int` | `compareTo(Language o)`
    `boolean` | `equals(Object obj)`
    `String` | `getCode()` Get the iso639 language code.
    `String` | `getCountry()` Get the iso3166 script for the language.
    `String` | `getFoundSpecification()` The specification that was given might not be be the one that ultimately gets the name.
    `String` | `getGivenSpecification()` The specification that was given might not be be the one that ultimately gets the name.
    `String` | `getName()` Get the localized language name.
    `String` | `getScript()` Get the iso15924 script for the language.
    `int` | `hashCode()`
    `boolean` | `isLeftToRight()` Determine whether this language is a Left-to-Right or a Right-to-Left language.
    `boolean` | `isValidLanguage()` Determine whether this language is valid.
    `private void` | `parse(String spec)` Split the specification on '-' into 1 to 3 parts.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DEFAULT_LANG_CODE

          public static final String DEFAULT_LANG_CODE

      The default language code is en for English.
      See Also:
        Constant Field Values

    - #### UNKNOWN_LANG_CODE

          public static final String UNKNOWN_LANG_CODE

      The language code for invalid language specifications is und for Undetermined.
      See Also:
        Constant Field Values

    - #### DEFAULT_LANG

          public static final Language DEFAULT_LANG

      The default language is English.

    - #### given

          private String given

      The original specification provided by the user.

    - #### found

          private String found

      The effective specification.

    - #### code

          private String code

      The lower case iso639 language code.

    - #### script

          private String script

      The Title case iso15924 script code.

    - #### country

          private String country

      The UPPER case iso3166 country code.

    - #### name

          private String name

      The name as defined by Languages.

    - #### valid

          private boolean valid

      Flag to store whether the code is valid.

    - #### knowsDirection

          private boolean knowsDirection

    - #### ltor

          private boolean ltor

  - ### Constructor Detail

    - #### Language

          public Language(String specification)

      A single language defined by an ISO-639 code. If the code is null or empty then it is considered to be DEFAULT_LANG (that is, English).
      Parameters:
        `specification` - the specifier for the particular language

  - ### Method Detail

    - #### getGivenSpecification

          public String getGivenSpecification()

      The specification that was given might not be be the one that ultimately gets the name.
      Returns:
        the specification that was originally given.

    - #### getFoundSpecification

          public String getFoundSpecification()

      The specification that was given might not be be the one that ultimately gets the name.
      Returns:
        the specification that was used to find the name.

    - #### isValidLanguage

          public boolean isValidLanguage()

      Determine whether this language is valid.
      - LL - An iso639-2 or iso639-3 language code
      - SSSS - A 4-letter iso15924 script code
      - CC - A 2-letter iso3166 country code
      Returns:
        true if the language is valid.

    - #### getCode

          public String getCode()

      Get the iso639 language code.
      Returns:
        the code for the language in lower case.

    - #### getScript

          public String getScript()

      Get the iso15924 script for the language. May be null.
      Returns:
        the code for the script in Title case.

    - #### getCountry

          public String getCountry()

      Get the iso3166 script for the language. May be null.
      Returns:
        the code for the country in UPPER case.

    - #### getName

          public String getName()

      Get the localized language name.
      Returns:
        the name of the language

    - #### isLeftToRight

          public boolean isLeftToRight()

      Determine whether this language is a Left-to-Right or a Right-to-Left language. If the language has a script, it is used for the determination. Otherwise, check the language.

      Note: This is problematic. Languages do not have direction. Scripts do. Further, there are over 7000 living languages, many of which are written in Right-to-Left scripts and are not listed here.

      Returns:
        true if the language is Left-to-Right.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### compareTo

          public int compareTo(Language o)

      Specified by:
        `compareTo` in interface `Comparable<Language>`

    - #### parse

          private void parse(String spec)

      Split the specification on '-' into 1 to 3 parts.
      Parameters:
        `spec` - the specification to parse

    - #### compareStrings

          private boolean compareStrings(String a,
                               String b)

      Equal if both a and b are the same.
      Parameters:
        `a` - a string to compare
        `b` - a string to compare
      Returns:
        true if both are the same.