icuSources/i18n/unicode/tznames.h

   1 /*
   2 *******************************************************************************
   3 * Copyright (C) 2011-2015, International Business Machines Corporation and
   4 * others. All Rights Reserved.
   5 *******************************************************************************
   6 */
   7 #ifndef __TZNAMES_H
   8 #define __TZNAMES_H
   9
  10 /**
  11  * \file
  12  * \brief C++ API: TimeZoneNames
  13  */
  14 #include "unicode/utypes.h"
  15
  16 #if !UCONFIG_NO_FORMATTING
  17
  18 #include "unicode/uloc.h"
  19 #include "unicode/unistr.h"
  20
  21 U_CDECL_BEGIN
  22
  23 /**
  24  * Constants for time zone display name types.
  25  * @stable ICU 50
  26  */
  27 typedef enum UTimeZoneNameType {
  28     /**
  29      * Unknown display name type.
  30      * @stable ICU 50
  31      */
  32     UTZNM_UNKNOWN           = 0x00,
  33     /**
  34      * Long display name, such as "Eastern Time".
  35      * @stable ICU 50
  36      */
  37     UTZNM_LONG_GENERIC      = 0x01,
  38     /**
  39      * Long display name for standard time, such as "Eastern Standard Time".
  40      * @stable ICU 50
  41      */
  42     UTZNM_LONG_STANDARD     = 0x02,
  43     /**
  44      * Long display name for daylight saving time, such as "Eastern Daylight Time".
  45      * @stable ICU 50
  46      */
  47     UTZNM_LONG_DAYLIGHT     = 0x04,
  48     /**
  49      * Short display name, such as "ET".
  50      * @stable ICU 50
  51      */
  52     UTZNM_SHORT_GENERIC     = 0x08,
  53     /**
  54      * Short display name for standard time, such as "EST".
  55      * @stable ICU 50
  56      */
  57     UTZNM_SHORT_STANDARD    = 0x10,
  58     /**
  59      * Short display name for daylight saving time, such as "EDT".
  60      * @stable ICU 50
  61      */
  62     UTZNM_SHORT_DAYLIGHT    = 0x20,
  63     /**
  64      * Exemplar location name, such as "Los Angeles".
  65      * @stable ICU 51
  66      */
  67     UTZNM_EXEMPLAR_LOCATION = 0x40
  68 } UTimeZoneNameType;
  69
  70 U_CDECL_END
  71
  72 U_NAMESPACE_BEGIN
  73
  74 class UVector;
  75 struct MatchInfo;
  76
  77 /**
  78  * <code>TimeZoneNames</code> is an abstract class representing the time zone display name data model defined
  79  * by <a href="http://www.unicode.org/reports/tr35/">UTS#35 Unicode Locale Data Markup Language (LDML)</a>.
  80  * The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared
  81  * by multiple time zones. Also a time zone may have multiple meta zone historic mappings.
  82  * <p>
  83  * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time".
  84  * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some
  85  * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make
  86  * much sense for most of people.
  87  * <p>
  88  * In <a href="http://cldr.unicode.org/">CLDR</a> (which uses LDML for representing locale data), the display name
  89  * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern".
  90  * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in
  91  * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern".
  92  * <p>
  93  * Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox"
  94  * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone
  95  * to meta zones mapping data are stored by date range.
  96  *
  97  * <p><b>Note:</b>
  98  * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper
  99  * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone
 100  * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See
 101  * {@link TimeZone#getCanonicalID(const UnicodeString& id, UnicodeString& canonicalID, UErrorCode& status)} about ICU
 102  * canonical time zone IDs.
 103  *
 104  * <p>
 105  * In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may
 106  * have a specific name that is not shared with other time zones.
 107  *
 108  * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also
 109  * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only
 110  * used for "Europe/London".
 111  *
 112  * <p>
 113  * {@link #getTimeZoneDisplayName} is designed for accessing a name only used by a single time zone.
 114  * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation
 115  * may provide time zone names only through {@link #getTimeZoneDisplayName}, or only through {@link #getMetaZoneDisplayName},
 116  * or both.
 117  *
 118  * <p>
 119  * The default <code>TimeZoneNames</code> implementation returned by {@link #createInstance}
 120  * uses the locale data imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone
 121  * IDs are shared by all locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs},
 122  * {@link #getMetaZoneID}, and {@link #getReferenceZoneID} won't be changed no matter
 123  * what locale is used for getting an instance of <code>TimeZoneNames</code>.
 124  *
 125  * @stable ICU 50
 126  */
 127 class U_I18N_API TimeZoneNames : public UObject {
 128 public:
 129     /**
 130      * Destructor.
 131      * @stable ICU 50
 132      */
 133     virtual ~TimeZoneNames();
 134
 135     /**
 136      * Return true if the given TimeZoneNames objects are emantically equal.
 137      * @param other the object to be compared with.
 138      * @return Return TRUE if the given Format objects are semantically equal.
 139      * @stable ICU 50
 140      */
 141     virtual UBool operator==(const TimeZoneNames& other) const = 0;
 142
 143     /**
 144      * Return true if the given TimeZoneNames objects are not semantically
 145      * equal.
 146      * @param other the object to be compared with.
 147      * @return Return TRUE if the given Format objects are not semantically equal.
 148      * @stable ICU 50
 149      */
 150     UBool operator!=(const TimeZoneNames& other) const { return !operator==(other); }
 151
 152     /**
 153      * Clone this object polymorphically.  The caller is responsible
 154      * for deleting the result when done.
 155      * @return A copy of the object
 156      * @stable ICU 50
 157      */
 158     virtual TimeZoneNames* clone() const = 0;
 159
 160     /**
 161      * Returns an instance of <code>TimeZoneNames</code> for the specified locale.
 162      *
 163      * @param locale The locale.
 164      * @param status Receives the status.
 165      * @return An instance of <code>TimeZoneNames</code>
 166      * @stable ICU 50
 167      */
 168     static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
 169
 170     /**
 171      * Returns an instance of <code>TimeZoneNames</code> containing only short specific
 172      * zone names (SHORT_STANDARD and SHORT_DAYLIGHT),
 173      * compatible with the IANA tz database's zone abbreviations (not localized).
 174      * <br>
 175      * Note: The input locale is used for resolving ambiguous names (e.g. "IST" is parsed
 176      * as Israel Standard Time for Israel, while it is parsed as India Standard Time for
 177      * all other regions). The zone names returned by this instance are not localized.
 178      * @stable ICU 54
 179      */
 180      static TimeZoneNames* U_EXPORT2 createTZDBInstance(const Locale& locale, UErrorCode& status);
 181
 182     /**
 183      * Returns an enumeration of all available meta zone IDs.
 184      * @param status Receives the status.
 185      * @return an enumeration object, owned by the caller.
 186      * @stable ICU 50
 187      */
 188     virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0;
 189
 190     /**
 191      * Returns an enumeration of all available meta zone IDs used by the given time zone.
 192      * @param tzID The canoical tiem zone ID.
 193      * @param status Receives the status.
 194      * @return an enumeration object, owned by the caller.
 195      * @stable ICU 50
 196      */
 197     virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0;
 198
 199     /**
 200      * Returns the meta zone ID for the given canonical time zone ID at the given date.
 201      * @param tzID The canonical time zone ID.
 202      * @param date The date.
 203      * @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
 204      *          corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state
 205      *          is set.
 206      * @return A reference to the result.
 207      * @stable ICU 50
 208      */
 209     virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0;
 210
 211     /**
 212      * Returns the reference zone ID for the given meta zone ID for the region.
 213      *
 214      * Note: Each meta zone must have a reference zone associated with a special region "001" (world).
 215      * Some meta zones may have region specific reference zone IDs other than the special region
 216      * "001". When a meta zone does not have any region specific reference zone IDs, this method
 217      * return the reference zone ID for the special region "001" (world).
 218      *
 219      * @param mzID The meta zone ID.
 220      * @param region The region.
 221      * @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the
 222      *          region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state
 223      *          is set.
 224      * @return A reference to the result.
 225      * @stable ICU 50
 226      */
 227     virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0;
 228
 229     /**
 230      * Returns the display name of the meta zone.
 231      * @param mzID The meta zone ID.
 232      * @param type The display name type. See {@link #UTimeZoneNameType}.
 233      * @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given
 234      *         meta zone with the specified type or the implementation does not provide any display names associated
 235      *         with meta zones, "bogus" state is set.
 236      * @return A reference to the result.
 237      * @stable ICU 50
 238      */
 239     virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
 240
 241     /**
 242      * Returns the display name of the time zone. Unlike {@link #getDisplayName},
 243      * this method does not get a name from a meta zone used by the time zone.
 244      * @param tzID The canonical time zone ID.
 245      * @param type The display name type. See {@link #UTimeZoneNameType}.
 246      * @param name Receives the display name for the time zone. When this object does not have a localized display name for the given
 247      *         time zone with the specified type, "bogus" state is set.
 248      * @return A reference to the result.
 249      * @stable ICU 50
 250      */
 251     virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
 252
 253     /**
 254      * Returns the exemplar location name for the given time zone. When this object does not have a localized location
 255      * name, the default implementation may still returns a programmatically generated name with the logic described
 256      * below.
 257      * <ol>
 258      * <li>Check if the ID contains "/". If not, return null.
 259      * <li>Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null.
 260      * <li>Extract a substring after the last occurrence of "/".
 261      * <li>Replace "_" with " ".
 262      * </ol>
 263      * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the
 264      * localized location name.
 265      *
 266      * @param tzID The canonical time zone ID
 267      * @param name Receives the exemplar location name for the given time zone, or "bogus" state is set when a localized
 268      *          location name is not available and the fallback logic described above cannot extract location from the ID.
 269      * @return A reference to the result.
 270      * @stable ICU 50
 271      */
 272     virtual UnicodeString& getExemplarLocationName(const UnicodeString& tzID, UnicodeString& name) const;
 273
 274     /**
 275      * Returns the display name of the time zone at the given date.
 276      * <p>
 277      * <b>Note:</b> This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the
 278      * result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the
 279      * time zone, then calls {@link #getMetaZoneDisplayName}.
 280      *
 281      * @param tzID The canonical time zone ID.
 282      * @param type The display name type. See {@link #UTimeZoneNameType}.
 283      * @param date The date.
 284      * @param name Receives the display name for the time zone at the given date. When this object does not have a localized display
 285      *          name for the time zone with the specified type and date, "bogus" state is set.
 286      * @return A reference to the result.
 287      * @stable ICU 50
 288      */
 289     virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const;
 290
 291     /**
 292      * <code>MatchInfoCollection</code> represents a collection of time zone name matches used by
 293      * {@link TimeZoneNames#find}.
 294      * @internal
 295      */
 296     class U_I18N_API MatchInfoCollection : public UMemory {
 297     public:
 298         /**
 299          * Constructor.
 300          * @internal
 301          */
 302         MatchInfoCollection();
 303         /**
 304          * Destructor.
 305          * @internal
 306          */
 307         virtual ~MatchInfoCollection();
 308
 309 #ifndef U_HIDE_INTERNAL_API
 310         /**
 311          * Adds a zone match.
 312          * @param nameType The name type.
 313          * @param matchLength The match length.
 314          * @param tzID The time zone ID.
 315          * @param status Receives the status
 316          * @internal
 317          */
 318         void addZone(UTimeZoneNameType nameType, int32_t matchLength,
 319             const UnicodeString& tzID, UErrorCode& status);
 320
 321         /**
 322          * Adds a meata zone match.
 323          * @param nameType The name type.
 324          * @param matchLength The match length.
 325          * @param mzID The metazone ID.
 326          * @param status Receives the status
 327          * @internal
 328          */
 329         void addMetaZone(UTimeZoneNameType nameType, int32_t matchLength,
 330             const UnicodeString& mzID, UErrorCode& status);
 331
 332         /**
 333          * Returns the number of entries available in this object.
 334          * @return The number of entries.
 335          * @internal
 336          */
 337         int32_t size() const;
 338
 339         /**
 340          * Returns the time zone name type of a match at the specified index.
 341          * @param idx The index
 342          * @return The time zone name type. If the specified idx is out of range,
 343          *      it returns UTZNM_UNKNOWN.
 344          * @see UTimeZoneNameType
 345          * @internal
 346          */
 347         UTimeZoneNameType getNameTypeAt(int32_t idx) const;
 348
 349         /**
 350          * Returns the match length of a match at the specified index.
 351          * @param idx The index
 352          * @return The match length. If the specified idx is out of range,
 353          *      it returns 0.
 354          * @internal
 355          */
 356         int32_t getMatchLengthAt(int32_t idx) const;
 357
 358         /**
 359          * Gets the zone ID of a match at the specified index.
 360          * @param idx The index
 361          * @param tzID Receives the zone ID.
 362          * @return TRUE if the zone ID was set to tzID.
 363          * @internal
 364          */
 365         UBool getTimeZoneIDAt(int32_t idx, UnicodeString& tzID) const;
 366
 367         /**
 368          * Gets the metazone ID of a match at the specified index.
 369          * @param idx The index
 370          * @param mzID Receives the metazone ID
 371          * @return TRUE if the meta zone ID was set to mzID.
 372          * @internal
 373          */
 374         UBool getMetaZoneIDAt(int32_t idx, UnicodeString& mzID) const;
 375 #endif  /* U_HIDE_INTERNAL_API */
 376
 377     private:
 378         UVector* fMatches;  // vector of MatchEntry
 379
 380         UVector* matches(UErrorCode& status);
 381     };
 382
 383     /**
 384      * Finds time zone name prefix matches for the input text at the
 385      * given offset and returns a collection of the matches.
 386      * @param text The text.
 387      * @param start The starting offset within the text.
 388      * @param types The set of name types represented by bitwise flags of UTimeZoneNameType enums,
 389      *              or UTZNM_UNKNOWN for all name types.
 390      * @param status Receives the status.
 391      * @return A collection of matches (owned by the caller), or NULL if no matches are found.
 392      * @see UTimeZoneNameType
 393      * @see MatchInfoCollection
 394      * @internal
 395      */
 396     virtual MatchInfoCollection* find(const UnicodeString& text, int32_t start, uint32_t types, UErrorCode& status) const = 0;
 397 };
 398
 399 U_NAMESPACE_END
 400
 401 #endif
 402 #endif