1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/tznames.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,392 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +* Copyright (C) 2011-2013, International Business Machines Corporation and *
1.7 +* others. All Rights Reserved. *
1.8 +*******************************************************************************
1.9 +*/
1.10 +#ifndef __TZNAMES_H
1.11 +#define __TZNAMES_H
1.12 +
1.13 +/**
1.14 + * \file
1.15 + * \brief C++ API: TimeZoneNames
1.16 + */
1.17 +#include "unicode/utypes.h"
1.18 +
1.19 +#if !UCONFIG_NO_FORMATTING
1.20 +
1.21 +#include "unicode/uloc.h"
1.22 +#include "unicode/unistr.h"
1.23 +
1.24 +U_CDECL_BEGIN
1.25 +
1.26 +/**
1.27 + * Constants for time zone display name types.
1.28 + * @stable ICU 50
1.29 + */
1.30 +typedef enum UTimeZoneNameType {
1.31 + /**
1.32 + * Unknown display name type.
1.33 + * @stable ICU 50
1.34 + */
1.35 + UTZNM_UNKNOWN = 0x00,
1.36 + /**
1.37 + * Long display name, such as "Eastern Time".
1.38 + * @stable ICU 50
1.39 + */
1.40 + UTZNM_LONG_GENERIC = 0x01,
1.41 + /**
1.42 + * Long display name for standard time, such as "Eastern Standard Time".
1.43 + * @stable ICU 50
1.44 + */
1.45 + UTZNM_LONG_STANDARD = 0x02,
1.46 + /**
1.47 + * Long display name for daylight saving time, such as "Eastern Daylight Time".
1.48 + * @stable ICU 50
1.49 + */
1.50 + UTZNM_LONG_DAYLIGHT = 0x04,
1.51 + /**
1.52 + * Short display name, such as "ET".
1.53 + * @stable ICU 50
1.54 + */
1.55 + UTZNM_SHORT_GENERIC = 0x08,
1.56 + /**
1.57 + * Short display name for standard time, such as "EST".
1.58 + * @stable ICU 50
1.59 + */
1.60 + UTZNM_SHORT_STANDARD = 0x10,
1.61 + /**
1.62 + * Short display name for daylight saving time, such as "EDT".
1.63 + * @stable ICU 50
1.64 + */
1.65 + UTZNM_SHORT_DAYLIGHT = 0x20,
1.66 +#ifndef U_HIDE_DRAFT_API
1.67 + /**
1.68 + * Exemplar location name, such as "Los Angeles".
1.69 + * @draft ICU 51
1.70 + */
1.71 + UTZNM_EXEMPLAR_LOCATION = 0x40
1.72 +#endif /* U_HIDE_DRAFT_API */
1.73 +} UTimeZoneNameType;
1.74 +
1.75 +U_CDECL_END
1.76 +
1.77 +U_NAMESPACE_BEGIN
1.78 +
1.79 +class UVector;
1.80 +struct MatchInfo;
1.81 +
1.82 +/**
1.83 + * <code>TimeZoneNames</code> is an abstract class representing the time zone display name data model defined
1.84 + * by <a href="http://www.unicode.org/reports/tr35/">UTS#35 Unicode Locale Data Markup Language (LDML)</a>.
1.85 + * The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared
1.86 + * by multiple time zones. Also a time zone may have multiple meta zone historic mappings.
1.87 + * <p>
1.88 + * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time".
1.89 + * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some
1.90 + * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make
1.91 + * much sense for most of people.
1.92 + * <p>
1.93 + * In <a href="http://cldr.unicode.org/">CLDR</a> (which uses LDML for representing locale data), the display name
1.94 + * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern".
1.95 + * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in
1.96 + * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern".
1.97 + * <p>
1.98 + * Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox"
1.99 + * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone
1.100 + * to meta zones mapping data are stored by date range.
1.101 + *
1.102 + * <p><b>Note:</b>
1.103 + * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper
1.104 + * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone
1.105 + * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See
1.106 + * {@link TimeZone#getCanonicalID(const UnicodeString& id, UnicodeString& canonicalID, UErrorCode& status)} about ICU
1.107 + * canonical time zone IDs.
1.108 + *
1.109 + * <p>
1.110 + * In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may
1.111 + * have a specific name that is not shared with other time zones.
1.112 + *
1.113 + * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also
1.114 + * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only
1.115 + * used for "Europe/London".
1.116 + *
1.117 + * <p>
1.118 + * {@link #getTimeZoneDisplayName} is designed for accessing a name only used by a single time zone.
1.119 + * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation
1.120 + * may provide time zone names only through {@link #getTimeZoneDisplayName}, or only through {@link #getMetaZoneDisplayName},
1.121 + * or both.
1.122 + *
1.123 + * <p>
1.124 + * The default <code>TimeZoneNames</code> implementation returned by {@link #createInstance}
1.125 + * uses the locale data imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone
1.126 + * IDs are shared by all locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs},
1.127 + * {@link #getMetaZoneID}, and {@link #getReferenceZoneID} won't be changed no matter
1.128 + * what locale is used for getting an instance of <code>TimeZoneNames</code>.
1.129 + *
1.130 + * @stable ICU 50
1.131 + */
1.132 +class U_I18N_API TimeZoneNames : public UObject {
1.133 +public:
1.134 + /**
1.135 + * Destructor.
1.136 + * @stable ICU 50
1.137 + */
1.138 + virtual ~TimeZoneNames();
1.139 +
1.140 + /**
1.141 + * Return true if the given TimeZoneNames objects are emantically equal.
1.142 + * @param other the object to be compared with.
1.143 + * @return Return TRUE if the given Format objects are semantically equal.
1.144 + * @stable ICU 50
1.145 + */
1.146 + virtual UBool operator==(const TimeZoneNames& other) const = 0;
1.147 +
1.148 + /**
1.149 + * Return true if the given TimeZoneNames objects are not semantically
1.150 + * equal.
1.151 + * @param other the object to be compared with.
1.152 + * @return Return TRUE if the given Format objects are not semantically equal.
1.153 + * @stable ICU 50
1.154 + */
1.155 + UBool operator!=(const TimeZoneNames& other) const { return !operator==(other); }
1.156 +
1.157 + /**
1.158 + * Clone this object polymorphically. The caller is responsible
1.159 + * for deleting the result when done.
1.160 + * @return A copy of the object
1.161 + * @stable ICU 50
1.162 + */
1.163 + virtual TimeZoneNames* clone() const = 0;
1.164 +
1.165 + /**
1.166 + * Returns an instance of <code>TimeZoneDisplayNames</code> for the specified locale.
1.167 + *
1.168 + * @param locale The locale.
1.169 + * @param status Recevies the status.
1.170 + * @return An instance of <code>TimeZoneDisplayNames</code>
1.171 + * @stable ICU 50
1.172 + */
1.173 + static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
1.174 +
1.175 + /**
1.176 + * Returns an enumeration of all available meta zone IDs.
1.177 + * @param status Recevies the status.
1.178 + * @return an enumeration object, owned by the caller.
1.179 + * @stable ICU 50
1.180 + */
1.181 + virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0;
1.182 +
1.183 + /**
1.184 + * Returns an enumeration of all available meta zone IDs used by the given time zone.
1.185 + * @param tzID The canoical tiem zone ID.
1.186 + * @param status Recevies the status.
1.187 + * @return an enumeration object, owned by the caller.
1.188 + * @stable ICU 50
1.189 + */
1.190 + virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0;
1.191 +
1.192 + /**
1.193 + * Returns the meta zone ID for the given canonical time zone ID at the given date.
1.194 + * @param tzID The canonical time zone ID.
1.195 + * @param date The date.
1.196 + * @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
1.197 + * corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state
1.198 + * is set.
1.199 + * @return A reference to the result.
1.200 + * @stable ICU 50
1.201 + */
1.202 + virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0;
1.203 +
1.204 + /**
1.205 + * Returns the reference zone ID for the given meta zone ID for the region.
1.206 + *
1.207 + * Note: Each meta zone must have a reference zone associated with a special region "001" (world).
1.208 + * Some meta zones may have region specific reference zone IDs other than the special region
1.209 + * "001". When a meta zone does not have any region specific reference zone IDs, this method
1.210 + * return the reference zone ID for the special region "001" (world).
1.211 + *
1.212 + * @param mzID The meta zone ID.
1.213 + * @param region The region.
1.214 + * @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the
1.215 + * region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state
1.216 + * is set.
1.217 + * @return A reference to the result.
1.218 + * @stable ICU 50
1.219 + */
1.220 + virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0;
1.221 +
1.222 + /**
1.223 + * Returns the display name of the meta zone.
1.224 + * @param mzID The meta zone ID.
1.225 + * @param type The display name type. See {@link #UTimeZoneNameType}.
1.226 + * @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given
1.227 + * meta zone with the specified type or the implementation does not provide any display names associated
1.228 + * with meta zones, "bogus" state is set.
1.229 + * @return A reference to the result.
1.230 + * @stable ICU 50
1.231 + */
1.232 + virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
1.233 +
1.234 + /**
1.235 + * Returns the display name of the time zone. Unlike {@link #getDisplayName},
1.236 + * this method does not get a name from a meta zone used by the time zone.
1.237 + * @param tzID The canonical time zone ID.
1.238 + * @param type The display name type. See {@link #UTimeZoneNameType}.
1.239 + * @param name Receives the display name for the time zone. When this object does not have a localized display name for the given
1.240 + * time zone with the specified type, "bogus" state is set.
1.241 + * @return A reference to the result.
1.242 + * @stable ICU 50
1.243 + */
1.244 + virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
1.245 +
1.246 + /**
1.247 + * Returns the exemplar location name for the given time zone. When this object does not have a localized location
1.248 + * name, the default implementation may still returns a programmatically generated name with the logic described
1.249 + * below.
1.250 + * <ol>
1.251 + * <li>Check if the ID contains "/". If not, return null.
1.252 + * <li>Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null.
1.253 + * <li>Extract a substring after the last occurrence of "/".
1.254 + * <li>Replace "_" with " ".
1.255 + * </ol>
1.256 + * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the
1.257 + * localized location name.
1.258 + *
1.259 + * @param tzID The canonical time zone ID
1.260 + * @param name Receives the exemplar location name for the given time zone, or "bogus" state is set when a localized
1.261 + * location name is not available and the fallback logic described above cannot extract location from the ID.
1.262 + * @return A reference to the result.
1.263 + * @stable ICU 50
1.264 + */
1.265 + virtual UnicodeString& getExemplarLocationName(const UnicodeString& tzID, UnicodeString& name) const;
1.266 +
1.267 + /**
1.268 + * Returns the display name of the time zone at the given date.
1.269 + * <p>
1.270 + * <b>Note:</b> This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the
1.271 + * result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the
1.272 + * time zone, then calls {@link #getMetaZoneDisplayName}.
1.273 + *
1.274 + * @param tzID The canonical time zone ID.
1.275 + * @param type The display name type. See {@link #UTimeZoneNameType}.
1.276 + * @param date The date.
1.277 + * @param name Receives the display name for the time zone at the given date. When this object does not have a localized display
1.278 + * name for the time zone with the specified type and date, "bogus" state is set.
1.279 + * @return A reference to the result.
1.280 + * @stable ICU 50
1.281 + */
1.282 + virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const;
1.283 +
1.284 + /**
1.285 + * <code>MatchInfoCollection</code> represents a collection of time zone name matches used by
1.286 + * {@link TimeZoneNames#find}.
1.287 + * @internal
1.288 + */
1.289 + class U_I18N_API MatchInfoCollection : public UMemory {
1.290 + public:
1.291 + /**
1.292 + * Constructor.
1.293 + * @internal
1.294 + */
1.295 + MatchInfoCollection();
1.296 + /**
1.297 + * Destructor.
1.298 + * @internal
1.299 + */
1.300 + virtual ~MatchInfoCollection();
1.301 +
1.302 +#ifndef U_HIDE_INTERNAL_API
1.303 + /**
1.304 + * Adds a zone match.
1.305 + * @param nameType The name type.
1.306 + * @param matchLength The match length.
1.307 + * @param tzID The time zone ID.
1.308 + * @param status Receives the status
1.309 + * @internal
1.310 + */
1.311 + void addZone(UTimeZoneNameType nameType, int32_t matchLength,
1.312 + const UnicodeString& tzID, UErrorCode& status);
1.313 +
1.314 + /**
1.315 + * Adds a meata zone match.
1.316 + * @param nameType The name type.
1.317 + * @param matchLength The match length.
1.318 + * @param mzID The metazone ID.
1.319 + * @param status Receives the status
1.320 + * @internal
1.321 + */
1.322 + void addMetaZone(UTimeZoneNameType nameType, int32_t matchLength,
1.323 + const UnicodeString& mzID, UErrorCode& status);
1.324 +
1.325 + /**
1.326 + * Returns the number of entries available in this object.
1.327 + * @return The number of entries.
1.328 + * @internal
1.329 + */
1.330 + int32_t size() const;
1.331 +
1.332 + /**
1.333 + * Returns the time zone name type of a match at the specified index.
1.334 + * @param idx The index
1.335 + * @return The time zone name type. If the specified idx is out of range,
1.336 + * it returns UTZNM_UNKNOWN.
1.337 + * @see UTimeZoneNameType
1.338 + * @internal
1.339 + */
1.340 + UTimeZoneNameType getNameTypeAt(int32_t idx) const;
1.341 +
1.342 + /**
1.343 + * Returns the match length of a match at the specified index.
1.344 + * @param idx The index
1.345 + * @return The match length. If the specified idx is out of range,
1.346 + * it returns 0.
1.347 + * @internal
1.348 + */
1.349 + int32_t getMatchLengthAt(int32_t idx) const;
1.350 +
1.351 + /**
1.352 + * Gets the zone ID of a match at the specified index.
1.353 + * @param idx The index
1.354 + * @param tzID Receives the zone ID.
1.355 + * @return TRUE if the zone ID was set to tzID.
1.356 + * @internal
1.357 + */
1.358 + UBool getTimeZoneIDAt(int32_t idx, UnicodeString& tzID) const;
1.359 +
1.360 + /**
1.361 + * Gets the metazone ID of a match at the specified index.
1.362 + * @param idx The index
1.363 + * @param mzID Receives the metazone ID
1.364 + * @return TRUE if the meta zone ID was set to mzID.
1.365 + * @internal
1.366 + */
1.367 + UBool getMetaZoneIDAt(int32_t idx, UnicodeString& mzID) const;
1.368 +#endif /* U_HIDE_INTERNAL_API */
1.369 +
1.370 + private:
1.371 + UVector* fMatches; // vector of MatchEntry
1.372 +
1.373 + UVector* matches(UErrorCode& status);
1.374 + };
1.375 +
1.376 + /**
1.377 + * Finds time zone name prefix matches for the input text at the
1.378 + * given offset and returns a collection of the matches.
1.379 + * @param text The text.
1.380 + * @param start The starting offset within the text.
1.381 + * @param types The set of name types represented by bitwise flags of UTimeZoneNameType enums,
1.382 + * or UTZNM_UNKNOWN for all name types.
1.383 + * @param status Receives the status.
1.384 + * @return A collection of matches (owned by the caller), or NULL if no matches are found.
1.385 + * @see UTimeZoneNameType
1.386 + * @see MatchInfoCollection
1.387 + * @internal
1.388 + */
1.389 + virtual MatchInfoCollection* find(const UnicodeString& text, int32_t start, uint32_t types, UErrorCode& status) const = 0;
1.390 +};
1.391 +
1.392 +U_NAMESPACE_END
1.393 +
1.394 +#endif
1.395 +#endif
