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
23U_CDECL_BEGIN
24
25/**
26 * Constants for time zone display name types.
27 * @stable ICU 50
28 */
29typedef 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
72U_CDECL_END
73
74U_NAMESPACE_BEGIN
75
76class UVector;
77struct 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 */
129class U_I18N_API TimeZoneNames : public UObject {
130public:
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
413U_NAMESPACE_END
414
415#endif
416#endif
417