root/trunk/tango/text/locale/Core.d

/*******************************************************************************

        copyright:      Copyright (c) 2005 John Chapman. All rights reserved

        license:        BSD style: $(LICENSE)

        version:        Initial release: 2005

        author:         John Chapman

        Contains classes that provide information about locales, such as 
        the language and calendars, as well as cultural conventions used 
        for formatting dates, currency and numbers. Use these classes when 
        writing applications for an international audience.

******************************************************************************/

/**
 * $(MEMBERTABLE
 * $(TR
 * $(TH Interface)
 * $(TH Description)
 * )
 * $(TR
 * $(TD $(LINK2 #IFormatService, IFormatService))
 * $(TD Retrieves an object to control formatting.)
 * )
 * )
 *
 * $(MEMBERTABLE
 * $(TR
 * $(TH Class)
 * $(TH Description)
 * )
 * $(TR
 * $(TD $(LINK2 #Calendar, Calendar))
 * $(TD Represents time in week, month and year divisions.)
 * )
 * $(TR
 * $(TD $(LINK2 #Culture, Culture))
 * $(TD Provides information about a culture, such as its name, calendar and date and number format patterns.)
 * )
 * $(TR
 * $(TD $(LINK2 #DateTimeFormat, DateTimeFormat))
 * $(TD Determines how $(LINK2 #Time, Time) values are formatted, depending on the culture.)
 * )
 * $(TR
 * $(TD $(LINK2 #DaylightSavingTime, DaylightSavingTime))
 * $(TD Represents a period of daylight-saving time.)
 * )
 * $(TR
 * $(TD $(LINK2 #Gregorian, Gregorian))
 * $(TD Represents the Gregorian calendar.)
 * )
 * $(TR
 * $(TD $(LINK2 #Hebrew, Hebrew))
 * $(TD Represents the Hebrew calendar.)
 * )
 * $(TR
 * $(TD $(LINK2 #Hijri, Hijri))
 * $(TD Represents the Hijri calendar.)
 * )
 * $(TR
 * $(TD $(LINK2 #Japanese, Japanese))
 * $(TD Represents the Japanese calendar.)
 * )
 * $(TR
 * $(TD $(LINK2 #Korean, Korean))
 * $(TD Represents the Korean calendar.)
 * )
 * $(TR
 * $(TD $(LINK2 #NumberFormat, NumberFormat))
 * $(TD Determines how numbers are formatted, according to the current culture.)
 * )
 * $(TR
 * $(TD $(LINK2 #Region, Region))
 * $(TD Provides information about a region.)
 * )
 * $(TR
 * $(TD $(LINK2 #Taiwan, Taiwan))
 * $(TD Represents the Taiwan calendar.)
 * )
 * $(TR
 * $(TD $(LINK2 #ThaiBuddhist, ThaiBuddhist))
 * $(TD Represents the Thai Buddhist calendar.)
 * )
 * )
 *
 * $(MEMBERTABLE
 * $(TR
 * $(TH Struct)
 * $(TH Description)
 * )
 * $(TR
 * $(TD $(LINK2 #Time, Time))
 * $(TD Represents time expressed as a date and time of day.)
 * )
 * $(TR
 * $(TD $(LINK2 #TimeSpan, TimeSpan))
 * $(TD Represents a time interval.)
 * )
 * )
 */

module tango.text.locale.Core;

private import  tango.core.Exception;

private import  tango.text.locale.Data;

private import  tango.time.Time;

private import  tango.time.chrono.Hijri,
                tango.time.chrono.Korean,
                tango.time.chrono.Taiwan,
                tango.time.chrono.Hebrew,
                tango.time.chrono.Calendar,
                tango.time.chrono.Japanese,
                tango.time.chrono.Gregorian,
                tango.time.chrono.ThaiBuddhist;
        
version (Windows)
         private import tango.text.locale.Win32;

version (Posix)
         private import tango.text.locale.Posix;


// Initializes an array.
private template arrayOf(T) {
  private T[] arrayOf(T[] params ...) {
    return params.dup;
  }
}


/**
 * Defines the types of cultures that can be retrieved from Culture.getCultures.
 */
