Line data Source code
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 !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 0 : 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
|
