icuSources/i18n/unicode/tznames.h

   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  * @internal ICU 49 technology preview
  27  */
  28 typedef enum UTimeZoneNameType {
  29     /**
  30      * Unknown display name type.
  31      * @internal ICU 49 technology preview
  32      */
  33     UTZNM_UNKNOWN           = 0x00,
  34     /**
  35      * Long display name, such as "Eastern Time".
  36      * @internal ICU 49 technology preview
  37      */
  38     UTZNM_LONG_GENERIC      = 0x01,
  39     /**
  40      * Long display name for standard time, such as "Eastern Standard Time".
  41      * @internal ICU 49 technology preview
  42      */
  43     UTZNM_LONG_STANDARD     = 0x02,
  44     /**
  45      * Long display name for daylight saving time, such as "Eastern Daylight Time".
  46      * @internal ICU 49 technology preview
  47      */
  48     UTZNM_LONG_DAYLIGHT     = 0x04,
  49     /**
  50      * Short display name, such as "ET".
  51      * @internal ICU 49 technology preview
  52      */
  53     UTZNM_SHORT_GENERIC     = 0x08,
  54     /**
  55      * Short display name for standard time, such as "EST".
  56      * @internal ICU 49 technology preview
  57      */
  58     UTZNM_SHORT_STANDARD    = 0x10,
  59     /**
  60      * Short display name for daylight saving time, such as "EDT".
  61      * @internal ICU 49 technology preview
  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  * @internal ICU 49 technology preview
 115  */
 116 class U_I18N_API TimeZoneNames : public UObject {
 117 public:
 118     /**
 119      * Destructor.
 120      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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      * @internal ICU 49 technology preview
 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 ICU 49 technology preview
 266      */
 267     class U_I18N_API MatchInfoCollection : public UMemory {
 268     public:
 269         /**
 270          * Constructor.
 271          * @internal ICU 49 technology preview
 272          */
 273         MatchInfoCollection();
 274         /**
 275          * Destructor.
 276          * @internal ICU 49 technology preview
 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 ICU 49 technology preview
 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 ICU 49 technology preview
 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 ICU 49 technology preview
 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 ICU 49 technology preview
 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          * @param status Receives the status
 323          * @return The match length. If the specified idx is out of range,
 324          *      it returns 0.
 325          * @internal ICU 49 technology preview
 326          */
 327         int32_t getMatchLengthAt(int32_t idx) const;
 328
 329         /**
 330          * Gets the zone ID of a match at the specified index.
 331          * @param idx The index
 332          * @param tzID Receives the zone ID.
 333          * @return TRUE if the zone ID was set to tzID.
 334          * @internal ICU 49 technology preview
 335          */
 336         UBool getTimeZoneIDAt(int32_t idx, UnicodeString& tzID) const;
 337
 338         /**
 339          * Gets the metazone ID of a match at the specified index.
 340          * @param idx The index
 341          * @param mzID Receives the metazone ID
 342          * @param status Receives the status.
 343          * @return TRUE if the meta zone ID was set to mzID.
 344          * @internal ICU 49 technology preview
 345          */
 346         UBool getMetaZoneIDAt(int32_t idx, UnicodeString& mzID) const;
 347
 348     private:
 349         UVector* fMatches;  // vector of MatchEntry
 350
 351         UVector* matches(UErrorCode& status);
 352     };
 353
 354     /**
 355      * Finds time zone name prefix matches for the input text at the
 356      * given offset and returns a collection of the matches.
 357      * @param text The text.
 358      * @param start The starting offset within the text.
 359      * @param types The set of name types represented by bitwise flags of UTimeZoneNameType enums,
 360      *              or UTZNM_UNKNOWN for all name types.
 361      * @param status Receives the status.
 362      * @return A collection of matches (owned by the caller), or NULL if no matches are found.
 363      * @see UTimeZoneNameType
 364      * @see MatchInfoCollection
 365      * @internal ICU 49 technology preview
 366      */
 367     virtual MatchInfoCollection* find(const UnicodeString& text, int32_t start, uint32_t types, UErrorCode& status) const = 0;
 368
 369 private:
 370     // No ICU "poor man's RTTI" for this class nor its subclasses.
 371     virtual UClassID getDynamicClassID() const;
 372 };
 373
 374 U_NAMESPACE_END
 375
 376 #endif  /* U_HIDE_INTERNAL_API */
 377 #endif
 378 #endif