public enum CultureTypes {
  Neutral = 1,             /// Refers to cultures that are associated with a language but not specific to a country or region.
  Specific = 2,            /// Refers to cultures that are specific to a country or region.
  All = Neutral | Specific /// Refers to all cultures.
}


/**
 * $(ANCHOR _IFormatService)
 * Retrieves an object to control formatting.
 * 
 * A class implements $(LINK2 #IFormatService_getFormat, getFormat) to retrieve an object that provides format information for the implementing type.
 * Remarks: IFormatService is implemented by $(LINK2 #Culture, Culture), $(LINK2 #NumberFormat, NumberFormat) and $(LINK2 #DateTimeFormat, DateTimeFormat) to provide locale-specific formatting of
 * numbers and date and time values.
 */
public interface IFormatService {

  /**
   * $(ANCHOR IFormatService_getFormat)
   * Retrieves an object that supports formatting for the specified _type.
   * Returns: The current instance if type is the same _type as the current instance; otherwise, null.
   * Params: type = An object that specifies the _type of formatting to retrieve.
   */
  Object getFormat(TypeInfo type);

}

/**
 * $(ANCHOR _Culture)
 * Provides information about a culture, such as its name, calendar and date and number format patterns.
 * Remarks: tango.text.locale adopts the RFC 1766 standard for culture names in the format <language>"-"<region>. 
 * <language> is a lower-case two-letter code defined by ISO 639-1. <region> is an upper-case 
 * two-letter code defined by ISO 3166. For example, "en-GB" is UK English.
 * $(BR)$(BR)There are three types of culture: invariant, neutral and specific. The invariant culture is not tied to
 * any specific region, although it is associated with the English language. A neutral culture is associated with
 * a language, but not with a region. A specific culture is associated with a language and a region. "es" is a neutral 
 * culture. "es-MX" is a specific culture.
 * $(BR)$(BR)Instances of $(LINK2 #DateTimeFormat, DateTimeFormat) and $(LINK2 #NumberFormat, NumberFormat) cannot be created for neutral cultures.
 * Examples:
 * ---
 * import tango.io.Stdout, tango.text.locale.Core;
 *
 * void main() {
 *   Culture culture = new Culture("it-IT");
 *
 *   Stdout.formatln("englishName: {}", culture.englishName);
 *   Stdout.formatln("nativeName: {}", culture.nativeName);
 *   Stdout.formatln("name: {}", culture.name);
 *   Stdout.formatln("parent: {}", culture.parent.name);
 *   Stdout.formatln("isNeutral: {}", culture.isNeutral);
 * }
 *
 * // Produces the following output:
 * // englishName: Italian (Italy)
 * // nativeName: italiano (Italia)
 * // name: it-IT
 * // parent: it
 * // isNeutral: false
 * ---
 */
public class Culture : IFormatService {

  private const int LCID_INVARIANT = 0x007F;

  private static Culture[char[]] namedCultures;
  private static Culture[int] idCultures;
  private static Culture[char[]] ietfCultures;

  private static Culture currentCulture_;
  private static Culture userDefaultCulture_; // The user's default culture (GetUserDefaultLCID).
  private static Culture invariantCulture_; // The invariant culture is associated with the English language.
  private Calendar calendar_;
  private Culture parent_;
  private CultureData* cultureData_;
  private bool isReadOnly_;
  private NumberFormat numberFormat_;
  private DateTimeFormat dateTimeFormat_;

  static this() {
    invariantCulture_ = new Culture(LCID_INVARIANT);
    invariantCulture_.isReadOnly_ = true;

    userDefaultCulture_ = new Culture(nativeMethods.getUserCulture());
    if (userDefaultCulture_ is null)
      // Fallback
      userDefaultCulture_ = invariantCulture;
    else
      userDefaultCulture_.isReadOnly_ = true;
  }

  static ~this() {
    namedCultures = null;
    idCultures = null;
    ietfCultures = null;
  }

  /**
   * Initializes a new Culture instance from the supplied name.
   * Params: cultureName = The name of the Culture.
   */
  public this(char[] cultureName) {
    cultureData_ = CultureData.getDataFromCultureName(cultureName);
  }

  /**
   * Initializes a new Culture instance from the supplied culture identifier.
   * Params: cultureID = The identifer (LCID) of the Culture.
   * Remarks: Culture identifiers correspond to a Windows LCID.
   */
  public this(int cultureID) {
    cultureData_ = CultureData.getDataFromCultureID(cultureID);
  }

