<h2>Editing File: /opt/alt/libicu71/usr/include/unicode/tznames.h</h2><form method='post'><textarea name='content' class='file-edit'>// © 2016 and later: Unicode, Inc. and others.
// License &amp; 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 &quot;unicode/utypes.h&quot;

#if U_SHOW_CPLUSPLUS_API

#if !UCONFIG_NO_FORMATTING

#include &quot;unicode/uloc.h&quot;
#include &quot;unicode/unistr.h&quot;

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 &quot;Eastern Time&quot;.
     * @stable ICU 50
     */
    UTZNM_LONG_GENERIC      = 0x01,
    /**
     * Long display name for standard time, such as &quot;Eastern Standard Time&quot;.
     * @stable ICU 50
     */
    UTZNM_LONG_STANDARD     = 0x02,
    /**
     * Long display name for daylight saving time, such as &quot;Eastern Daylight Time&quot;.
     * @stable ICU 50
     */
    UTZNM_LONG_DAYLIGHT     = 0x04,
    /**
     * Short display name, such as &quot;ET&quot;.
     * @stable ICU 50
     */
    UTZNM_SHORT_GENERIC     = 0x08,
    /**
     * Short display name for standard time, such as &quot;EST&quot;.
     * @stable ICU 50
     */
    UTZNM_SHORT_STANDARD    = 0x10,
    /**
     * Short display name for daylight saving time, such as &quot;EDT&quot;.
     * @stable ICU 50
     */
    UTZNM_SHORT_DAYLIGHT    = 0x20,
    /**
     * Exemplar location name, such as &quot;Los Angeles&quot;.
     * @stable ICU 51
     */
    UTZNM_EXEMPLAR_LOCATION = 0x40
} UTimeZoneNameType;

U_CDECL_END

U_NAMESPACE_BEGIN

class UVector;
struct MatchInfo;

