1/*
2*******************************************************************************
3* Copyright (C) 2011-2014, International Business Machines Corporation and
4* others. All Rights Reserved.
5*******************************************************************************
6*/
7#ifndef __TZNAMES_H
8#define __TZNAMES_H
9
10/**
11 * \file
12 * \brief C++ API: TimeZoneNames
13 */
14#include "unicode/utypes.h"
15
16#if !UCONFIG_NO_FORMATTING
17
18#include "unicode/uloc.h"
19#include "unicode/unistr.h"
20
21U_CDECL_BEGIN
22
23/**
24 * Constants for time zone display name types.
25 * @stable ICU 50
26 */
27typedef enum UTimeZoneNameType {
28    /**
29     * Unknown display name type.
30     * @stable ICU 50
31     */
32    UTZNM_UNKNOWN           = 0x00,
33    /**
34     * Long display name, such as "Eastern Time".
35     * @stable ICU 50
36     */
37    UTZNM_LONG_GENERIC      = 0x01,
38    /**
39     * Long display name for standard time, such as "Eastern Standard Time".
40     * @stable ICU 50
41     */
42    UTZNM_LONG_STANDARD     = 0x02,
43    /**
44     * Long display name for daylight saving time, such as "Eastern Daylight Time".
45     * @stable ICU 50
46     */
47    UTZNM_LONG_DAYLIGHT     = 0x04,
48    /**
49     * Short display name, such as "ET".
50     * @stable ICU 50
51     */
52    UTZNM_SHORT_GENERIC     = 0x08,
53    /**
54     * Short display name for standard time, such as "EST".
55     * @stable ICU 50
56     */
57    UTZNM_SHORT_STANDARD    = 0x10,
58    /**
59     * Short display name for daylight saving time, such as "EDT".
60     * @stable ICU 50
61     */
62    UTZNM_SHORT_DAYLIGHT    = 0x20,
63    /**
64     * Exemplar location name, such as "Los Angeles".
65     * @stable ICU 51
66     */
67    UTZNM_EXEMPLAR_LOCATION = 0x40
68} UTimeZoneNameType;
69
70U_CDECL_END
71
72U_NAMESPACE_BEGIN
73
74class UVector;
75struct MatchInfo;
76
77/**
78 * <code>TimeZoneNames</code> is an abstract class representing the time zone display name data model defined
79 * by <a href="http://www.unicode.org/reports/tr35/">UTS#35 Unicode Locale Data Markup Language (LDML)</a>.
80 * The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared
81 * by multiple time zones. Also a time zone may have multiple meta zone historic mappings.
82 * <p>
83 * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time".
84 * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some
85 * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make
86 * much sense for most of people.
87 * <p>
88 * In <a href="http://cldr.unicode.org/">CLDR</a> (which uses LDML for representing locale data), the display name
89 * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern".
90 * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in
91 * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern".
92 * <p>
93 * Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox"
94 * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone
95 * to meta zones mapping data are stored by date range.
96 *
97 * <p><b>Note:</b>
98 * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper
99 * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone
100 * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See
101 * {@link TimeZone#getCanonicalID(const UnicodeString& id, UnicodeString& canonicalID, UErrorCode& status)} about ICU
102 * canonical time zone IDs.
103 *
104 * <p>
105 * In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may
106 * have a specific name that is not shared with other time zones.
107 *
108 * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also
109 * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only
110 * used for "Europe/London".
111 *
112 * <p>
113 * {@link #getTimeZoneDisplayName} is designed for accessing a name only used by a single time zone.
114 * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation
115 * may provide time zone names only through {@link #getTimeZoneDisplayName}, or only through {@link #getMetaZoneDisplayName},
116 * or both.
117 *
118 * <p>
119 * The default <code>TimeZoneNames</code> implementation returned by {@link #createInstance}
120 * uses the locale data imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone
121 * IDs are shared by all locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs},
122 * {@link #getMetaZoneID}, and {@link #getReferenceZoneID} won't be changed no matter
123 * what locale is used for getting an instance of <code>TimeZoneNames</code>.
124 *
125 * @stable ICU 50
126 */
127class U_I18N_API TimeZoneNames : public UObject {
128public:
129    /**
130     * Destructor.
131     * @stable ICU 50
132     */
133    virtual ~TimeZoneNames();
134
135    /**
136     * Return true if the given TimeZoneNames objects are emantically equal.
137     * @param other the object to be compared with.
138     * @return Return TRUE if the given Format objects are semantically equal.
139     * @stable ICU 50
140     */
141    virtual UBool operator==(const TimeZoneNames& other) const = 0;
142
143    /**
144     * Return true if the given TimeZoneNames objects are not semantically
145     * equal.
146     * @param other the object to be compared with.
147     * @return Return TRUE if the given Format objects are not semantically equal.
148     * @stable ICU 50
149     */
150    UBool operator!=(const TimeZoneNames& other) const { return !operator==(other); }
151
152    /**
153     * Clone this object polymorphically.  The caller is responsible
154     * for deleting the result when done.
155     * @return A copy of the object
156     * @stable ICU 50
157     */
158    virtual TimeZoneNames* clone() const = 0;
159
160    /**
161     * Returns an instance of <code>TimeZoneDisplayNames</code> for the specified locale.
162     *
163     * @param locale The locale.
164     * @param status Receives the status.
165     * @return An instance of <code>TimeZoneDisplayNames</code>
166     * @stable ICU 50
167     */
168    static TimeZoneNames* U_EXPORT2 createInstance(const Locale& locale, UErrorCode& status);
169
170    /**
171     * Returns an enumeration of all available meta zone IDs.
172     * @param status Receives the status.
173     * @return an enumeration object, owned by the caller.
174     * @stable ICU 50
175     */
176    virtual StringEnumeration* getAvailableMetaZoneIDs(UErrorCode& status) const = 0;
177
178    /**
179     * Returns an enumeration of all available meta zone IDs used by the given time zone.
180     * @param tzID The canoical tiem zone ID.
181     * @param status Receives the status.
182     * @return an enumeration object, owned by the caller.
183     * @stable ICU 50
184     */
185    virtual StringEnumeration* getAvailableMetaZoneIDs(const UnicodeString& tzID, UErrorCode& status) const = 0;
186
187    /**
188     * Returns the meta zone ID for the given canonical time zone ID at the given date.
189     * @param tzID The canonical time zone ID.
190     * @param date The date.
191     * @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
192     *          corresponding meta zone at the given date or the implementation does not support meta zones, "bogus" state
193     *          is set.
194     * @return A reference to the result.
195     * @stable ICU 50
196     */
197    virtual UnicodeString& getMetaZoneID(const UnicodeString& tzID, UDate date, UnicodeString& mzID) const = 0;
198
199    /**
200     * Returns the reference zone ID for the given meta zone ID for the region.
201     *
202     * Note: Each meta zone must have a reference zone associated with a special region "001" (world).
203     * Some meta zones may have region specific reference zone IDs other than the special region
204     * "001". When a meta zone does not have any region specific reference zone IDs, this method
205     * return the reference zone ID for the special region "001" (world).
206     *
207     * @param mzID The meta zone ID.
208     * @param region The region.
209     * @param tzID Receives the reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the
210     *          region. If the meta zone is unknown or the implementation does not support meta zones, "bogus" state
211     *          is set.
212     * @return A reference to the result.
213     * @stable ICU 50
214     */
215    virtual UnicodeString& getReferenceZoneID(const UnicodeString& mzID, const char* region, UnicodeString& tzID) const = 0;
216
217    /**
218     * Returns the display name of the meta zone.
219     * @param mzID The meta zone ID.
220     * @param type The display name type. See {@link #UTimeZoneNameType}.
221     * @param name Receives the display name of the meta zone. When this object does not have a localized display name for the given
222     *         meta zone with the specified type or the implementation does not provide any display names associated
223     *         with meta zones, "bogus" state is set.
224     * @return A reference to the result.
225     * @stable ICU 50
226     */
227    virtual UnicodeString& getMetaZoneDisplayName(const UnicodeString& mzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
228
229    /**
230     * Returns the display name of the time zone. Unlike {@link #getDisplayName},
231     * this method does not get a name from a meta zone used by the time zone.
232     * @param tzID The canonical time zone ID.
233     * @param type The display name type. See {@link #UTimeZoneNameType}.
234     * @param name Receives the display name for the time zone. When this object does not have a localized display name for the given
235     *         time zone with the specified type, "bogus" state is set.
236     * @return A reference to the result.
237     * @stable ICU 50
238     */
239    virtual UnicodeString& getTimeZoneDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UnicodeString& name) const = 0;
240
241    /**
242     * Returns the exemplar location name for the given time zone. When this object does not have a localized location
243     * name, the default implementation may still returns a programmatically generated name with the logic described
244     * below.
245     * <ol>
246     * <li>Check if the ID contains "/". If not, return null.
247     * <li>Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null.
248     * <li>Extract a substring after the last occurrence of "/".
249     * <li>Replace "_" with " ".
250     * </ol>
251     * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the
252     * localized location name.
253     *
254     * @param tzID The canonical time zone ID
255     * @param name Receives the exemplar location name for the given time zone, or "bogus" state is set when a localized
256     *          location name is not available and the fallback logic described above cannot extract location from the ID.
257     * @return A reference to the result.
258     * @stable ICU 50
259     */
260    virtual UnicodeString& getExemplarLocationName(const UnicodeString& tzID, UnicodeString& name) const;
261
262    /**
263     * Returns the display name of the time zone at the given date.
264     * <p>
265     * <b>Note:</b> This method calls the subclass's {@link #getTimeZoneDisplayName} first. When the
266     * result is bogus, this method calls {@link #getMetaZoneID} to get the meta zone ID mapped from the
267     * time zone, then calls {@link #getMetaZoneDisplayName}.
268     *
269     * @param tzID The canonical time zone ID.
270     * @param type The display name type. See {@link #UTimeZoneNameType}.
271     * @param date The date.
272     * @param name Receives the display name for the time zone at the given date. When this object does not have a localized display
273     *          name for the time zone with the specified type and date, "bogus" state is set.
274     * @return A reference to the result.
275     * @stable ICU 50
276     */
277    virtual UnicodeString& getDisplayName(const UnicodeString& tzID, UTimeZoneNameType type, UDate date, UnicodeString& name) const;
278
279    /**
280     * <code>MatchInfoCollection</code> represents a collection of time zone name matches used by
281     * {@link TimeZoneNames#find}.
282     * @internal
283     */
284    class U_I18N_API MatchInfoCollection : public UMemory {
285    public:
286        /**
287         * Constructor.
288         * @internal
289         */
290        MatchInfoCollection();
291        /**
292         * Destructor.
293         * @internal
294         */
295        virtual ~MatchInfoCollection();
296
297#ifndef U_HIDE_INTERNAL_API
298        /**
299         * Adds a zone match.
300         * @param nameType The name type.
301         * @param matchLength The match length.
302         * @param tzID The time zone ID.
303         * @param status Receives the status
304         * @internal
305         */
306        void addZone(UTimeZoneNameType nameType, int32_t matchLength,
307            const UnicodeString& tzID, UErrorCode& status);
308
309        /**
310         * Adds a meata zone match.
311         * @param nameType The name type.
312         * @param matchLength The match length.
313         * @param mzID The metazone ID.
314         * @param status Receives the status
315         * @internal
316         */
317        void addMetaZone(UTimeZoneNameType nameType, int32_t matchLength,
318            const UnicodeString& mzID, UErrorCode& status);
319
320        /**
321         * Returns the number of entries available in this object.
322         * @return The number of entries.
323         * @internal
324         */
325        int32_t size() const;
326
327        /**
328         * Returns the time zone name type of a match at the specified index.
329         * @param idx The index
330         * @return The time zone name type. If the specified idx is out of range,
331         *      it returns UTZNM_UNKNOWN.
332         * @see UTimeZoneNameType
333         * @internal
334         */
335        UTimeZoneNameType getNameTypeAt(int32_t idx) const;
336
337        /**
338         * Returns the match length of a match at the specified index.
339         * @param idx The index
340         * @return The match length. If the specified idx is out of range,
341         *      it returns 0.
342         * @internal
343         */
344        int32_t getMatchLengthAt(int32_t idx) const;
345
346        /**
347         * Gets the zone ID of a match at the specified index.
348         * @param idx The index
349         * @param tzID Receives the zone ID.
350         * @return TRUE if the zone ID was set to tzID.
351         * @internal
352         */
353        UBool getTimeZoneIDAt(int32_t idx, UnicodeString& tzID) const;
354
355        /**
356         * Gets the metazone ID of a match at the specified index.
357         * @param idx The index
358         * @param mzID Receives the metazone ID
359         * @return TRUE if the meta zone ID was set to mzID.
360         * @internal
361         */
362        UBool getMetaZoneIDAt(int32_t idx, UnicodeString& mzID) const;
363#endif  /* U_HIDE_INTERNAL_API */
364
365    private:
366        UVector* fMatches;  // vector of MatchEntry
367
368        UVector* matches(UErrorCode& status);
369    };
370
371    /**
372     * Finds time zone name prefix matches for the input text at the
373     * given offset and returns a collection of the matches.
374     * @param text The text.
375     * @param start The starting offset within the text.
376     * @param types The set of name types represented by bitwise flags of UTimeZoneNameType enums,
377     *              or UTZNM_UNKNOWN for all name types.
378     * @param status Receives the status.
379     * @return A collection of matches (owned by the caller), or NULL if no matches are found.
380     * @see UTimeZoneNameType
381     * @see MatchInfoCollection
382     * @internal
383     */
384    virtual MatchInfoCollection* find(const UnicodeString& text, int32_t start, uint32_t types, UErrorCode& status) const = 0;
385};
386
387U_NAMESPACE_END
388
389#endif
390#endif
391