1// © 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 U_SHOW_CPLUSPLUS_API
19
20#if !UCONFIG_NO_FORMATTING
21
22#include "unicode/uloc.h"
23#include "unicode/unistr.h"
24
25U_CDECL_BEGIN
26
27/**
28 * Constants for time zone display name types.
29 * @stable ICU 50
30 */
31typedef enum UTimeZoneNameType {
32 /**
33 * Unknown display name type.
34 * @stable ICU 50
35 */
36 UTZNM_UNKNOWN = 0x00,
37 /**
38 * Long display name, such as "Eastern Time".
39 * @stable ICU 50
40 */
41 UTZNM_LONG_GENERIC = 0x01,
42 /**
43 * Long display name for standard time, such as "Eastern Standard Time".
44 * @stable ICU 50
45 */
46 UTZNM_LONG_STANDARD = 0x02,
47 /**
48 * Long display name for daylight saving time, such as "Eastern Daylight Time".
49 * @stable ICU 50
50 */
51 UTZNM_LONG_DAYLIGHT = 0x04,
52 /**
53 * Short display name, such as "ET".
54 * @stable ICU 50
55 */
56 UTZNM_SHORT_GENERIC = 0x08,
57 /**
58 * Short display name for standard time, such as "EST".
59 * @stable ICU 50
60 */
61 UTZNM_SHORT_STANDARD = 0x10,
62 /**
63 * Short display name for daylight saving time, such as "EDT".
64 * @stable ICU 50
65 */
66 UTZNM_SHORT_DAYLIGHT = 0x20,
67 /**
68 * Exemplar location name, such as "Los Angeles".
69 * @stable ICU 51
70 */
71 UTZNM_EXEMPLAR_LOCATION = 0x40
72} UTimeZoneNameType;
73
74U_CDECL_END
75
76U_NAMESPACE_BEGIN
77
78class UVector;
79struct MatchInfo;
80
81/**
82 * <code>TimeZoneNames</code> is an abstract class representing the time zone display name data model defined
83 * by <a href="http://www.unicode.org/reports/tr35/">UTS#35 Unicode Locale Data Markup Language (LDML)</a>.
84 * The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared
85 * by multiple time zones. Also a time zone may have multiple meta zone historic mappings.
86 * <p>
87 * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time".
88 * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some
89 * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make
90 * much sense for most of people.
91 * <p>
92 * In <a href="http://cldr.unicode.org/">CLDR</a> (which uses LDML for representing locale data), the display name
93 * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern".
94 * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in
95 * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern".
96 * <p>
97 * Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox"
98 * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone
99 * to meta zones mapping data are stored by date range.
100 *
101 * <p><b>Note:</b>
102 * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper
103 * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone
104 * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See
105 * {@link TimeZone#getCanonicalID(const UnicodeString& id, UnicodeString& canonicalID, UErrorCode& status)} about ICU
106 * canonical time zone IDs.
107 *
108 * <p>
109 * In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may
110 * have a specific name that is not shared with other time zones.
111 *
112 * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also
113 * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only
114 * used for "Europe/London".
115 *
116 * <p>
117 * {@link #getTimeZoneDisplayName} is designed for accessing a name only used by a single time zone.
118 * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation
119 * may provide time zone names only through {@link #getTimeZoneDisplayName}, or only through {@link #getMetaZoneDisplayName},
120 * or both.
121 *
122 * <p>
123 * The default <code>TimeZoneNames</code> implementation returned by {@link #createInstance}
124 * uses the locale data imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone
125 * IDs are shared by all locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs},
126 * {@link #getMetaZoneID}, and {@link #getReferenceZoneID} won't be changed no matter
127 * what locale is used for getting an instance of <code>TimeZoneNames</code>.
128 *
129 * @stable ICU 50
130 */
131class U_I18N_API TimeZoneNames : public UObject {
132public:
133 /**
134 * Destructor.
135 * @stable ICU 50
136 */
137 virtual ~TimeZoneNames();
138
139 /**
140 * Return true if the given TimeZoneNames objects are semantically equal.
141 * @param other the object to be compared with.
142 * @return Return TRUE if the given Format objects are semantically equal.
143 * @stable ICU 50
144 */
145 virtual UBool operator==(const TimeZoneNames& other) const = 0;
146
147 /**
148 * Return true if the given TimeZoneNames objects are not semantically
149 * equal.
150 * @param other the object to be compared with.
151 * @return Return TRUE if the given Format objects are not semantically equal.
152 * @stable ICU 50
153 */
154 UBool operator!=(const TimeZoneNames& other) const { return !operator==(other); }
155
156 /**
157 * Clone this object polymorphically. The caller is responsible
158 * for deleting the result when done.
159 * @return A copy of the object
160 * @stable ICU 50
161 */
162 virtual TimeZoneNames* clone() const = 0;
163
164 /**
165 * Returns an instance of <code>TimeZoneNames</code> for the specified locale.
166 *
167 * @param locale The locale.
168 * @param status Receives the status.
169 * @return An instance of <code>TimeZoneNames</code>
170 * @stable ICU 50
171 */
172 static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
173
174 /**
175 * Returns an instance of <code>TimeZoneNames</code> containing only short specific
176 * zone names (SHORT_STANDARD and SHORT_DAYLIGHT),
177 * compatible with the IANA tz database's zone abbreviations (not localized).
178 * <br>
179 * Note: The input locale is used for resolving ambiguous names (e.g. "IST" is parsed
180 * as Israel Standard Time for Israel, while it is parsed as India Standard Time for
181 * all other regions). The zone names returned by this instance are not localized.
182 * @stable ICU 54
183 */
184 static TimeZoneNames* U_EXPORT2 createTZDBInstance(const Locale& locale, UErrorCode& status);
185
186 /**
187 * Returns an enumeration of all available meta zone IDs.
188 * @param status Receives the status.
189 * @return an enumeration object, owned by the caller.
190 * @stable ICU 50
191 */
192 virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0;
193
194 /**
195 * Returns an enumeration of all available meta zone IDs used by the given time zone.
196 * @param tzID The canoical tiem zone ID.
197 * @param status Receives the status.
198 * @return an enumeration object, owned by the caller.
199 * @stable ICU 50
200 */
201 virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0;
202
203 /**
204 * Returns the meta zone ID for the given canonical time zone ID at the given date.
205 * @param tzID The canonical time zone ID.
206 * @param date The date.
207 * @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
208 * corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state
209 * is set.
210 * @return A reference to the result.
211 * @stable ICU 50
212 */
213 virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0;
214
215 /**
216 * Returns the reference zone ID for the given meta zone ID for the region.
217 *
218 * Note: Each meta zone must have a reference zone associated with a special region "001" (world).
219 * Some meta zones may have region specific reference zone IDs other than the special region
220 * "001". When a meta zone does not have any region specific reference zone IDs, this method
221 * return the reference zone ID for the special region "001" (world).
222 *
223 * @param mzID The meta zone ID.
224 * @param region The region.
225 * @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the
226 * region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state
227 * is set.
228 * @return A reference to the result.
229 * @stable ICU 50
230 */
231 virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0;
232
233 /**
234 * Returns the display name of the meta zone.
235 * @param mzID The meta zone ID.
236 * @param type The display name type. See {@link #UTimeZoneNameType}.
237 * @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given
238 * meta zone with the specified type or the implementation does not provide any display names associated
239 * with meta zones, "bogus" state is set.
240 * @return A reference to the result.
241 * @stable ICU 50
242 */
243 virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
244
245 /**
246 * Returns the display name of the time zone. Unlike {@link #getDisplayName},
247 * this method does not get a name from a meta zone used by the time zone.
248 * @param tzID The canonical time zone ID.
249 * @param type The display name type. See {@link #UTimeZoneNameType}.
250 * @param name Receives the display name for the time zone. When this object does not have a localized display name for the given
251 * time zone with the specified type, "bogus" state is set.
252 * @return A reference to the result.
253 * @stable ICU 50
254 */
255 virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
256
257 /**
258 * Returns the exemplar location name for the given time zone. When this object does not have a localized location
259 * name, the default implementation may still returns a programmatically generated name with the logic described
260 * below.
261 * <ol>
262 * <li>Check if the ID contains "/". If not, return null.
263 * <li>Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null.
264 * <li>Extract a substring after the last occurrence of "/".
265 * <li>Replace "_" with " ".
266 * </ol>
267 * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the
268 * localized location name.
269 *
270 * @param tzID The canonical time zone ID
271 * @param name Receives the exemplar location name for the given time zone, or "bogus" state is set when a localized
272 * location name is not available and the fallback logic described above cannot extract location from the ID.
273 * @return A reference to the result.
274 * @stable ICU 50
275 */
276 virtual UnicodeString& getExemplarLocationName(const UnicodeString& tzID, UnicodeString& name) const;
277
278 /**
279 * Returns the display name of the time zone at the given date.
280 * <p>
281 * <b>Note:</b> This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the
282 * result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the
283 * time zone, then calls {@link #getMetaZoneDisplayName}.
284 *
285 * @param tzID The canonical time zone ID.
286 * @param type The display name type. See {@link #UTimeZoneNameType}.
287 * @param date The date.
288 * @param name Receives the display name for the time zone at the given date. When this object does not have a localized display
289 * name for the time zone with the specified type and date, "bogus" state is set.
290 * @return A reference to the result.
291 * @stable ICU 50
292 */
293 virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const;
294
295 /**
296 * @internal ICU internal only, for specific users only until proposed publicly.
297 */
298 virtual void loadAllDisplayNames(UErrorCode& status);
299
300 /**
301 * @internal ICU internal only, for specific users only until proposed publicly.
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
413U_NAMESPACE_END
414
415#endif
416
417#endif /* U_SHOW_CPLUSPLUS_API */
418
419#endif
420