include/unicode/tznames.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *******************************************************************************
0005 * Copyright (C) 2011-2016, International Business Machines Corporation and
0006 * others. All Rights Reserved.
0007 *******************************************************************************
0008 */
0009 #ifndef __TZNAMES_H
0010 #define __TZNAMES_H
0011
0012 /**
0013  * \file
0014  * \brief C++ API: TimeZoneNames
0015  */
0016 #include "unicode/utypes.h"
0017
0018 #if U_SHOW_CPLUSPLUS_API
0019
0020 #if !UCONFIG_NO_FORMATTING
0021
0022 #include "unicode/uloc.h"
0023 #include "unicode/unistr.h"
0024
0025 U_CDECL_BEGIN
0026
0027 /**
0028  * Constants for time zone display name types.
0029  * @stable ICU 50
0030  */
0031 typedef enum UTimeZoneNameType {
0032     /**
0033      * Unknown display name type.
0034      * @stable ICU 50
0035      */
0036     UTZNM_UNKNOWN           = 0x00,
0037     /**
0038      * Long display name, such as "Eastern Time".
0039      * @stable ICU 50
0040      */
0041     UTZNM_LONG_GENERIC      = 0x01,
0042     /**
0043      * Long display name for standard time, such as "Eastern Standard Time".
0044      * @stable ICU 50
0045      */
0046     UTZNM_LONG_STANDARD     = 0x02,
0047     /**
0048      * Long display name for daylight saving time, such as "Eastern Daylight Time".
0049      * @stable ICU 50
0050      */
0051     UTZNM_LONG_DAYLIGHT     = 0x04,
0052     /**
0053      * Short display name, such as "ET".
0054      * @stable ICU 50
0055      */
0056     UTZNM_SHORT_GENERIC     = 0x08,
0057     /**
0058      * Short display name for standard time, such as "EST".
0059      * @stable ICU 50
0060      */
0061     UTZNM_SHORT_STANDARD    = 0x10,
0062     /**
0063      * Short display name for daylight saving time, such as "EDT".
0064      * @stable ICU 50
0065      */
0066     UTZNM_SHORT_DAYLIGHT    = 0x20,
0067     /**
0068      * Exemplar location name, such as "Los Angeles".
0069      * @stable ICU 51
0070      */
0071     UTZNM_EXEMPLAR_LOCATION = 0x40
0072 } UTimeZoneNameType;
0073
0074 U_CDECL_END
0075
0076 U_NAMESPACE_BEGIN
0077
0078 class UVector;
0079 struct MatchInfo;
0080
0081 /**
0082  * <code>TimeZoneNames</code> is an abstract class representing the time zone display name data model defined
0083  * by <a href="http://www.unicode.org/reports/tr35/">UTS#35 Unicode Locale Data Markup Language (LDML)</a>.
0084  * The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared
0085  * by multiple time zones. Also a time zone may have multiple meta zone historic mappings.
0086  * <p>
0087  * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time".
0088  * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some
0089  * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make
0090  * much sense for most of people.
0091  * <p>
0092  * In <a href="http://cldr.unicode.org/">CLDR</a> (which uses LDML for representing locale data), the display name
0093  * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern".
0094  * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in
0095  * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern".
0096  * <p>
0097  * Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox"
0098  * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone
0099  * to meta zones mapping data are stored by date range.
0100  *
0101  * <p><b>Note:</b>
0102  * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper
0103  * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone
0104  * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See
0105  * {@link TimeZone#getCanonicalID(const UnicodeString& id, UnicodeString& canonicalID, UErrorCode& status)} about ICU
0106  * canonical time zone IDs.
0107  *
0108  * <p>
0109  * In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may
0110  * have a specific name that is not shared with other time zones.
0111  *
0112  * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also
0113  * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only
0114  * used for "Europe/London".
0115  *
0116  * <p>
0117  * {@link #getTimeZoneDisplayName} is designed for accessing a name only used by a single time zone.
0118  * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation
0119  * may provide time zone names only through {@link #getTimeZoneDisplayName}, or only through {@link #getMetaZoneDisplayName},
0120  * or both.
0121  *
0122  * <p>
0123  * The default <code>TimeZoneNames</code> implementation returned by {@link #createInstance}
0124  * uses the locale data imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone
0125  * IDs are shared by all locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs},
0126  * {@link #getMetaZoneID}, and {@link #getReferenceZoneID} won't be changed no matter
0127  * what locale is used for getting an instance of <code>TimeZoneNames</code>.
0128  *
0129  * @stable ICU 50
0130  */
0131 class U_I18N_API TimeZoneNames : public UObject {
0132 public:
0133     /**
0134      * Destructor.
0135      * @stable ICU 50
0136      */
0137     virtual ~TimeZoneNames();
0138
0139     /**
0140      * Return true if the given TimeZoneNames objects are semantically equal.
0141      * @param other the object to be compared with.
0142      * @return Return true if the given Format objects are semantically equal.
0143      * @stable ICU 50
0144      */
0145     virtual bool operator==(const TimeZoneNames& other) const = 0;
0146
0147     /**
0148      * Return true if the given TimeZoneNames objects are not semantically
0149      * equal.
0150      * @param other the object to be compared with.
0151      * @return Return true if the given Format objects are not semantically equal.
0152      * @stable ICU 50
0153      */
0154     bool operator!=(const TimeZoneNames& other) const { return !operator==(other); }
0155
0156     /**
0157      * Clone this object polymorphically.  The caller is responsible
0158      * for deleting the result when done.
0159      * @return A copy of the object
0160      * @stable ICU 50
0161      */
0162     virtual TimeZoneNames* clone() const = 0;
0163
0164     /**
0165      * Returns an instance of <code>TimeZoneNames</code> for the specified locale.
0166      *
0167      * @param locale The locale.
0168      * @param status Receives the status.
0169      * @return An instance of <code>TimeZoneNames</code>
0170      * @stable ICU 50
0171      */
0172     static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
0173
0174     /**
0175      * Returns an instance of <code>TimeZoneNames</code> containing only short specific
0176      * zone names (SHORT_STANDARD and SHORT_DAYLIGHT),
0177      * compatible with the IANA tz database's zone abbreviations (not localized).
0178      * <br>
0179      * Note: The input locale is used for resolving ambiguous names (e.g. "IST" is parsed
0180      * as Israel Standard Time for Israel, while it is parsed as India Standard Time for
0181      * all other regions). The zone names returned by this instance are not localized.
0182      * @stable ICU 54
0183      */
0184      static TimeZoneNames* U_EXPORT2 createTZDBInstance(const Locale& locale, UErrorCode& status);
0185
0186     /**
0187      * Returns an enumeration of all available meta zone IDs.
0188      * @param status Receives the status.
0189      * @return an enumeration object, owned by the caller.
0190      * @stable ICU 50
0191      */
0192     virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0;
0193
0194     /**
0195      * Returns an enumeration of all available meta zone IDs used by the given time zone.
0196      * @param tzID The canonical time zone ID.
0197      * @param status Receives the status.
0198      * @return an enumeration object, owned by the caller.
0199      * @stable ICU 50
0200      */
0201     virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0;
0202
0203     /**
0204      * Returns the meta zone ID for the given canonical time zone ID at the given date.
0205      * @param tzID The canonical time zone ID.
0206      * @param date The date.
0207      * @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
0208      *          corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state
0209      *          is set.
0210      * @return A reference to the result.
0211      * @stable ICU 50
0212      */
0213     virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0;
0214
0215     /**
0216      * Returns the reference zone ID for the given meta zone ID for the region.
0217      *
0218      * Note: Each meta zone must have a reference zone associated with a special region "001" (world).
0219      * Some meta zones may have region specific reference zone IDs other than the special region
0220      * "001". When a meta zone does not have any region specific reference zone IDs, this method
0221      * return the reference zone ID for the special region "001" (world).
0222      *
0223      * @param mzID The meta zone ID.
0224      * @param region The region.
0225      * @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the
0226      *          region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state
0227      *          is set.
0228      * @return A reference to the result.
0229      * @stable ICU 50
0230      */
0231     virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0;
0232
0233     /**
0234      * Returns the display name of the meta zone.
0235      * @param mzID The meta zone ID.
0236      * @param type The display name type. See {@link #UTimeZoneNameType}.
0237      * @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given
0238      *         meta zone with the specified type or the implementation does not provide any display names associated
0239      *         with meta zones, "bogus" state is set.
0240      * @return A reference to the result.
0241      * @stable ICU 50
0242      */
0243     virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
0244
0245     /**
0246      * Returns the display name of the time zone. Unlike {@link #getDisplayName},
0247      * this method does not get a name from a meta zone used by the time zone.
0248      * @param tzID The canonical time zone ID.
0249      * @param type The display name type. See {@link #UTimeZoneNameType}.
0250      * @param name Receives the display name for the time zone. When this object does not have a localized display name for the given
0251      *         time zone with the specified type, "bogus" state is set.
0252      * @return A reference to the result.
0253      * @stable ICU 50
0254      */
0255     virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
0256
0257     /**
0258      * Returns the exemplar location name for the given time zone. When this object does not have a localized location
0259      * name, the default implementation may still returns a programmatically generated name with the logic described
0260      * below.
0261      * <ol>
0262      * <li>Check if the ID contains "/". If not, return null.
0263      * <li>Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null.
0264      * <li>Extract a substring after the last occurrence of "/".
0265      * <li>Replace "_" with " ".
0266      * </ol>
0267      * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the
0268      * localized location name.
0269      *
0270      * @param tzID The canonical time zone ID
0271      * @param name Receives the exemplar location name for the given time zone, or "bogus" state is set when a localized
0272      *          location name is not available and the fallback logic described above cannot extract location from the ID.
0273      * @return A reference to the result.
0274      * @stable ICU 50
0275      */
0276     virtual UnicodeString& getExemplarLocationName(const UnicodeString& tzID, UnicodeString& name) const;
0277
0278     /**
0279      * Returns the display name of the time zone at the given date.
0280      * <p>
0281      * <b>Note:</b> This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the
0282      * result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the
0283      * time zone, then calls {@link #getMetaZoneDisplayName}.
0284      *
0285      * @param tzID The canonical time zone ID.
0286      * @param type The display name type. See {@link #UTimeZoneNameType}.
0287      * @param date The date.
0288      * @param name Receives the display name for the time zone at the given date. When this object does not have a localized display
0289      *          name for the time zone with the specified type and date, "bogus" state is set.
0290      * @return A reference to the result.
0291      * @stable ICU 50
0292      */
0293     virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const;
0294
0295     /**
0296      * @internal ICU internal only, for specific users only until proposed publicly.
0297      */
0298     virtual void loadAllDisplayNames(UErrorCode& status);
0299
0300     /**
0301      * @internal ICU internal only, for specific users only until proposed publicly.
0302      */
0303     virtual void getDisplayNames(const UnicodeString& tzID, const UTimeZoneNameType types[], int32_t numTypes, UDate date, UnicodeString dest[], UErrorCode& status) const;
0304
0305     /**
0306      * <code>MatchInfoCollection</code> represents a collection of time zone name matches used by
0307      * {@link TimeZoneNames#find}.
0308      * @internal
0309      */
0310     class U_I18N_API MatchInfoCollection : public UMemory {
0311     public:
0312         /**
0313          * Constructor.
0314          * @internal
0315          */
0316         MatchInfoCollection();
0317         /**
0318          * Destructor.
0319          * @internal
0320          */
0321         virtual ~MatchInfoCollection();
0322
0323 #ifndef U_HIDE_INTERNAL_API
0324         /**
0325          * Adds a zone match.
0326          * @param nameType The name type.
0327          * @param matchLength The match length.
0328          * @param tzID The time zone ID.
0329          * @param status Receives the status
0330          * @internal
0331          */
0332         void addZone(UTimeZoneNameType nameType, int32_t matchLength,
0333             const UnicodeString& tzID, UErrorCode& status);
0334
0335         /**
0336          * Adds a meata zone match.
0337          * @param nameType The name type.
0338          * @param matchLength The match length.
0339          * @param mzID The metazone ID.
0340          * @param status Receives the status
0341          * @internal
0342          */
0343         void addMetaZone(UTimeZoneNameType nameType, int32_t matchLength,
0344             const UnicodeString& mzID, UErrorCode& status);
0345
0346         /**
0347          * Returns the number of entries available in this object.
0348          * @return The number of entries.
0349          * @internal
0350          */
0351         int32_t size() const;
0352
0353         /**
0354          * Returns the time zone name type of a match at the specified index.
0355          * @param idx The index
0356          * @return The time zone name type. If the specified idx is out of range,
0357          *      it returns UTZNM_UNKNOWN.
0358          * @see UTimeZoneNameType
0359          * @internal
0360          */
0361         UTimeZoneNameType getNameTypeAt(int32_t idx) const;
0362
0363         /**
0364          * Returns the match length of a match at the specified index.
0365          * @param idx The index
0366          * @return The match length. If the specified idx is out of range,
0367          *      it returns 0.
0368          * @internal
0369          */
0370         int32_t getMatchLengthAt(int32_t idx) const;
0371
0372         /**
0373          * Gets the zone ID of a match at the specified index.
0374          * @param idx The index
0375          * @param tzID Receives the zone ID.
0376          * @return true if the zone ID was set to tzID.
0377          * @internal
0378          */
0379         UBool getTimeZoneIDAt(int32_t idx, UnicodeString& tzID) const;
0380
0381         /**
0382          * Gets the metazone ID of a match at the specified index.
0383          * @param idx The index
0384          * @param mzID Receives the metazone ID
0385          * @return true if the meta zone ID was set to mzID.
0386          * @internal
0387          */
0388         UBool getMetaZoneIDAt(int32_t idx, UnicodeString& mzID) const;
0389 #endif  /* U_HIDE_INTERNAL_API */
0390
0391     private:
0392         UVector* fMatches;  // vector of MatchEntry
0393
0394         UVector* matches(UErrorCode& status);
0395     };
0396
0397     /**
0398      * Finds time zone name prefix matches for the input text at the
0399      * given offset and returns a collection of the matches.
0400      * @param text The text.
0401      * @param start The starting offset within the text.
0402      * @param types The set of name types represented by bitwise flags of UTimeZoneNameType enums,
0403      *              or UTZNM_UNKNOWN for all name types.
0404      * @param status Receives the status.
0405      * @return A collection of matches (owned by the caller), or nullptr if no matches are found.
0406      * @see UTimeZoneNameType
0407      * @see MatchInfoCollection
0408      * @internal
0409      */
0410     virtual MatchInfoCollection* find(const UnicodeString& text, int32_t start, uint32_t types, UErrorCode& status) const = 0;
0411 };
0412
0413 U_NAMESPACE_END
0414
0415 #endif
0416
0417 #endif /* U_SHOW_CPLUSPLUS_API */
0418
0419 #endif