1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 *******************************************************************************
5 * Copyright (C) 2007-2013, International Business Machines Corporation and    *
6 * others. All Rights Reserved.                                                *
7 *******************************************************************************
8 */
9 #ifndef ZONEMETA_H
10 #define ZONEMETA_H
11 
12 #include "unicode/utypes.h"
13 
14 #if !UCONFIG_NO_FORMATTING
15 
16 #include "unicode/unistr.h"
17 #include "hash.h"
18 
19 U_NAMESPACE_BEGIN
20 
21 typedef struct OlsonToMetaMappingEntry {
22     const UChar *mzid; // const because it's a reference to a resource bundle string.
23     UDate from;
24     UDate to;
25 } OlsonToMetaMappingEntry;
26 
27 class UVector;
28 class TimeZone;
29 
30 class U_I18N_API ZoneMeta {
31 public:
32     /**
33      * Return the canonical id for this tzid defined by CLDR, which might be the id itself.
34      * If the given system tzid is not known, U_ILLEGAL_ARGUMENT_ERROR is set in the status.
35      *
36      * Note: this internal API supports all known system IDs and "Etc/Unknown" (which is
37      * NOT a system ID).
38      */
39     static UnicodeString& U_EXPORT2 getCanonicalCLDRID(const UnicodeString &tzid, UnicodeString &systemID, UErrorCode& status);
40 
41     /**
42      * Return the canonical id for this tzid defined by CLDR, which might be the id itself.
43      * This overload method returns a persistent const UChar*, which is guranteed to persist
44      * (a pointer to a resource). If the given system tzid is not known, U_ILLEGAL_ARGUMENT_ERROR
45      * is set in the status.
46      * @param tzid Zone ID
47      * @param status Receives the status
48      * @return The canonical ID for the input time zone ID
49      */
50     static const UChar* U_EXPORT2 getCanonicalCLDRID(const UnicodeString &tzid, UErrorCode& status);
51 
52     /*
53      * Convenient method returning CLDR canonical ID for the given time zone
54      */
55     static const UChar* U_EXPORT2 getCanonicalCLDRID(const TimeZone& tz);
56 
57     /**
58      * Return the canonical country code for this tzid.  If we have none, or if the time zone
59      * is not associated with a country, return bogus string.
60      * @param tzid Zone ID
61      * @param country [output] Country code
62      * @param isPrimary [output] true if the zone is the primary zone for the country
63      * @return A reference to the result country
64      */
65     static UnicodeString& U_EXPORT2 getCanonicalCountry(const UnicodeString &tzid, UnicodeString &country, UBool *isPrimary = NULL);
66 
67     /**
68      * Returns a CLDR metazone ID for the given Olson tzid and time.
69      */
70     static UnicodeString& U_EXPORT2 getMetazoneID(const UnicodeString &tzid, UDate date, UnicodeString &result);
71     /**
72      * Returns an Olson ID for the ginve metazone and region
73      */
74     static UnicodeString& U_EXPORT2 getZoneIdByMetazone(const UnicodeString &mzid, const UnicodeString &region, UnicodeString &result);
75 
76     static const UVector* U_EXPORT2 getMetazoneMappings(const UnicodeString &tzid);
77 
78     static const UVector* U_EXPORT2 getAvailableMetazoneIDs();
79 
80     /**
81      * Returns the pointer to the persistent time zone ID string, or NULL if the given tzid is not in the
82      * tz database. This method is useful when you maintain persistent zone IDs without duplication.
83      */
84     static const UChar* U_EXPORT2 findTimeZoneID(const UnicodeString& tzid);
85 
86     /**
87      * Returns the pointer to the persistent meta zone ID string, or NULL if the given mzid is not available.
88      * This method is useful when you maintain persistent meta zone IDs without duplication.
89      */
90     static const UChar* U_EXPORT2 findMetaZoneID(const UnicodeString& mzid);
91 
92     /**
93      * Creates a custom zone for the offset
94      * @param offset GMT offset in milliseconds
95      * @return A custom TimeZone for the offset with normalized time zone id
96      */
97     static TimeZone* createCustomTimeZone(int32_t offset);
98 
99     /**
100      * Returns the time zone's short ID (null terminated) for the zone.
101      * For example, "uslax" for zone "America/Los_Angeles".
102      * @param tz the time zone
103      * @return the short ID of the time zone, or null if the short ID is not available.
104      */
105     static const UChar* U_EXPORT2 getShortID(const TimeZone& tz);
106 
107     /**
108      * Returns the time zone's short ID (null terminated) for the zone ID.
109      * For example, "uslax" for zone ID "America/Los_Angeles".
110      * @param tz the time zone ID
111      * @return the short ID of the time zone ID, or null if the short ID is not available.
112      */
113     static const UChar* U_EXPORT2 getShortID(const UnicodeString& id);
114 
115 private:
116     ZoneMeta(); // Prevent construction.
117     static UVector* createMetazoneMappings(const UnicodeString &tzid);
118     static UnicodeString& formatCustomID(uint8_t hour, uint8_t min, uint8_t sec, UBool negative, UnicodeString& id);
119     static const UChar* getShortIDFromCanonical(const UChar* canonicalID);
120 };
121 
122 U_NAMESPACE_END
123 
124 #endif /* #if !UCONFIG_NO_FORMATTING */
125 #endif // ZONEMETA_H
126