Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/tznames.h @ 69:33d812a61356

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