icuSources/i18n/unicode/tznames.h

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