[apple/icu.git] / icuSources / i18n / unicode / tznames.h

/*
*******************************************************************************
* Copyright (C) 2011-2013, 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 !UCONFIG_NO_FORMATTING
#ifndef U_HIDE_DRAFT_API

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

U_CDECL_BEGIN

/**
 * Constants for time zone display name types.
 * @draft ICU 50
 */
typedef enum UTimeZoneNameType {
    /**
     * Unknown display name type.
     * @draft ICU 50
     */
    UTZNM_UNKNOWN           = 0x00,
    /**
     * Long display name, such as "Eastern Time".
     * @draft ICU 50
     */
    UTZNM_LONG_GENERIC      = 0x01,
    /**
     * Long display name for standard time, such as "Eastern Standard Time".
     * @draft ICU 50
     */
    UTZNM_LONG_STANDARD     = 0x02,
    /**
     * Long display name for daylight saving time, such as "Eastern Daylight Time".
     * @draft ICU 50
     */
    UTZNM_LONG_DAYLIGHT     = 0x04,
    /**
     * Short display name, such as "ET".
     * @draft ICU 50
     */
    UTZNM_SHORT_GENERIC     = 0x08,
    /**
     * Short display name for standard time, such as "EST".
     * @draft ICU 50
     */
    UTZNM_SHORT_STANDARD    = 0x10,
    /**
     * Short display name for daylight saving time, such as "EDT".
     * @draft ICU 50
     */
    UTZNM_SHORT_DAYLIGHT    = 0x20,
#ifndef U_HIDE_DRAFT_API
    /**
     * Exemplar location name, such as "Los Angeles".
     * @draft ICU 51
     */
    UTZNM_EXEMPLAR_LOCATION = 0x40
#endif /* U_HIDE_DRAFT_API */
} 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>.
 *
 * @draft ICU 50
 */
class U_I18N_API TimeZoneNames : public UObject {
public:
    /**
     * Destructor.
     * @draft ICU 50
     */
    virtual ~TimeZoneNames();

    /**
     * Return true if the given TimeZoneNames objects are emantically equal.
     * @param other the object to be compared with.
     * @return Return TRUE if the given Format objects are semantically equal.
     * @draft ICU 50
     */
    virtual UBool 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.
     * @draft ICU 50
     */
    UBool 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
     * @draft ICU 50
     */
    virtual TimeZoneNames* clone() const = 0;

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

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