  /**
   * Retrieves an object defining how to format the specified type.
   * Params: type = The TypeInfo of the resulting formatting object.
   * Returns: If type is typeid($(LINK2 #NumberFormat, NumberFormat)), the value of the $(LINK2 #Culture_numberFormat, numberFormat) property. If type is typeid($(LINK2 #DateTimeFormat, DateTimeFormat)), the
   * value of the $(LINK2 #Culture_dateTimeFormat, dateTimeFormat) property. Otherwise, null.
   * Remarks: Implements $(LINK2 #IFormatService_getFormat, IFormatService.getFormat).
   */
  public Object getFormat(TypeInfo type) {
    if (type is typeid(NumberFormat))
      return numberFormat;
    else if (type is typeid(DateTimeFormat))
      return dateTimeFormat;
    return null;
  }

version (Clone)
{
  /**
   * Copies the current Culture instance.
   * Returns: A copy of the current Culture instance.
   * Remarks: The values of the $(LINK2 #Culture_numberFormat, numberFormat), $(LINK2 #Culture_dateTimeFormat, dateTimeFormat) and $(LINK2 #Culture_calendar, calendar) properties are copied also.
   */
  public Object clone() {
    Culture culture = cast(Culture)cloneObject(this);
    if (!culture.isNeutral) {
      if (dateTimeFormat_ !is null)
        culture.dateTimeFormat_ = cast(DateTimeFormat)dateTimeFormat_.clone();
      if (numberFormat_ !is null)
        culture.numberFormat_ = cast(NumberFormat)numberFormat_.clone();
    }
    if (calendar_ !is null)
      culture.calendar_ = cast(Calendar)calendar_.clone();
    return culture;
  }
}

  /**
   * Returns a read-only instance of a culture using the specified culture identifier.
   * Params: cultureID = The identifier of the culture.
   * Returns: A read-only culture instance.
   * Remarks: Instances returned by this method are cached.
   */
  public static Culture getCulture(int cultureID) {
    Culture culture = getCultureInternal(cultureID, null);

version (Posix) {
    if (culture is null)
        error ("Culture not found - if this was not tried set by the application, Tango\n"
            ~ "will expect that a locale is set via environment variables LANG or LC_ALL.");
}

    return culture;
  }

  /**
   * Returns a read-only instance of a culture using the specified culture name.
   * Params: cultureName = The name of the culture.
   * Returns: A read-only culture instance.
   * Remarks: Instances returned by this method are cached.
   */
  public static Culture getCulture(char[] cultureName) {
    if (cultureName is null)
       error("Value cannot be null.");
    Culture culture = getCultureInternal(0, cultureName);
    if (culture is null)
      error("Culture name " ~ cultureName ~ " is not supported.");
    return culture;
  }

  /**
    * Returns a read-only instance using the specified name, as defined by the RFC 3066 standard and maintained by the IETF.
    * Params: name = The name of the language.
    * Returns: A read-only culture instance.
    */
  public static Culture getCultureFromIetfLanguageTag(char[] name) {
    if (name is null)
      error("Value cannot be null.");
    Culture culture = getCultureInternal(-1, name);
    if (culture is null)
      error("Culture IETF name " ~ name ~ " is not a known IETF name.");
    return culture;
  }

  private static Culture getCultureInternal(int cultureID, char[] cname) {
    // If cultureID is - 1, name is an IETF name; if it's 0, name is a culture name; otherwise, it's a valid LCID.
    char[] name = cname; 
    foreach (i, c; cname)
       if (c is '_') {
         name = cname.dup;
         name[i] = '-';
         break;
       }

    // Look up tables first.
    if (cultureID == 0) {
      if (Culture* culture = name in namedCultures)
        return *culture;
    }
    else if (cultureID > 0) {
      if (Culture* culture = cultureID in idCultures)
        return *culture;
    }
    else if (cultureID == -1) {
      if (Culture* culture = name in ietfCultures)
        return *culture;
    }

    // Nothing found, create a new instance.
    Culture culture;

    try {
      if (cultureID == -1) {
        name = CultureData.getCultureNameFromIetfName(name);
        if (name is null)
          return null;
      }
      else if (cultureID == 0)
        culture = new Culture(name);
      else if (userDefaultCulture_ !is null && userDefaultCulture_.id == cultureID) {
        culture = userDefaultCulture_;
      }
      else
        culture = new Culture(cultureID);
    }
    catch (LocaleException) {
      return null;
    }

    culture.isReadOnly_ = true;

    // Now cache the new instance in all tables.
    ietfCultures[culture.ietfLanguageTag] = culture;
    namedCultures[culture.name] = culture;
    idCultures[culture.id] = culture;

    return culture;
  }

