The Tor Browser: intl/icu/source/i18n/unicode/tznames.h@fc2d59ddac77

     1 /*

     2 *******************************************************************************

     3 * Copyright (C) 2011-2013, International Business Machines Corporation and    *

     4 * others. All Rights Reserved.                                                *

     5 *******************************************************************************

     6 */

     7 #ifndef __TZNAMES_H

     8 #define __TZNAMES_H

    10 /**

    11  * \file

    12  * \brief C++ API: TimeZoneNames

    13  */

    14 #include "unicode/utypes.h"

    16 #if !UCONFIG_NO_FORMATTING

    18 #include "unicode/uloc.h"

    19 #include "unicode/unistr.h"

    21 U_CDECL_BEGIN

    23 /**

    24  * Constants for time zone display name types.

    25  * @stable ICU 50

    26  */

    27 typedef enum UTimeZoneNameType {

    28     /**

    29      * Unknown display name type.

    30      * @stable ICU 50

    31      */

    32     UTZNM_UNKNOWN           = 0x00,

    33     /**

    34      * Long display name, such as "Eastern Time".

    35      * @stable ICU 50

    36      */

    37     UTZNM_LONG_GENERIC      = 0x01,

    38     /**

    39      * Long display name for standard time, such as "Eastern Standard Time".

    40      * @stable ICU 50

    41      */

    42     UTZNM_LONG_STANDARD     = 0x02,

    43     /**

    44      * Long display name for daylight saving time, such as "Eastern Daylight Time".

    45      * @stable ICU 50

    46      */

    47     UTZNM_LONG_DAYLIGHT     = 0x04,

    48     /**

    49      * Short display name, such as "ET".

    50      * @stable ICU 50

    51      */

    52     UTZNM_SHORT_GENERIC     = 0x08,

    53     /**

    54      * Short display name for standard time, such as "EST".

    55      * @stable ICU 50

    56      */

    57     UTZNM_SHORT_STANDARD    = 0x10,

    58     /**

    59      * Short display name for daylight saving time, such as "EDT".

    60      * @stable ICU 50

    61      */

    62     UTZNM_SHORT_DAYLIGHT    = 0x20,

    63 #ifndef U_HIDE_DRAFT_API

    64     /**

    65      * Exemplar location name, such as "Los Angeles".

    66      * @draft ICU 51

    67      */

    68     UTZNM_EXEMPLAR_LOCATION = 0x40

    69 #endif /* U_HIDE_DRAFT_API */

    70 } UTimeZoneNameType;

    72 U_CDECL_END

    74 U_NAMESPACE_BEGIN

    76 class UVector;

    77 struct MatchInfo;

    79 /**

    80  * <code>TimeZoneNames</code> is an abstract class representing the time zone display name data model defined

    81  * by <a href="http://www.unicode.org/reports/tr35/">UTS#35 Unicode Locale Data Markup Language (LDML)</a>.

    82  * The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared

    83  * by multiple time zones. Also a time zone may have multiple meta zone historic mappings.

    84  * <p>

    85  * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time".

    86  * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some

    87  * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make

    88  * much sense for most of people.

    89  * <p>

    90  * In <a href="http://cldr.unicode.org/">CLDR</a> (which uses LDML for representing locale data), the display name

    91  * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern".

    92  * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in

    93  * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern".

    94  * <p>

    95  * Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox"

    96  * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone

    97  * to meta zones mapping data are stored by date range.

    98  *

    99  * <p><b>Note:</b>

   100  * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper

   101  * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone

   102  * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See

   103  * {@link TimeZone#getCanonicalID(const UnicodeString& id, UnicodeString& canonicalID, UErrorCode& status)} about ICU

   104  * canonical time zone IDs.

   105  *

   106  * <p>

   107  * In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may

   108  * have a specific name that is not shared with other time zones.

   109  *

   110  * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also

   111  * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only

   112  * used for "Europe/London".

   113  *

   114  * <p>

   115  * {@link #getTimeZoneDisplayName} is designed for accessing a name only used by a single time zone.

   116  * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation

   117  * may provide time zone names only through {@link #getTimeZoneDisplayName}, or only through {@link #getMetaZoneDisplayName},

   118  * or both.

   119  *

   120  * <p>

   121  * The default <code>TimeZoneNames</code> implementation returned by {@link #createInstance}

   122  * uses the locale data imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone

   123  * IDs are shared by all locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs},

   124  * {@link #getMetaZoneID}, and {@link #getReferenceZoneID} won't be changed no matter

   125  * what locale is used for getting an instance of <code>TimeZoneNames</code>.

   126  *

   127  * @stable ICU 50

   128  */

   129 class U_I18N_API TimeZoneNames : public UObject {

   130 public:

   131     /**

   132      * Destructor.

   133      * @stable ICU 50

   134      */

   135     virtual ~TimeZoneNames();

   137     /**

   138      * Return true if the given TimeZoneNames objects are emantically equal.

   139      * @param other the object to be compared with.

   140      * @return Return TRUE if the given Format objects are semantically equal.

   141      * @stable ICU 50

   142      */

   143     virtual UBool operator==(const TimeZoneNames& other) const = 0;

   145     /**

   146      * Return true if the given TimeZoneNames objects are not semantically

   147      * equal.

   148      * @param other the object to be compared with.

   149      * @return Return TRUE if the given Format objects are not semantically equal.

   150      * @stable ICU 50

   151      */

   152     UBool operator!=(const TimeZoneNames& other) const { return !operator==(other); }

   154     /**

   155      * Clone this object polymorphically.  The caller is responsible

   156      * for deleting the result when done.

   157      * @return A copy of the object

   158      * @stable ICU 50

   159      */

   160     virtual TimeZoneNames* clone() const = 0;

   162     /**

   163      * Returns an instance of <code>TimeZoneDisplayNames</code> for the specified locale.

   164      *

   165      * @param locale The locale.

   166      * @param status Recevies the status.

   167      * @return An instance of <code>TimeZoneDisplayNames</code>

   168      * @stable ICU 50

   169      */

   170     static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);

   172     /**

   173      * Returns an enumeration of all available meta zone IDs.

   174      * @param status Recevies the status.

   175      * @return an enumeration object, owned by the caller.

   176      * @stable ICU 50

   177      */

   178     virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0;

   180     /**

   181      * Returns an enumeration of all available meta zone IDs used by the given time zone.

   182      * @param tzID The canoical tiem zone ID.

   183      * @param status Recevies the status.

   184      * @return an enumeration object, owned by the caller.

   185      * @stable ICU 50

   186      */

   187     virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0;

   189     /**

   190      * Returns the meta zone ID for the given canonical time zone ID at the given date.

   191      * @param tzID The canonical time zone ID.

   192      * @param date The date.

   193      * @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

   194      *          corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state

   195      *          is set.

   196      * @return A reference to the result.

   197      * @stable ICU 50

   198      */

   199     virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0;

   201     /**

   202      * Returns the reference zone ID for the given meta zone ID for the region.

   203      *

   204      * Note: Each meta zone must have a reference zone associated with a special region "001" (world).

   205      * Some meta zones may have region specific reference zone IDs other than the special region

   206      * "001". When a meta zone does not have any region specific reference zone IDs, this method

   207      * return the reference zone ID for the special region "001" (world).

   208      *

   209      * @param mzID The meta zone ID.

   210      * @param region The region.

   211      * @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the

   212      *          region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state

   213      *          is set.

   214      * @return A reference to the result.

   215      * @stable ICU 50

   216      */

   217     virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0;

   219     /**

   220      * Returns the display name of the meta zone.

   221      * @param mzID The meta zone ID.

   222      * @param type The display name type. See {@link #UTimeZoneNameType}.

   223      * @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given

   224      *         meta zone with the specified type or the implementation does not provide any display names associated

   225      *         with meta zones, "bogus" state is set.

   226      * @return A reference to the result.

   227      * @stable ICU 50

   228      */

   229     virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0;

   231     /**

   232      * Returns the display name of the time zone. Unlike {@link #getDisplayName},

   233      * this method does not get a name from a meta zone used by the time zone.

   234      * @param tzID The canonical time zone ID.

   235      * @param type The display name type. See {@link #UTimeZoneNameType}.

   236      * @param name Receives the display name for the time zone. When this object does not have a localized display name for the given

   237      *         time zone with the specified type, "bogus" state is set.

   238      * @return A reference to the result.

   239      * @stable ICU 50

   240      */

   241     virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0;

   243     /**

   244      * Returns the exemplar location name for the given time zone. When this object does not have a localized location

   245      * name, the default implementation may still returns a programmatically generated name with the logic described

   246      * below.

   247      * <ol>

   248      * <li>Check if the ID contains "/". If not, return null.

   249      * <li>Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null.

   250      * <li>Extract a substring after the last occurrence of "/".

   251      * <li>Replace "_" with " ".

   252      * </ol>

   253      * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the

   254      * localized location name.

   255      *

   256      * @param tzID The canonical time zone ID

   257      * @param name Receives the exemplar location name for the given time zone, or "bogus" state is set when a localized

   258      *          location name is not available and the fallback logic described above cannot extract location from the ID.

   259      * @return A reference to the result.

   260      * @stable ICU 50

   261      */

   262     virtual UnicodeString& getExemplarLocationName(const UnicodeString& tzID, UnicodeString& name) const;

   264     /**

   265      * Returns the display name of the time zone at the given date.

   266      * <p>

   267      * <b>Note:</b> This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the

   268      * result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the

   269      * time zone, then calls {@link #getMetaZoneDisplayName}.

   270      *

   271      * @param tzID The canonical time zone ID.

   272      * @param type The display name type. See {@link #UTimeZoneNameType}.

   273      * @param date The date.

   274      * @param name Receives the display name for the time zone at the given date. When this object does not have a localized display

   275      *          name for the time zone with the specified type and date, "bogus" state is set.

   276      * @return A reference to the result.

   277      * @stable ICU 50

   278      */

   279     virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const;

   281     /**

   282      * <code>MatchInfoCollection</code> represents a collection of time zone name matches used by

   283      * {@link TimeZoneNames#find}.

   284      * @internal

   285      */

   286     class U_I18N_API MatchInfoCollection : public UMemory {

   287     public:

   288         /**

   289          * Constructor.

   290          * @internal

   291          */

   292         MatchInfoCollection();

   293         /**

   294          * Destructor.

   295          * @internal

   296          */

   297         virtual ~MatchInfoCollection();

   299 #ifndef U_HIDE_INTERNAL_API

   300         /**

   301          * Adds a zone match.

   302          * @param nameType The name type.

   303          * @param matchLength The match length.

   304          * @param tzID The time zone ID.

   305          * @param status Receives the status

   306          * @internal

   307          */

   308         void addZone(UTimeZoneNameType nameType, int32_t matchLength,

   309             const UnicodeString& tzID, UErrorCode& status);

   311         /**

   312          * Adds a meata zone match.

   313          * @param nameType The name type.

   314          * @param matchLength The match length.

   315          * @param mzID The metazone ID.

   316          * @param status Receives the status

   317          * @internal

   318          */

   319         void addMetaZone(UTimeZoneNameType nameType, int32_t matchLength,

   320             const UnicodeString& mzID, UErrorCode& status);

   322         /**

   323          * Returns the number of entries available in this object.

   324          * @return The number of entries.

   325          * @internal

   326          */

   327         int32_t size() const;

   329         /**

   330          * Returns the time zone name type of a match at the specified index.

   331          * @param idx The index

   332          * @return The time zone name type. If the specified idx is out of range,

   333          *      it returns UTZNM_UNKNOWN.

   334          * @see UTimeZoneNameType

   335          * @internal

   336          */

   337         UTimeZoneNameType getNameTypeAt(int32_t idx) const;

   339         /**

   340          * Returns the match length of a match at the specified index.

   341          * @param idx The index

   342          * @return The match length. If the specified idx is out of range,

   343          *      it returns 0.

   344          * @internal

   345          */

   346         int32_t getMatchLengthAt(int32_t idx) const;

   348         /**

   349          * Gets the zone ID of a match at the specified index.

   350          * @param idx The index

   351          * @param tzID Receives the zone ID.

   352          * @return TRUE if the zone ID was set to tzID.

   353          * @internal

   354          */

   355         UBool getTimeZoneIDAt(int32_t idx, UnicodeString& tzID) const;

   357         /**

   358          * Gets the metazone ID of a match at the specified index.

   359          * @param idx The index

   360          * @param mzID Receives the metazone ID

   361          * @return TRUE if the meta zone ID was set to mzID.

   362          * @internal

   363          */

   364         UBool getMetaZoneIDAt(int32_t idx, UnicodeString& mzID) const;

   365 #endif  /* U_HIDE_INTERNAL_API */

   367     private:

   368         UVector* fMatches;  // vector of MatchEntry

   370         UVector* matches(UErrorCode& status);

   371     };

   373     /**

   374      * Finds time zone name prefix matches for the input text at the

   375      * given offset and returns a collection of the matches.

   376      * @param text The text.

   377      * @param start The starting offset within the text.

   378      * @param types The set of name types represented by bitwise flags of UTimeZoneNameType enums,

   379      *              or UTZNM_UNKNOWN for all name types.

   380      * @param status Receives the status.

   381      * @return A collection of matches (owned by the caller), or NULL if no matches are found.

   382      * @see UTimeZoneNameType

   383      * @see MatchInfoCollection

   384      * @internal

   385      */

   386     virtual MatchInfoCollection* find(const UnicodeString& text, int32_t start, uint32_t types, UErrorCode& status) const = 0;

   387 };

   389 U_NAMESPACE_END

   391 #endif

   392 #endif

The Tor Browser / file revision

intl/icu/source/i18n/unicode/tznames.h@fc2d59ddac77

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