tznames.h (17254B)
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 bool 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 bool 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 canonical time 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 nullptr 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