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