michael@0: /* michael@0: ******************************************************************************* michael@0: * Copyright (C) 2011-2013, International Business Machines Corporation and * michael@0: * others. All Rights Reserved. * michael@0: ******************************************************************************* michael@0: */ michael@0: #ifndef __TZNAMES_H michael@0: #define __TZNAMES_H michael@0: michael@0: /** michael@0: * \file michael@0: * \brief C++ API: TimeZoneNames michael@0: */ michael@0: #include "unicode/utypes.h" michael@0: michael@0: #if !UCONFIG_NO_FORMATTING michael@0: michael@0: #include "unicode/uloc.h" michael@0: #include "unicode/unistr.h" michael@0: michael@0: U_CDECL_BEGIN michael@0: michael@0: /** michael@0: * Constants for time zone display name types. michael@0: * @stable ICU 50 michael@0: */ michael@0: typedef enum UTimeZoneNameType { michael@0: /** michael@0: * Unknown display name type. michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZNM_UNKNOWN = 0x00, michael@0: /** michael@0: * Long display name, such as "Eastern Time". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZNM_LONG_GENERIC = 0x01, michael@0: /** michael@0: * Long display name for standard time, such as "Eastern Standard Time". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZNM_LONG_STANDARD = 0x02, michael@0: /** michael@0: * Long display name for daylight saving time, such as "Eastern Daylight Time". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZNM_LONG_DAYLIGHT = 0x04, michael@0: /** michael@0: * Short display name, such as "ET". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZNM_SHORT_GENERIC = 0x08, michael@0: /** michael@0: * Short display name for standard time, such as "EST". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZNM_SHORT_STANDARD = 0x10, michael@0: /** michael@0: * Short display name for daylight saving time, such as "EDT". michael@0: * @stable ICU 50 michael@0: */ michael@0: UTZNM_SHORT_DAYLIGHT = 0x20, michael@0: #ifndef U_HIDE_DRAFT_API michael@0: /** michael@0: * Exemplar location name, such as "Los Angeles". michael@0: * @draft ICU 51 michael@0: */ michael@0: UTZNM_EXEMPLAR_LOCATION = 0x40 michael@0: #endif /* U_HIDE_DRAFT_API */ michael@0: } UTimeZoneNameType; michael@0: michael@0: U_CDECL_END michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: class UVector; michael@0: struct MatchInfo; michael@0: michael@0: /** michael@0: * TimeZoneNames is an abstract class representing the time zone display name data model defined michael@0: * by UTS#35 Unicode Locale Data Markup Language (LDML). michael@0: * The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared michael@0: * by multiple time zones. Also a time zone may have multiple meta zone historic mappings. michael@0: *

michael@0: * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time". michael@0: * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some michael@0: * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make michael@0: * much sense for most of people. michael@0: *

michael@0: * In CLDR (which uses LDML for representing locale data), the display name michael@0: * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern". michael@0: * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in michael@0: * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern". michael@0: *

michael@0: * Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox" michael@0: * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone michael@0: * to meta zones mapping data are stored by date range. michael@0: * michael@0: *

