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 403