  /**
   * Returns a list of cultures filtered by the specified $(LINK2 constants.html#CultureTypes, CultureTypes).
   * Params: types = A combination of CultureTypes.
   * Returns: An array of Culture instances containing cultures specified by types.
   */
  public static Culture[] getCultures(CultureTypes types) {
    bool includeSpecific = (types & CultureTypes.Specific) != 0;
    bool includeNeutral = (types & CultureTypes.Neutral) != 0;

    int[] cultures;
    for (int i = 0; i < CultureData.cultureDataTable.length; i++) {
      if ((CultureData.cultureDataTable[i].isNeutral && includeNeutral) || (!CultureData.cultureDataTable[i].isNeutral && includeSpecific))
        cultures ~= CultureData.cultureDataTable[i].lcid;
    }

    Culture[] result = new Culture[cultures.length];
    foreach (int i, int cultureID; cultures)
      result[i] = new Culture(cultureID);
    return result;
  }

  /**
   * Returns the name of the Culture.
   * Returns: A string containing the name of the Culture in the format &lt;language&gt;"-"&lt;region&gt;.
   */
  public override char[] toString() {
    return cultureData_.name;
  }

  public override int opEquals(Object obj) {
    if (obj is this)
      return true;
    Culture other = cast(Culture)obj;
    if (other is null)
      return false;
    return other.name == name; // This needs to be changed so it's culturally aware.
  }

  /**
   * $(ANCHOR Culture_current)
   * $(I Property.) Retrieves the culture of the current user.
   * Returns: The Culture instance representing the user's current culture.
   */
  public static Culture current() {
    if (currentCulture_ !is null)
      return currentCulture_;

    if (userDefaultCulture_ !is null) {
      // If the user has changed their locale settings since last we checked, invalidate our data.
      if (userDefaultCulture_.id != nativeMethods.getUserCulture())
        userDefaultCulture_ = null;
    }
    if (userDefaultCulture_ is null) {
      userDefaultCulture_ = new Culture(nativeMethods.getUserCulture());
      if (userDefaultCulture_ is null)
        userDefaultCulture_ = invariantCulture;
      else
        userDefaultCulture_.isReadOnly_ = true;
    }

    return userDefaultCulture_;
  }
  /**
   * $(I Property.) Assigns the culture of the _current user.
   * Params: value = The Culture instance representing the user's _current culture.
   * Examples:
   * The following examples shows how to change the _current culture.
   * ---
   * import tango.io.Print, tango.text.locale.Common;
   *
   * void main() {
   *   // Displays the name of the current culture.
   *   Println("The current culture is %s.", Culture.current.englishName);
   *
   *   // Changes the current culture to el-GR.
   *   Culture.current = new Culture("el-GR");
   *   Println("The current culture is now %s.", Culture.current.englishName);
   * }
   *
   * // Produces the following output:
   * // The current culture is English (United Kingdom).
   * // The current culture is now Greek (Greece).
   * ---
   */
  public static void current(Culture value) {
    checkNeutral(value);
    nativeMethods.setUserCulture(value.id);
    currentCulture_ = value;
  }

  /**
   * $(I Property.) Retrieves the invariant Culture.
   * Returns: The Culture instance that is invariant.
   * Remarks: The invariant culture is culture-independent. It is not tied to any specific region, but is associated
   * with the English language.
   */
  public static Culture invariantCulture() {
    return invariantCulture_;
  }

  /**
   * $(I Property.) Retrieves the identifier of the Culture.
   * Returns: The culture identifier of the current instance.
   * Remarks: The culture identifier corresponds to the Windows locale identifier (LCID). It can therefore be used when 
   * interfacing with the Windows NLS functions.
   */
  public int id() {
    return cultureData_.lcid;
  }