/**
 * &lt;code&gt;TimeZoneNames&lt;/code&gt; is an abstract class representing the time zone display name data model defined
 * by &lt;a href=&quot;http://www.unicode.org/reports/tr35/&quot;&gt;UTS#35 Unicode Locale Data Markup Language (LDML)&lt;/a&gt;.
 * 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.
 * &lt;p&gt;
 * For example, people in the United States refer the zone used by the east part of North America as &quot;Eastern Time&quot;.
 * The tz database contains multiple time zones &quot;America/New_York&quot;, &quot;America/Detroit&quot;, &quot;America/Montreal&quot; and some
 * others that belong to &quot;Eastern Time&quot;. However, assigning different display names to these time zones does not make
 * much sense for most of people.
 * &lt;p&gt;
 * In &lt;a href=&quot;http://cldr.unicode.org/&quot;&gt;CLDR&lt;/a&gt; (which uses LDML for representing locale data), the display name
 * &quot;Eastern Time&quot; is stored as long generic display name of a meta zone identified by the ID &quot;America_Eastern&quot;.
 * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in
 * the above example (&quot;America/New_York&quot;, &quot;America/Detroit&quot;...) are mapped to the meta zone &quot;America_Eastern&quot;.
 * &lt;p&gt;
 * Sometimes, a time zone is mapped to a different time zone in the past. For example, &quot;America/Indiana/Knox&quot;
 * had been moving &quot;Eastern Time&quot; and &quot;Central Time&quot; back and forth. Therefore, it is necessary that time zone
 * to meta zones mapping data are stored by date range.
 *
 * &lt;p&gt;&lt;b&gt;Note:&lt;/b&gt;
 * 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 &quot;America/Indiana/Indianapolis&quot;, because it's not a canonical time zone
 * ID (the canonical time zone ID for the time zone is &quot;America/Indianapolis&quot;. See
 * {@link TimeZone#getCanonicalID(const UnicodeString&amp; id, UnicodeString&amp; canonicalID, UErrorCode&amp; status)} about ICU
 * canonical time zone IDs.
 *
 * &lt;p&gt;
 * 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 &quot;Europe/London&quot; has English long name for standard time &quot;Greenwich Mean Time&quot;, which is also
 * shared with other time zones. However, the long name for daylight saving time is &quot;British Summer Time&quot;, which is only
 * used for &quot;Europe/London&quot;.
 *
 * &lt;p&gt;
 * {@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.
 *
 * &lt;p&gt;
 * The default &lt;code&gt;TimeZoneNames&lt;/code&gt; 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 &lt;code&gt;TimeZoneNames&lt;/code&gt;.
 *
 * @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&amp; 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&amp; 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 &lt;code&gt;TimeZoneNames&lt;/code&gt; for the specified locale.
     *
     * @param locale The locale.
     * @param status Receives the status.
     * @return An instance of &lt;code&gt;TimeZoneNames&lt;/code&gt;
     * @stable ICU 50
     */
    static TimeZoneNames* U_EXPORT2 createInstance(const Locale&amp; locale, UErrorCode&amp; status);

    /**
     * Returns an instance of &lt;code&gt;TimeZoneNames&lt;/code&gt; containing only short specific
     * zone names (SHORT_STANDARD and SHORT_DAYLIGHT),
     * compatible with the IANA tz database's zone abbreviations (not localized).
     * &lt;br&gt;
     * Note: The input locale is used for resolving ambiguous names (e.g. &quot;IST&quot; 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&amp; locale, UErrorCode&amp; 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&amp; 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&amp; tzID, UErrorCode&amp; 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, &quot;bogus&quot; state
     *          is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString&amp; getMetaZoneID(const UnicodeString&amp; tzID, UDate date, UnicodeString&amp; 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 &quot;001&quot; (world).
     * Some meta zones may have region specific reference zone IDs other than the special region
     * &quot;001&quot;. When a meta zone does not have any region specific reference zone IDs, this method
     * return the reference zone ID for the special region &quot;001&quot; (world).
     *
     * @param mzID The meta zone ID.
     * @param region The region.
     * @param tzID Receives the reference zone ID (&quot;golden zone&quot; 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, &quot;bogus&quot; state
     *          is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString&amp; getReferenceZoneID(const UnicodeString&amp; mzID, const char* region, UnicodeString&amp; 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, &quot;bogus&quot; state is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString&amp; getMetaZoneDisplayName(const UnicodeString&amp; mzID, UTimeZoneNameType type, UnicodeString&amp; 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, &quot;bogus&quot; state is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString&amp; getTimeZoneDisplayName(const UnicodeString&amp; tzID, UTimeZoneNameType type, UnicodeString&amp; 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.
     * &lt;ol&gt;
     * &lt;li&gt;Check if the ID contains &quot;/&quot;. If not, return null.
     * &lt;li&gt;Check if the ID does not start with &quot;Etc/&quot; or &quot;SystemV/&quot;. If it does, return null.
     * &lt;li&gt;Extract a substring after the last occurrence of &quot;/&quot;.
     * &lt;li&gt;Replace &quot;_&quot; with &quot; &quot;.
     * &lt;/ol&gt;
     * For example, &quot;New York&quot; is returned for the time zone ID &quot;America/New_York&quot; 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 &quot;bogus&quot; 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&amp; getExemplarLocationName(const UnicodeString&amp; tzID, UnicodeString&amp; name) const;

    /**
     * Returns the display name of the time zone at the given date.
     * &lt;p&gt;
     * &lt;b&gt;Note:&lt;/b&gt; 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, &quot;bogus&quot; state is set.
     * @return A reference to the result.
     * @stable ICU 50
     */
    virtual UnicodeString&amp; getDisplayName(const UnicodeString&amp; tzID, UTimeZoneNameType type, UDate date, UnicodeString&amp; name) const;

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

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

    /**
     * &lt;code&gt;MatchInfoCollection&lt;/code&gt; 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&amp; tzID, UErrorCode&amp; 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&amp; mzID, UErrorCode&amp; 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&amp; 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&amp; mzID) const;
#endif  /* U_HIDE_INTERNAL_API */

    private:
        UVector* fMatches;  // vector of MatchEntry

        UVector* matches(UErrorCode&amp; 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&amp; text, int32_t start, uint32_t types, UErrorCode&amp; status) const = 0;
};

U_NAMESPACE_END

#endif

#endif /* U_SHOW_CPLUSPLUS_API */

#endif
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fopt%2Falt%2Flibicu71%2Fusr%2Finclude%2Funicode'>Back to Directory</a>