Note: michael@0: * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper michael@0: * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone michael@0: * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See michael@0: * {@link TimeZone#getCanonicalID(const UnicodeString& id, UnicodeString& canonicalID, UErrorCode& status)} about ICU michael@0: * canonical time zone IDs. michael@0: * michael@0: *

michael@0: * In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may michael@0: * have a specific name that is not shared with other time zones. michael@0: * michael@0: * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also michael@0: * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only michael@0: * used for "Europe/London". michael@0: * michael@0: *

michael@0: * {@link #getTimeZoneDisplayName} is designed for accessing a name only used by a single time zone. michael@0: * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation michael@0: * may provide time zone names only through {@link #getTimeZoneDisplayName}, or only through {@link #getMetaZoneDisplayName}, michael@0: * or both. michael@0: * michael@0: *

michael@0: * The default TimeZoneNames implementation returned by {@link #createInstance} michael@0: * uses the locale data imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone michael@0: * IDs are shared by all locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs}, michael@0: * {@link #getMetaZoneID}, and {@link #getReferenceZoneID} won't be changed no matter michael@0: * what locale is used for getting an instance of TimeZoneNames. michael@0: * michael@0: * @stable ICU 50 michael@0: */ michael@0: class U_I18N_API TimeZoneNames : public UObject { michael@0: public: michael@0: /** michael@0: * Destructor. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual ~TimeZoneNames(); michael@0: michael@0: /** michael@0: * Return true if the given TimeZoneNames objects are emantically equal. michael@0: * @param other the object to be compared with. michael@0: * @return Return TRUE if the given Format objects are semantically equal. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UBool operator==(const TimeZoneNames& other) const = 0; michael@0: michael@0: /** michael@0: * Return true if the given TimeZoneNames objects are not semantically michael@0: * equal. michael@0: * @param other the object to be compared with. michael@0: * @return Return TRUE if the given Format objects are not semantically equal. michael@0: * @stable ICU 50 michael@0: */ michael@0: UBool operator!=(const TimeZoneNames& other) const { return !operator==(other); } michael@0: michael@0: /** michael@0: * Clone this object polymorphically. The caller is responsible michael@0: * for deleting the result when done. michael@0: * @return A copy of the object michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual TimeZoneNames* clone() const = 0; michael@0: michael@0: /** michael@0: * Returns an instance of TimeZoneDisplayNames for the specified locale. michael@0: * michael@0: * @param locale The locale. michael@0: * @param status Recevies the status. michael@0: * @return An instance of TimeZoneDisplayNames michael@0: * @stable ICU 50 michael@0: */ michael@0: static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status); michael@0: michael@0: /** michael@0: * Returns an enumeration of all available meta zone IDs. michael@0: * @param status Recevies the status. michael@0: * @return an enumeration object, owned by the caller. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0; michael@0: michael@0: /** michael@0: * Returns an enumeration of all available meta zone IDs used by the given time zone. michael@0: * @param tzID The canoical tiem zone ID. michael@0: * @param status Recevies the status. michael@0: * @return an enumeration object, owned by the caller. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0; michael@0: michael@0: /** michael@0: * Returns the meta zone ID for the given canonical time zone ID at the given date. michael@0: * @param tzID The canonical time zone ID. michael@0: * @param date The date. michael@0: * @param mzID Receives the meta zone ID for the given time zone ID at the given date. If the time zone does not have a michael@0: * corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state michael@0: * is set. michael@0: * @return A reference to the result. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0; michael@0: michael@0: /** michael@0: * Returns the reference zone ID for the given meta zone ID for the region. michael@0: * michael@0: * Note: Each meta zone must have a reference zone associated with a special region "001" (world). michael@0: * Some meta zones may have region specific reference zone IDs other than the special region michael@0: * "001". When a meta zone does not have any region specific reference zone IDs, this method michael@0: * return the reference zone ID for the special region "001" (world). michael@0: * michael@0: * @param mzID The meta zone ID. michael@0: * @param region The region. michael@0: * @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the michael@0: * region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state michael@0: * is set. michael@0: * @return A reference to the result. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0; michael@0: michael@0: /** michael@0: * Returns the display name of the meta zone. michael@0: * @param mzID The meta zone ID. michael@0: * @param type The display name type. See {@link #UTimeZoneNameType}. michael@0: * @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given michael@0: * meta zone with the specified type or the implementation does not provide any display names associated michael@0: * with meta zones, "bogus" state is set. michael@0: * @return A reference to the result. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0; michael@0: michael@0: /** michael@0: * Returns the display name of the time zone. Unlike {@link #getDisplayName}, michael@0: * this method does not get a name from a meta zone used by the time zone. michael@0: * @param tzID The canonical time zone ID. michael@0: * @param type The display name type. See {@link #UTimeZoneNameType}. michael@0: * @param name Receives the display name for the time zone. When this object does not have a localized display name for the given michael@0: * time zone with the specified type, "bogus" state is set. michael@0: * @return A reference to the result. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0; michael@0: michael@0: /** michael@0: * Returns the exemplar location name for the given time zone. When this object does not have a localized location michael@0: * name, the default implementation may still returns a programmatically generated name with the logic described michael@0: * below. michael@0: *

    michael@0: *
  1. Check if the ID contains "/". If not, return null. michael@0: *
  2. Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null. michael@0: *
  3. Extract a substring after the last occurrence of "/". michael@0: *
  4. Replace "_" with " ". michael@0: *
michael@0: * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the michael@0: * localized location name. michael@0: * michael@0: * @param tzID The canonical time zone ID michael@0: * @param name Receives the exemplar location name for the given time zone, or "bogus" state is set when a localized michael@0: * location name is not available and the fallback logic described above cannot extract location from the ID. michael@0: * @return A reference to the result. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UnicodeString& getExemplarLocationName(const UnicodeString& tzID, UnicodeString& name) const; michael@0: michael@0: /** michael@0: * Returns the display name of the time zone at the given date. michael@0: *

michael@0: * Note: This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the michael@0: * result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the michael@0: * time zone, then calls {@link #getMetaZoneDisplayName}. michael@0: * michael@0: * @param tzID The canonical time zone ID. michael@0: * @param type The display name type. See {@link #UTimeZoneNameType}. michael@0: * @param date The date. michael@0: * @param name Receives the display name for the time zone at the given date. When this object does not have a localized display michael@0: * name for the time zone with the specified type and date, "bogus" state is set. michael@0: * @return A reference to the result. michael@0: * @stable ICU 50 michael@0: */ michael@0: virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const; michael@0: michael@0: /** michael@0: * MatchInfoCollection represents a collection of time zone name matches used by michael@0: * {@link TimeZoneNames#find}. michael@0: * @internal michael@0: */ michael@0: class U_I18N_API MatchInfoCollection : public UMemory { michael@0: public: michael@0: /** michael@0: * Constructor. michael@0: * @internal michael@0: */ michael@0: MatchInfoCollection(); michael@0: /** michael@0: * Destructor. michael@0: * @internal michael@0: */ michael@0: virtual ~MatchInfoCollection(); michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Adds a zone match. michael@0: * @param nameType The name type. michael@0: * @param matchLength The match length. michael@0: * @param tzID The time zone ID. michael@0: * @param status Receives the status michael@0: * @internal michael@0: */ michael@0: void addZone(UTimeZoneNameType nameType, int32_t matchLength, michael@0: const UnicodeString& tzID, UErrorCode& status); michael@0: michael@0: /** michael@0: * Adds a meata zone match. michael@0: * @param nameType The name type. michael@0: * @param matchLength The match length. michael@0: * @param mzID The metazone ID. michael@0: * @param status Receives the status michael@0: * @internal michael@0: */ michael@0: void addMetaZone(UTimeZoneNameType nameType, int32_t matchLength, michael@0: const UnicodeString& mzID, UErrorCode& status); michael@0: michael@0: /** michael@0: * Returns the number of entries available in this object. michael@0: * @return The number of entries. michael@0: * @internal michael@0: */ michael@0: int32_t size() const; michael@0: michael@0: /** michael@0: * Returns the time zone name type of a match at the specified index. michael@0: * @param idx The index michael@0: * @return The time zone name type. If the specified idx is out of range, michael@0: * it returns UTZNM_UNKNOWN. michael@0: * @see UTimeZoneNameType michael@0: * @internal michael@0: */ michael@0: UTimeZoneNameType getNameTypeAt(int32_t idx) const; michael@0: michael@0: /** michael@0: * Returns the match length of a match at the specified index. michael@0: * @param idx The index michael@0: * @return The match length. If the specified idx is out of range, michael@0: * it returns 0. michael@0: * @internal michael@0: */ michael@0: int32_t getMatchLengthAt(int32_t idx) const; michael@0: michael@0: /** michael@0: * Gets the zone ID of a match at the specified index. michael@0: * @param idx The index michael@0: * @param tzID Receives the zone ID. michael@0: * @return TRUE if the zone ID was set to tzID. michael@0: * @internal michael@0: */ michael@0: UBool getTimeZoneIDAt(int32_t idx, UnicodeString& tzID) const; michael@0: michael@0: /** michael@0: * Gets the metazone ID of a match at the specified index. michael@0: * @param idx The index michael@0: * @param mzID Receives the metazone ID michael@0: * @return TRUE if the meta zone ID was set to mzID. michael@0: * @internal michael@0: */ michael@0: UBool getMetaZoneIDAt(int32_t idx, UnicodeString& mzID) const; michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: private: michael@0: UVector* fMatches; // vector of MatchEntry michael@0: michael@0: UVector* matches(UErrorCode& status); michael@0: }; michael@0: michael@0: /** michael@0: * Finds time zone name prefix matches for the input text at the michael@0: * given offset and returns a collection of the matches. michael@0: * @param text The text. michael@0: * @param start The starting offset within the text. michael@0: * @param types The set of name types represented by bitwise flags of UTimeZoneNameType enums, michael@0: * or UTZNM_UNKNOWN for all name types. michael@0: * @param status Receives the status. michael@0: * @return A collection of matches (owned by the caller), or NULL if no matches are found. michael@0: * @see UTimeZoneNameType michael@0: * @see MatchInfoCollection michael@0: * @internal michael@0: */ michael@0: virtual MatchInfoCollection* find(const UnicodeString& text, int32_t start, uint32_t types, UErrorCode& status) const = 0; michael@0: }; michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif michael@0: #endif