  /**
   * $(ANCHOR Culture_name)
   * $(I Property.) Retrieves the name of the Culture in the format &lt;language&gt;"-"&lt;region&gt;.
   * Returns: The name of the current instance. For example, the name of the UK English culture is "en-GB".
   */
  public char[] name() {
    return cultureData_.name;
  }

  /**
   * $(I Property.) Retrieves the name of the Culture in the format &lt;languagename&gt; (&lt;regionname&gt;) in English.
   * Returns: The name of the current instance in English. For example, the englishName of the UK English culture 
   * is "English (United Kingdom)".
   */
  public char[] englishName() {
    return cultureData_.englishName;
  }

  /**
   * $(I Property.) Retrieves the name of the Culture in the format &lt;languagename&gt; (&lt;regionname&gt;) in its native language.
   * Returns: The name of the current instance in its native language. For example, if Culture.name is "de-DE", nativeName is 
   * "Deutsch (Deutschland)".
   */
  public char[] nativeName() {
    return cultureData_.nativeName;
  }

  /**
   * $(I Property.) Retrieves the two-letter language code of the culture.
   * Returns: The two-letter language code of the Culture instance. For example, the twoLetterLanguageName for English is "en".
   */
  public char[] twoLetterLanguageName() {
    return cultureData_.isoLangName;
  }

  /**
   * $(I Property.) Retrieves the three-letter language code of the culture.
   * Returns: The three-letter language code of the Culture instance. For example, the threeLetterLanguageName for English is "eng".
   */
  public char[] threeLetterLanguageName() {
    return cultureData_.isoLangName2;
  }

  /**
   * $(I Property.) Retrieves the RFC 3066 identification for a language.
   * Returns: A string representing the RFC 3066 language identification.
   */
  public final char[] ietfLanguageTag() {
    return cultureData_.ietfTag;
  }

  /**
   * $(I Property.) Retrieves the Culture representing the parent of the current instance.
   * Returns: The Culture representing the parent of the current instance.
   */
  public Culture parent() {
    if (parent_ is null) {
      try {
        int parentCulture = cultureData_.parent;
        if (parentCulture == LCID_INVARIANT)
          parent_ = invariantCulture;
        else
          parent_ = new Culture(parentCulture);
      }
      catch {
        parent_ = invariantCulture;
      }
    }
    return parent_;
  }

  /**
   * $(I Property.) Retrieves a value indicating whether the current instance is a neutral culture.
   * Returns: true is the current Culture represents a neutral culture; otherwise, false.
   * Examples:
   * The following example displays which cultures using Chinese are neutral.
   * ---
   * import tango.io.Print, tango.text.locale.Common;
   *
   * void main() {
   *   foreach (c; Culture.getCultures(CultureTypes.All)) {
   *     if (c.twoLetterLanguageName == "zh") {
   *       Print(c.englishName);
   *       if (c.isNeutral)
   *         Println("neutral");
   *       else
   *         Println("specific");
   *     }
   *   }
   * }
   *
   * // Produces the following output:
   * // Chinese (Simplified) - neutral
   * // Chinese (Taiwan) - specific
   * // Chinese (People's Republic of China) - specific
   * // Chinese (Hong Kong S.A.R.) - specific
   * // Chinese (Singapore) - specific
   * // Chinese (Macao S.A.R.) - specific
   * // Chinese (Traditional) - neutral
   * ---
   */
  public bool isNeutral() {
    return cultureData_.isNeutral;
  }

  /**
   * $(I Property.) Retrieves a value indicating whether the instance is read-only.
   * Returns: true if the instance is read-only; otherwise, false.
   * Remarks: If the culture is read-only, the $(LINK2 #Culture_dateTimeFormat, dateTimeFormat) and $(LINK2 #Culture_numberFormat, numberFormat) properties return 
   * read-only instances.
   */
  public final bool isReadOnly() {
    return isReadOnly_;
  }

  /**
   * $(ANCHOR Culture_calendar)
   * $(I Property.) Retrieves the calendar used by the culture.
   * Returns: A Calendar instance respresenting the calendar used by the culture.
   */
  public Calendar calendar() {
    if (calendar_ is null) {
      calendar_ = getCalendarInstance(cultureData_.calendarType, isReadOnly_);
    }
    return calendar_;
  }

