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