OLD | NEW |
1 /* | 1 /* |
2 ******************************************************************************* | 2 ******************************************************************************* |
3 * Copyright (C) 2013, International Business Machines Corporation and others. | 3 * Copyright (C) 2014, International Business Machines Corporation and others. |
4 * All Rights Reserved. | 4 * All Rights Reserved. |
5 ******************************************************************************* | 5 ******************************************************************************* |
6 */ | 6 */ |
7 | 7 |
8 #ifndef REGION_H | 8 #ifndef REGION_H |
9 #define REGION_H | 9 #define REGION_H |
10 | 10 |
11 /** | 11 /** |
12 * \file | 12 * \file |
13 * \brief C++ API: Region classes (territory containment) | 13 * \brief C++ API: Region classes (territory containment) |
14 */ | 14 */ |
15 | 15 |
16 #include "unicode/utypes.h" | 16 #include "unicode/utypes.h" |
17 #include "unicode/uregion.h" | 17 #include "unicode/uregion.h" |
18 | 18 |
19 #if !UCONFIG_NO_FORMATTING | 19 #if !UCONFIG_NO_FORMATTING |
20 #ifndef U_HIDE_DRAFT_API | |
21 | 20 |
22 #include "unicode/uobject.h" | 21 #include "unicode/uobject.h" |
23 #include "unicode/uniset.h" | 22 #include "unicode/uniset.h" |
24 #include "unicode/unistr.h" | 23 #include "unicode/unistr.h" |
25 #include "unicode/strenum.h" | 24 #include "unicode/strenum.h" |
26 | 25 |
27 U_NAMESPACE_BEGIN | 26 U_NAMESPACE_BEGIN |
28 | 27 |
29 /** | 28 /** |
30 * <code>Region</code> is the class representing a Unicode Region Code, also kno
wn as a | 29 * <code>Region</code> is the class representing a Unicode Region Code, also kno
wn as a |
(...skipping 25 matching lines...) Expand all Loading... |
56 * GROUPING - A widely understood grouping of territories that has a well defin
ed membership such | 55 * GROUPING - A widely understood grouping of territories that has a well defin
ed membership such |
57 * that a region code has been assigned for it. Some of these are UNM.49 codes
that do't fall into | 56 * that a region code has been assigned for it. Some of these are UNM.49 codes
that do't fall into |
58 * the world/continent/sub-continent hierarchy, while others are just well know
n groupings that have | 57 * the world/continent/sub-continent hierarchy, while others are just well know
n groupings that have |
59 * their own region code. Region "EU" (European Union) is one such region code
that is a grouping. | 58 * their own region code. Region "EU" (European Union) is one such region code
that is a grouping. |
60 * Groupings will never be returned by the getContainingRegion() API, since a d
ifferent type of region | 59 * Groupings will never be returned by the getContainingRegion() API, since a d
ifferent type of region |
61 * ( WORLD, CONTINENT, or SUBCONTINENT ) will always be the containing region i
nstead. | 60 * ( WORLD, CONTINENT, or SUBCONTINENT ) will always be the containing region i
nstead. |
62 * | 61 * |
63 * The Region class is not intended for public subclassing. | 62 * The Region class is not intended for public subclassing. |
64 * | 63 * |
65 * @author John Emmons | 64 * @author John Emmons |
66 * @draft ICU 51 | 65 * @stable ICU 51 |
67 */ | 66 */ |
68 | 67 |
69 class U_I18N_API Region : public UObject { | 68 class U_I18N_API Region : public UObject { |
70 public: | 69 public: |
71 /** | 70 /** |
72 * Destructor. | 71 * Destructor. |
73 * @draft ICU 51 | 72 * @stable ICU 51 |
74 */ | 73 */ |
75 virtual ~Region(); | 74 virtual ~Region(); |
76 | 75 |
77 /** | 76 /** |
78 * Returns true if the two regions are equal. | 77 * Returns true if the two regions are equal. |
79 * @draft ICU 51 | 78 * @stable ICU 51 |
80 */ | 79 */ |
81 UBool operator==(const Region &that) const; | 80 UBool operator==(const Region &that) const; |
82 | 81 |
83 /** | 82 /** |
84 * Returns true if the two regions are NOT equal; that is, if operator ==()
returns false. | 83 * Returns true if the two regions are NOT equal; that is, if operator ==()
returns false. |
85 * @draft ICU 51 | 84 * @stable ICU 51 |
86 */ | 85 */ |
87 UBool operator!=(const Region &that) const; | 86 UBool operator!=(const Region &that) const; |
88 | 87 |
89 /** | 88 /** |
90 * Returns a pointer to a Region using the given region code. The region co
de can be either 2-letter ISO code, | 89 * Returns a pointer to a Region using the given region code. The region co
de can be either 2-letter ISO code, |
91 * 3-letter ISO code, UNM.49 numeric code, or other valid Unicode Region Co
de as defined by the LDML specification. | 90 * 3-letter ISO code, UNM.49 numeric code, or other valid Unicode Region Co
de as defined by the LDML specification. |
92 * The identifier will be canonicalized internally using the supplemental me
tadata as defined in the CLDR. | 91 * The identifier will be canonicalized internally using the supplemental me
tadata as defined in the CLDR. |
93 * If the region code is NULL or not recognized, the appropriate error code
will be set ( U_ILLEGAL_ARGUMENT_ERROR ) | 92 * If the region code is NULL or not recognized, the appropriate error code
will be set ( U_ILLEGAL_ARGUMENT_ERROR ) |
94 * @draft ICU 51 | 93 * @stable ICU 51 |
95 */ | 94 */ |
96 static const Region* U_EXPORT2 getInstance(const char *region_code, UErrorCo
de &status); | 95 static const Region* U_EXPORT2 getInstance(const char *region_code, UErrorCo
de &status); |
97 | 96 |
98 /** | 97 /** |
99 * Returns a pointer to a Region using the given numeric region code. If the
numeric region code is not recognized, | 98 * Returns a pointer to a Region using the given numeric region code. If the
numeric region code is not recognized, |
100 * the appropriate error code will be set ( U_ILLEGAL_ARGUMENT_ERROR ). | 99 * the appropriate error code will be set ( U_ILLEGAL_ARGUMENT_ERROR ). |
101 * @draft ICU 51 | 100 * @stable ICU 51 |
102 */ | 101 */ |
103 static const Region* U_EXPORT2 getInstance (int32_t code, UErrorCode &status
); | 102 static const Region* U_EXPORT2 getInstance (int32_t code, UErrorCode &status
); |
104 | 103 |
| 104 #ifndef U_HIDE_DRAFT_API |
105 /** | 105 /** |
106 * Returns an enumeration over the IDs of all known regions that match the g
iven type. | 106 * Returns an enumeration over the IDs of all known regions that match the g
iven type. |
107 * @draft ICU 51 | 107 * @draft ICU 51 |
108 */ | 108 */ |
109 static StringEnumeration* U_EXPORT2 getAvailable(URegionType type); | 109 static StringEnumeration* U_EXPORT2 getAvailable(URegionType type); |
| 110 #endif /* U_HIDE_DRAFT_API */ |
110 | 111 |
111 /** | 112 /** |
112 * Returns a pointer to the region that contains this region. Returns NULL
if this region is code "001" (World) | 113 * Returns a pointer to the region that contains this region. Returns NULL
if this region is code "001" (World) |
113 * or "ZZ" (Unknown region). For example, calling this method with region "I
T" (Italy) returns the | 114 * or "ZZ" (Unknown region). For example, calling this method with region "I
T" (Italy) returns the |
114 * region "039" (Southern Europe). | 115 * region "039" (Southern Europe). |
115 * @draft ICU 51 | 116 * @stable ICU 51 |
116 */ | 117 */ |
117 const Region* getContainingRegion() const; | 118 const Region* getContainingRegion() const; |
118 | 119 |
119 /** | 120 /** |
120 * Return a pointer to the region that geographically contains this region a
nd matches the given type, | 121 * Return a pointer to the region that geographically contains this region a
nd matches the given type, |
121 * moving multiple steps up the containment chain if necessary. Returns NUL
L if no containing region can be found | 122 * moving multiple steps up the containment chain if necessary. Returns NUL
L if no containing region can be found |
122 * that matches the given type. Note: The URegionTypes = "URGN_GROUPING", "U
RGN_DEPRECATED", or "URGN_UNKNOWN" | 123 * that matches the given type. Note: The URegionTypes = "URGN_GROUPING", "U
RGN_DEPRECATED", or "URGN_UNKNOWN" |
123 * are not appropriate for use in this API. NULL will be returned in this ca
se. For example, calling this method | 124 * are not appropriate for use in this API. NULL will be returned in this ca
se. For example, calling this method |
124 * with region "IT" (Italy) for type "URGN_CONTINENT" returns the region "15
0" ( Europe ). | 125 * with region "IT" (Italy) for type "URGN_CONTINENT" returns the region "15
0" ( Europe ). |
125 * @draft ICU 51 | 126 * @stable ICU 51 |
126 */ | 127 */ |
127 const Region* getContainingRegion(URegionType type) const; | 128 const Region* getContainingRegion(URegionType type) const; |
128 | 129 |
| 130 #ifndef U_HIDE_DRAFT_API |
129 /** | 131 /** |
130 * Return an enumeration over the IDs of all the regions that are immediate
children of this region in the | 132 * Return an enumeration over the IDs of all the regions that are immediate
children of this region in the |
131 * region hierarchy. These returned regions could be either macro regions, t
erritories, or a mixture of the two, | 133 * region hierarchy. These returned regions could be either macro regions, t
erritories, or a mixture of the two, |
132 * depending on the containment data as defined in CLDR. This API may retur
n NULL if this region doesn't have | 134 * depending on the containment data as defined in CLDR. This API may retur
n NULL if this region doesn't have |
133 * any sub-regions. For example, calling this method with region "150" (Euro
pe) returns an enumeration containing | 135 * any sub-regions. For example, calling this method with region "150" (Euro
pe) returns an enumeration containing |
134 * the various sub regions of Europe - "039" (Southern Europe) - "151" (East
ern Europe) - "154" (Northern Europe) | 136 * the various sub regions of Europe - "039" (Southern Europe) - "151" (East
ern Europe) - "154" (Northern Europe) |
135 * and "155" (Western Europe). | 137 * and "155" (Western Europe). |
136 * @draft ICU 51 | 138 * @draft ICU 51 |
137 */ | 139 */ |
138 StringEnumeration* getContainedRegions() const; | 140 StringEnumeration* getContainedRegions() const; |
139 | 141 |
140 /** | 142 /** |
141 * Returns an enumeration over the IDs of all the regions that are children
of this region anywhere in the region | 143 * Returns an enumeration over the IDs of all the regions that are children
of this region anywhere in the region |
142 * hierarchy and match the given type. This API may return an empty enumera
tion if this region doesn't have any | 144 * hierarchy and match the given type. This API may return an empty enumera
tion if this region doesn't have any |
143 * sub-regions that match the given type. For example, calling this method w
ith region "150" (Europe) and type | 145 * sub-regions that match the given type. For example, calling this method w
ith region "150" (Europe) and type |
144 * "URGN_TERRITORY" returns a set containing all the territories in Europe (
"FR" (France) - "IT" (Italy) - "DE" (Germany) etc. ) | 146 * "URGN_TERRITORY" returns a set containing all the territories in Europe (
"FR" (France) - "IT" (Italy) - "DE" (Germany) etc. ) |
145 * @draft ICU 51 | 147 * @draft ICU 51 |
146 */ | 148 */ |
147 StringEnumeration* getContainedRegions( URegionType type ) const; | 149 StringEnumeration* getContainedRegions( URegionType type ) const; |
| 150 #endif /* U_HIDE_DRAFT_API */ |
148 | 151 |
149 /** | 152 /** |
150 * Returns true if this region contains the supplied other region anywhere i
n the region hierarchy. | 153 * Returns true if this region contains the supplied other region anywhere i
n the region hierarchy. |
151 * @draft ICU 51 | 154 * @stable ICU 51 |
152 */ | 155 */ |
153 UBool contains(const Region &other) const; | 156 UBool contains(const Region &other) const; |
154 | 157 |
| 158 #ifndef U_HIDE_DRAFT_API |
155 /** | 159 /** |
156 * For deprecated regions, return an enumeration over the IDs of the regions
that are the preferred replacement | 160 * For deprecated regions, return an enumeration over the IDs of the regions
that are the preferred replacement |
157 * regions for this region. Returns null for a non-deprecated region. For
example, calling this method with region | 161 * regions for this region. Returns null for a non-deprecated region. For
example, calling this method with region |
158 * "SU" (Soviet Union) would return a list of the regions containing "RU" (R
ussia), "AM" (Armenia), "AZ" (Azerbaijan), etc... | 162 * "SU" (Soviet Union) would return a list of the regions containing "RU" (R
ussia), "AM" (Armenia), "AZ" (Azerbaijan), etc... |
159 * @draft ICU 51 | 163 * @draft ICU 51 |
160 */ | 164 */ |
161 StringEnumeration* getPreferredValues() const; | 165 StringEnumeration* getPreferredValues() const; |
162 | 166 #endif /* U_HIDE_DRAFT_API */ |
163 | 167 |
164 /** | 168 /** |
165 * Return this region's canonical region code. | 169 * Return this region's canonical region code. |
166 * @draft ICU 51 | 170 * @stable ICU 51 |
167 */ | 171 */ |
168 const char* getRegionCode() const; | 172 const char* getRegionCode() const; |
169 | 173 |
170 /** | 174 /** |
171 * Return this region's numeric code. | 175 * Return this region's numeric code. |
172 * Returns a negative value if the given region does not have a numeric code
assigned to it. | 176 * Returns a negative value if the given region does not have a numeric code
assigned to it. |
173 * @draft ICU 51 | 177 * @stable ICU 51 |
174 */ | 178 */ |
175 int32_t getNumericCode() const; | 179 int32_t getNumericCode() const; |
176 | 180 |
177 /** | 181 /** |
178 * Returns the region type of this region. | 182 * Returns the region type of this region. |
179 * @draft ICU 51 | 183 * @stable ICU 51 |
180 */ | 184 */ |
181 URegionType getType() const; | 185 URegionType getType() const; |
182 | 186 |
183 #ifndef U_HIDE_INTERNAL_API | 187 #ifndef U_HIDE_INTERNAL_API |
184 /** | 188 /** |
185 * Cleans up statically allocated memory. | 189 * Cleans up statically allocated memory. |
186 * @internal | 190 * @internal |
187 */ | 191 */ |
188 static void cleanupRegionData(); | 192 static void cleanupRegionData(); |
189 #endif /* U_HIDE_INTERNAL_API */ | 193 #endif /* U_HIDE_INTERNAL_API */ |
(...skipping 15 matching lines...) Expand all Loading... |
205 | 209 |
206 /* | 210 /* |
207 * Initializes the region data from the ICU resource bundles. The region da
ta | 211 * Initializes the region data from the ICU resource bundles. The region da
ta |
208 * contains the basic relationships such as which regions are known, what th
e numeric | 212 * contains the basic relationships such as which regions are known, what th
e numeric |
209 * codes are, any known aliases, and the territory containment data. | 213 * codes are, any known aliases, and the territory containment data. |
210 * | 214 * |
211 * If the region data has already loaded, then this method simply returns wi
thout doing | 215 * If the region data has already loaded, then this method simply returns wi
thout doing |
212 * anything meaningful. | 216 * anything meaningful. |
213 */ | 217 */ |
214 | 218 |
215 static void loadRegionData(); | 219 static void loadRegionData(UErrorCode &status); |
216 | 220 |
217 }; | 221 }; |
218 | 222 |
219 U_NAMESPACE_END | 223 U_NAMESPACE_END |
220 | 224 |
221 #endif /* U_HIDE_DRAFT_API */ | |
222 #endif /* #if !UCONFIG_NO_FORMATTING */ | 225 #endif /* #if !UCONFIG_NO_FORMATTING */ |
223 #endif // REGION_H | 226 #endif // REGION_H |
224 | 227 |
225 //eof | 228 //eof |
OLD | NEW |