/src/icu/source/i18n/unicode/tznames.h

Source (jump to first uncovered line)
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
* Copyright (C) 2011-2016, International Business Machines Corporation and
* others. All Rights Reserved.
*******************************************************************************
*/
#ifndef __TZNAMES_H
#define __TZNAMES_H

/**
 * \file
 * \brief C++ API: TimeZoneNames
 */
#include "unicode/utypes.h"

#if U_SHOW_CPLUSPLUS_API

#if !UCONFIG_NO_FORMATTING

#include "unicode/uloc.h"
#include "unicode/unistr.h"

U_CDECL_BEGIN

/**
 * Constants for time zone display name types.
 * @stable ICU 50
 */
typedef enum UTimeZoneNameType {
    /**
     * Unknown display name type.
     * @stable ICU 50
     */
    UTZNM_UNKNOWN           = 0x00,
    /**
     * Long display name, such as "Eastern Time".
     * @stable ICU 50
     */
    UTZNM_LONG_GENERIC      = 0x01,
    /**
     * Long display name for standard time, such as "Eastern Standard Time".
     * @stable ICU 50
     */
    UTZNM_LONG_STANDARD     = 0x02,
    /**
     * Long display name for daylight saving time, such as "Eastern Daylight Time".
     * @stable ICU 50
     */
    UTZNM_LONG_DAYLIGHT     = 0x04,
    /**
     * Short display name, such as "ET".
     * @stable ICU 50
     */
    UTZNM_SHORT_GENERIC     = 0x08,
    /**
     * Short display name for standard time, such as "EST".
     * @stable ICU 50
     */
    UTZNM_SHORT_STANDARD    = 0x10,
    /**
     * Short display name for daylight saving time, such as "EDT".
     * @stable ICU 50
     */
    UTZNM_SHORT_DAYLIGHT    = 0x20,
    /**
     * Exemplar location name, such as "Los Angeles".
     * @stable ICU 51
     */
    UTZNM_EXEMPLAR_LOCATION = 0x40
} UTimeZoneNameType;

U_CDECL_END

U_NAMESPACE_BEGIN

class UVector;
struct MatchInfo;

/**
 * <code>TimeZoneNames</code> is an abstract class representing the time zone display name data model defined
 * by <a href="http://www.unicode.org/reports/tr35/">UTS#35 Unicode Locale Data Markup Language (LDML)</a>.
 * The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared
 * by multiple time zones. Also a time zone may have multiple meta zone historic mappings.
 * <p>
 * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time".
 * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some
 * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make
 * much sense for most of people.
 * <p>
 * In <a href="http://cldr.unicode.org/">CLDR</a> (which uses LDML for representing locale data), the display name
 * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern".
 * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in
 * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern".
 * <p>
 * Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox"
 * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone
 * to meta zones mapping data are stored by date range.
 *
 * <p><b>Note:</b>
 * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper
 * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone
 * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See
 * {@link TimeZone#getCanonicalID(const UnicodeString& id, UnicodeString& canonicalID, UErrorCode& status)} about ICU
 * canonical time zone IDs.
 *
 * <p>
 * In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may
 * have a specific name that is not shared with other time zones.
 *
 * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also
 * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only
 * used for "Europe/London".
 *
 * <p>
 * {@link #getTimeZoneDisplayName} is designed for accessing a name only used by a single time zone.
 * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation
 * may provide time zone names only through {@link #getTimeZoneDisplayName}, or only through {@link #getMetaZoneDisplayName},
 * or both.
 *
 * <p>
 * The default <code>TimeZoneNames</code> implementation returned by {@link #createInstance}
 * uses the locale data imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone
 * IDs are shared by all locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs},
 * {@link #getMetaZoneID}, and {@link #getReferenceZoneID} won't be changed no matter
 * what locale is used for getting an instance of <code>TimeZoneNames</code>.
 *
 * @stable ICU 50
 */
class U_I18N_API TimeZoneNames : public UObject {
public:
    /**
     * Destructor.
     * @stable ICU 50
     */
    virtual ~TimeZoneNames();