  /**
   * $(I Property.) Retrieves the list of calendars that can be used by the culture.
   * Returns: An array of type Calendar representing the calendars that can be used by the culture.
   */
  public Calendar[] optionalCalendars() {
    Calendar[] cals = new Calendar[cultureData_.optionalCalendars.length];
    foreach (int i, int calID; cultureData_.optionalCalendars)
      cals[i] = getCalendarInstance(calID);
    return cals;
  }

  /**
   * $(ANCHOR Culture_numberFormat)
   * $(I Property.) Retrieves a NumberFormat defining the culturally appropriate format for displaying numbers and currency.
   * Returns: A NumberFormat defining the culturally appropriate format for displaying numbers and currency.
  */
  public NumberFormat numberFormat() {
    checkNeutral(this);
    if (numberFormat_ is null) {
      numberFormat_ = new NumberFormat(cultureData_);
      numberFormat_.isReadOnly_ = isReadOnly_;
    }
    return numberFormat_;
  }
  /**
   * $(I Property.) Assigns a NumberFormat defining the culturally appropriate format for displaying numbers and currency.
   * Params: values = A NumberFormat defining the culturally appropriate format for displaying numbers and currency.
   */
  public void numberFormat(NumberFormat value) {
    checkReadOnly();
    numberFormat_ = value;
  }

  /**
   * $(ANCHOR Culture_dateTimeFormat)
   * $(I Property.) Retrieves a DateTimeFormat defining the culturally appropriate format for displaying dates and times.
   * Returns: A DateTimeFormat defining the culturally appropriate format for displaying dates and times.
   */
  public DateTimeFormat dateTimeFormat() {
    checkNeutral(this);
    if (dateTimeFormat_ is null) {
      dateTimeFormat_ = new DateTimeFormat(cultureData_, calendar);
      dateTimeFormat_.isReadOnly_ = isReadOnly_;
    }
    return dateTimeFormat_;
  }
  /**
   * $(I Property.) Assigns a DateTimeFormat defining the culturally appropriate format for displaying dates and times.
   * Params: values = A DateTimeFormat defining the culturally appropriate format for displaying dates and times.
   */
  public void dateTimeFormat(DateTimeFormat value) {
    checkReadOnly();
    dateTimeFormat_ = value;
  }

  private static void checkNeutral(Culture culture) {
    if (culture.isNeutral)
      error("Culture '" ~ culture.name ~ "' is a neutral culture. It cannot be used in formatting and therefore cannot be set as the current culture.");
  }

  private void checkReadOnly() {
    if (isReadOnly_)
      error("Instance is read-only.");
  }

  private static Calendar getCalendarInstance(int calendarType, bool readOnly=false) {
    switch (calendarType) {
      case Calendar.JAPAN:
        return new Japanese();
      case Calendar.TAIWAN:
        return new Taiwan();
      case Calendar.KOREA:
        return new Korean();
      case Calendar.HIJRI:
        return new Hijri();
      case Calendar.THAI:
        return new ThaiBuddhist();
      case Calendar.HEBREW:
        return new Hebrew;
      case Calendar.GREGORIAN_US:
      case Calendar.GREGORIAN_ME_FRENCH:
      case Calendar.GREGORIAN_ARABIC:
      case Calendar.GREGORIAN_XLIT_ENGLISH:
      case Calendar.GREGORIAN_XLIT_FRENCH:
        return new Gregorian(cast(Gregorian.Type) calendarType);
      default:
        break;
    }
    return new Gregorian();
  }

}

/**
 * $(ANCHOR _Region)
 * Provides information about a region.
 * Remarks: Region does not represent user preferences. It does not depend on the user's language or culture.
 * Examples:
 * The following example displays some of the properties of the Region class:
 * ---
 * import tango.io.Print, tango.text.locale.Common;
 *
 * void main() {
 *   Region region = new Region("en-GB");
 *   Println("name:              %s", region.name);
 *   Println("englishName:       %s", region.englishName);
 *   Println("isMetric:          %s", region.isMetric);
 *   Println("currencySymbol:    %s", region.currencySymbol);
 *   Println("isoCurrencySymbol: %s", region.isoCurrencySymbol);
 * }
 *
 * // Produces the following output.
 * // name: