• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (C) 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 !UCONFIG_NO_FORMATTING
19 
20 #include "unicode/uloc.h"
21 #include "unicode/unistr.h"
22 
23 U_CDECL_BEGIN
24 
25 /**
26  * Constants for time zone display name types.
27  * @stable ICU 50
28  */
29 typedef enum UTimeZoneNameType {
30     /**
31      * Unknown display name type.
32      * @stable ICU 50
33      */
34     UTZNM_UNKNOWN           = 0x00,
35     /**
36      * Long display name, such as "Eastern Time".
37      * @stable ICU 50
38      */
39     UTZNM_LONG_GENERIC      = 0x01,
40     /**
41      * Long display name for standard time, such as "Eastern Standard Time".
42      * @stable ICU 50
43      */
44     UTZNM_LONG_STANDARD     = 0x02,
45     /**
46      * Long display name for daylight saving time, such as "Eastern Daylight Time".
47      * @stable ICU 50
48      */
49     UTZNM_LONG_DAYLIGHT     = 0x04,
50     /**
51      * Short display name, such as "ET".
52      * @stable ICU 50
53      */
54     UTZNM_SHORT_GENERIC     = 0x08,
55     /**
56      * Short display name for standard time, such as "EST".
57      * @stable ICU 50
58      */
59     UTZNM_SHORT_STANDARD    = 0x10,
60     /**
61      * Short display name for daylight saving time, such as "EDT".
62      * @stable ICU 50
63      */
64     UTZNM_SHORT_DAYLIGHT    = 0x20,
65     /**
66      * Exemplar location name, such as "Los Angeles".
67      * @stable ICU 51
68      */
69     UTZNM_EXEMPLAR_LOCATION = 0x40
70 } UTimeZoneNameType;
71 
72 U_CDECL_END
73 
74 U_NAMESPACE_BEGIN
75 
76 class UVector;
77 struct MatchInfo;
78 
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();
136 
137     /**
138      * Return true if the given TimeZoneNames objects are semantically 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;
144 
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); }
153 
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;
161 
162     /**
163      * Returns an instance of <code>TimeZoneNames</code> for the specified locale.
164      *
165      * @param locale The locale.
166      * @param status Receives the status.
167      * @return An instance of <code>TimeZoneNames</code>
168      * @stable ICU 50
169      */
170     static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
171 
172     /**
173      * Returns an instance of <code>TimeZoneNames</code> containing only short specific
174      * zone names (SHORT_STANDARD and SHORT_DAYLIGHT),
175      * compatible with the IANA tz database's zone abbreviations (not localized).
176      * <br>
177      * Note: The input locale is used for resolving ambiguous names (e.g. "IST" is parsed
178      * as Israel Standard Time for Israel, while it is parsed as India Standard Time for
179      * all other regions). The zone names returned by this instance are not localized.
180      * @stable ICU 54
181      */
182      static TimeZoneNames* U_EXPORT2 createTZDBInstance(const Locale& locale, UErrorCode& status);
183 
184     /**
185      * Returns an enumeration of all available meta zone IDs.
186      * @param status Receives the status.
187      * @return an enumeration object, owned by the caller.
188      * @stable ICU 50
189      */
190     virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0;
191 
192     /**
193      * Returns an enumeration of all available meta zone IDs used by the given time zone.
194      * @param tzID The canoical tiem zone ID.
195      * @param status Receives the status.
196      * @return an enumeration object, owned by the caller.
197      * @stable ICU 50
198      */
199     virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0;
200 
201     /**
202      * Returns the meta zone ID for the given canonical time zone ID at the given date.
203      * @param tzID The canonical time zone ID.
204      * @param date The date.
205      * @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
206      *          corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state
207      *          is set.
208      * @return A reference to the result.
209      * @stable ICU 50
210      */
211     virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0;
212 
213     /**
214      * Returns the reference zone ID for the given meta zone ID for the region.
215      *
216      * Note: Each meta zone must have a reference zone associated with a special region "001" (world).
217      * Some meta zones may have region specific reference zone IDs other than the special region
218      * "001". When a meta zone does not have any region specific reference zone IDs, this method
219      * return the reference zone ID for the special region "001" (world).
220      *
221      * @param mzID The meta zone ID.
222      * @param region The region.
223      * @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the
224      *          region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state
225      *          is set.
226      * @return A reference to the result.
227      * @stable ICU 50
228      */
229     virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0;
230 
231     /**
232      * Returns the display name of the meta zone.
233      * @param mzID The meta zone ID.
234      * @param type The display name type. See {@link #UTimeZoneNameType}.
235      * @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given
236      *         meta zone with the specified type or the implementation does not provide any display names associated
237      *         with meta zones, "bogus" state is set.
238      * @return A reference to the result.
239      * @stable ICU 50
240      */
241     virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
242 
243     /**
244      * Returns the display name of the time zone. Unlike {@link #getDisplayName},
245      * this method does not get a name from a meta zone used by the time zone.
246      * @param tzID The canonical time zone ID.
247      * @param type The display name type. See {@link #UTimeZoneNameType}.
248      * @param name Receives the display name for the time zone. When this object does not have a localized display name for the given
249      *         time zone with the specified type, "bogus" state is set.
250      * @return A reference to the result.
251      * @stable ICU 50
252      */
253     virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
254 
255     /**
256      * Returns the exemplar location name for the given time zone. When this object does not have a localized location
257      * name, the default implementation may still returns a programmatically generated name with the logic described
258      * below.
259      * <ol>
260      * <li>Check if the ID contains "/". If not, return null.
261      * <li>Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null.
262      * <li>Extract a substring after the last occurrence of "/".
263      * <li>Replace "_" with " ".
264      * </ol>
265      * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the
266      * localized location name.
267      *
268      * @param tzID The canonical time zone ID
269      * @param name Receives the exemplar location name for the given time zone, or "bogus" state is set when a localized
270      *          location name is not available and the fallback logic described above cannot extract location from the ID.
271      * @return A reference to the result.
272      * @stable ICU 50
273      */
274     virtual UnicodeString& getExemplarLocationName(const UnicodeString& tzID, UnicodeString& name) const;
275 
276     /**
277      * Returns the display name of the time zone at the given date.
278      * <p>
279      * <b>Note:</b> This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the
280      * result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the
281      * time zone, then calls {@link #getMetaZoneDisplayName}.
282      *
283      * @param tzID The canonical time zone ID.
284      * @param type The display name type. See {@link #UTimeZoneNameType}.
285      * @param date The date.
286      * @param name Receives the display name for the time zone at the given date. When this object does not have a localized display
287      *          name for the time zone with the specified type and date, "bogus" state is set.
288      * @return A reference to the result.
289      * @stable ICU 50
290      */
291     virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const;
292 
293     /**
294      * @internal For specific users only until proposed publicly.
295      * @deprecated This API is ICU internal only.
296      */
297     virtual void loadAllDisplayNames(UErrorCode& status);
298 
299     /**
300      * @internal For specific users only until proposed publicly.
301      * @deprecated This API is ICU internal only.
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 #endif
417