    /**
     * Return true if the given TimeZoneNames objects are semantically equal.
     * @param other the object to be compared with.
     * @return Return true if the given Format objects are semantically equal.
     * @stable ICU 50
     */
    virtual bool operator==(const TimeZoneNames& other) const = 0;

    /**
     * Return true if the given TimeZoneNames objects are not semantically
     * equal.
     * @param other the object to be compared with.
     * @return Return true if the given Format objects are not semantically equal.
     * @stable ICU 50
     */
    bool operator!=(const TimeZoneNames& other) const { return !operator==(other); }

    /**
     * Clone this object polymorphically.  The caller is responsible
     * for deleting the result when done.
     * @return A copy of the object
     * @stable ICU 50
     */
    virtual TimeZoneNames* clone() const = 0;

    /**
     * Returns an instance of <code>TimeZoneNames</code> for the specified locale.
     *
     * @param locale The locale.
     * @param status Receives the status.
     * @return An instance of <code>TimeZoneNames</code>
     * @stable ICU 50
     */
    static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);

    /**
     * Returns an instance of <code>TimeZoneNames</code> containing only short specific
     * zone names (SHORT_STANDARD and SHORT_DAYLIGHT),
     * compatible with the IANA tz database's zone abbreviations (not localized).
     * <br>
     * Note: The input locale is used for resolving ambiguous names (e.g. "IST" is parsed
     * as Israel Standard Time for Israel, while it is parsed as India Standard Time for
     * all other regions). The zone names returned by this instance are not localized.
     * @stable ICU 54
     */
     static TimeZoneNames* U_EXPORT2 createTZDBInstance(const Locale& locale, UErrorCode& status);

    /**
     * Returns an enumeration of all available meta zone IDs.
     * @param status Receives the status.
     * @return an enumeration object, owned by the caller.
     * @stable ICU 50
     */
    virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0;

    /**
     * Returns an enumeration of all available meta zone IDs used by the given time zone.
     * @param tzID The canonical time zone ID.
     * @param status Receives the status.
     * @return an enumeration object, owned by the caller.
     * @stable ICU 50
     */
    virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0;

    /**
     * Returns the meta zone ID for the given canonical time zone ID at the given date.
     * @param tzID The canonical time zone ID.
     * @param date The date.
     * @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
     *          corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state
     *          is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0;

    /**
     * Returns the reference zone ID for the given meta zone ID for the region.
     *
     * Note: Each meta zone must have a reference zone associated with a special region "001" (world).
     * Some meta zones may have region specific reference zone IDs other than the special region
     * "001". When a meta zone does not have any region specific reference zone IDs, this method
     * return the reference zone ID for the special region "001" (world).
     *
     * @param mzID The meta zone ID.
     * @param region The region.
     * @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the
     *          region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state
     *          is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0;

    /**
     * Returns the display name of the meta zone.
     * @param mzID The meta zone ID.
     * @param type The display name type. See {@link #UTimeZoneNameType}.
     * @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given
     *         meta zone with the specified type or the implementation does not provide any display names associated
     *         with meta zones, "bogus" state is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0;

    /**
     * Returns the display name of the time zone. Unlike {@link #getDisplayName},
     * this method does not get a name from a meta zone used by the time zone.
     * @param tzID The canonical time zone ID.
     * @param type The display name type. See {@link #UTimeZoneNameType}.
     * @param name Receives the display name for the time zone. When this object does not have a localized display name for the given
     *         time zone with the specified type, "bogus" state is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0;

    /**
     * Returns the exemplar location name for the given time zone. When this object does not have a localized location
     * name, the default implementation may still returns a programmatically generated name with the logic described
     * below.
     * <ol>
     * <li>Check if the ID contains "/". If not, return null.
     * <li>Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null.
     * <li>Extract a substring after the last occurrence of "/".
     * <li>Replace "_" with " ".
     * </ol>
     * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the
     * localized location name.
     *
     * @param tzID The canonical time zone ID
     * @param name Receives the exemplar location name for the given time zone, or "bogus" state is set when a localized
     *          location name is not available and the fallback logic described above cannot extract location from the ID.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString& getExemplarLocationName(const UnicodeString& tzID, UnicodeString& name) const;

    /**
     * Returns the display name of the time zone at the given date.
     * <p>
     * <b>Note:</b> This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the
     * result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the
     * time zone, then calls {@link #getMetaZoneDisplayName}.
     *
     * @param tzID The canonical time zone ID.
     * @param type The display name type. See {@link #UTimeZoneNameType}.
     * @param date The date.
     * @param name Receives the display name for the time zone at the given date. When this object does not have a localized display
     *          name for the time zone with the specified type and date, "bogus" state is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const;

    /**
     * @internal ICU internal only, for specific users only until proposed publicly.
     */
    virtual void loadAllDisplayNames(UErrorCode& status);

    /**
     * @internal ICU internal only, for specific users only until proposed publicly.
     */
    virtual void getDisplayNames(const UnicodeString& tzID, const UTimeZoneNameType types[], int32_t numTypes, UDate date, UnicodeString dest[], UErrorCode& status) const;

    /**
     * <code>MatchInfoCollection</code> represents a collection of time zone name matches used by
     * {@link TimeZoneNames#find}.
     * @internal
     */
    class U_I18N_API MatchInfoCollection : public UMemory {
    public:
        /**
         * Constructor.
         * @internal
         */
        MatchInfoCollection();
        /**
         * Destructor.
         * @internal
         */
        virtual ~MatchInfoCollection();

#ifndef U_HIDE_INTERNAL_API
        /**
         * Adds a zone match.
         * @param nameType The name type.
         * @param matchLength The match length.
         * @param tzID The time zone ID.
         * @param status Receives the status
         * @internal
         */
        void addZone(UTimeZoneNameType nameType, int32_t matchLength,
            const UnicodeString& tzID, UErrorCode& status);

        /**
         * Adds a meata zone match.
         * @param nameType The name type.
         * @param matchLength The match length.
         * @param mzID The metazone ID.
         * @param status Receives the status
         * @internal
         */
        void addMetaZone(UTimeZoneNameType nameType, int32_t matchLength,
            const UnicodeString& mzID, UErrorCode& status);

        /**
         * Returns the number of entries available in this object.
         * @return The number of entries.
         * @internal
         */
        int32_t size() const;

        /**
         * Returns the time zone name type of a match at the specified index.
         * @param idx The index
         * @return The time zone name type. If the specified idx is out of range,
         *      it returns UTZNM_UNKNOWN.
         * @see UTimeZoneNameType
         * @internal
         */
        UTimeZoneNameType getNameTypeAt(int32_t idx) const;

        /**
         * Returns the match length of a match at the specified index.
         * @param idx The index
         * @return The match length. If the specified idx is out of range,
         *      it returns 0.
         * @internal
         */
        int32_t getMatchLengthAt(int32_t idx) const;

        /**
         * Gets the zone ID of a match at the specified index.
         * @param idx The index
         * @param tzID Receives the zone ID.
         * @return true if the zone ID was set to tzID.
         * @internal
         */
        UBool getTimeZoneIDAt(int32_t idx, UnicodeString& tzID) const;

        /**
         * Gets the metazone ID of a match at the specified index.
         * @param idx The index
         * @param mzID Receives the metazone ID
         * @return true if the meta zone ID was set to mzID.
         * @internal
         */
        UBool getMetaZoneIDAt(int32_t idx, UnicodeString& mzID) const;
#endif  /* U_HIDE_INTERNAL_API */

    private:
        UVector* fMatches;  // vector of MatchEntry

        UVector* matches(UErrorCode& status);
    };

    /**
     * Finds time zone name prefix matches for the input text at the
     * given offset and returns a collection of the matches.
     * @param text The text.
     * @param start The starting offset within the text.
     * @param types The set of name types represented by bitwise flags of UTimeZoneNameType enums,
     *              or UTZNM_UNKNOWN for all name types.
     * @param status Receives the status.
     * @return A collection of matches (owned by the caller), or NULL if no matches are found.
     * @see UTimeZoneNameType
     * @see MatchInfoCollection
     * @internal
     */
    virtual MatchInfoCollection* find(const UnicodeString& text, int32_t start, uint32_t types, UErrorCode& status) const = 0;
};

U_NAMESPACE_END

#endif

#endif /* U_SHOW_CPLUSPLUS_API */

#endif

Coverage Report

Created: 2025-06-24 06:43

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