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