OLD | NEW |
1 /* | 1 /* |
2 ********************************************************************************
********* | 2 ********************************************************************************
********* |
3 * Copyright (C) 2013, International Business Machines | 3 * Copyright (C) 2014, International Business Machines |
4 * Corporation and others. All Rights Reserved. | 4 * Corporation and others. All Rights Reserved. |
5 ********************************************************************************
********* | 5 ********************************************************************************
********* |
6 */ | 6 */ |
7 | 7 |
8 #ifndef UREGION_H | 8 #ifndef UREGION_H |
9 #define UREGION_H | 9 #define UREGION_H |
10 | 10 |
11 #include "unicode/utypes.h" | 11 #include "unicode/utypes.h" |
12 #include "unicode/uenum.h" | 12 #include "unicode/uenum.h" |
13 | 13 |
(...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
46 * that a region code has been assigned for it. Some of these are UN M.49 codes
that don't fall into | 46 * that a region code has been assigned for it. Some of these are UN M.49 codes
that don't fall into |
47 * the world/continent/sub-continent hierarchy, while others are just well-known
groupings that have | 47 * the world/continent/sub-continent hierarchy, while others are just well-known
groupings that have |
48 * their own region code. Region "EU" (European Union) is one such region code t
hat is a grouping. | 48 * their own region code. Region "EU" (European Union) is one such region code t
hat is a grouping. |
49 * Groupings will never be returned by the uregion_getContainingRegion, since a
different type of region | 49 * Groupings will never be returned by the uregion_getContainingRegion, since a
different type of region |
50 * (WORLD, CONTINENT, or SUBCONTINENT) will always be the containing region inst
ead. | 50 * (WORLD, CONTINENT, or SUBCONTINENT) will always be the containing region inst
ead. |
51 * | 51 * |
52 * URegion objects are const/immutable, owned and maintained by ICU itself, so t
here are not functions | 52 * URegion objects are const/immutable, owned and maintained by ICU itself, so t
here are not functions |
53 * to open or close them. | 53 * to open or close them. |
54 */ | 54 */ |
55 | 55 |
56 #ifndef U_HIDE_DRAFT_API | |
57 /** | 56 /** |
58 * URegionType is an enumeration defining the different types of regions. Curre
nt possible | 57 * URegionType is an enumeration defining the different types of regions. Curre
nt possible |
59 * values are URGN_WORLD, URGN_CONTINENT, URGN_SUBCONTINENT, URGN_TERRITORY, URG
N_GROUPING, | 58 * values are URGN_WORLD, URGN_CONTINENT, URGN_SUBCONTINENT, URGN_TERRITORY, URG
N_GROUPING, |
60 * URGN_DEPRECATED, and URGN_UNKNOWN. | 59 * URGN_DEPRECATED, and URGN_UNKNOWN. |
61 * | 60 * |
62 * @draft ICU 51 | 61 * @stable ICU 51 |
63 */ | 62 */ |
64 typedef enum URegionType { | 63 typedef enum URegionType { |
65 /** | 64 /** |
66 * Type representing the unknown region. | 65 * Type representing the unknown region. |
67 * @draft ICU 51 | 66 * @stable ICU 51 |
68 */ | 67 */ |
69 URGN_UNKNOWN, | 68 URGN_UNKNOWN, |
70 | 69 |
71 /** | 70 /** |
72 * Type representing a territory. | 71 * Type representing a territory. |
73 * @draft ICU 51 | 72 * @stable ICU 51 |
74 */ | 73 */ |
75 URGN_TERRITORY, | 74 URGN_TERRITORY, |
76 | 75 |
77 /** | 76 /** |
78 * Type representing the whole world. | 77 * Type representing the whole world. |
79 * @draft ICU 51 | 78 * @stable ICU 51 |
80 */ | 79 */ |
81 URGN_WORLD, | 80 URGN_WORLD, |
82 | 81 |
83 /** | 82 /** |
84 * Type representing a continent. | 83 * Type representing a continent. |
85 * @draft ICU 51 | 84 * @stable ICU 51 |
86 */ | 85 */ |
87 URGN_CONTINENT, | 86 URGN_CONTINENT, |
88 | 87 |
89 /** | 88 /** |
90 * Type representing a sub-continent. | 89 * Type representing a sub-continent. |
91 * @draft ICU 51 | 90 * @stable ICU 51 |
92 */ | 91 */ |
93 URGN_SUBCONTINENT, | 92 URGN_SUBCONTINENT, |
94 | 93 |
95 /** | 94 /** |
96 * Type representing a grouping of territories that is not to be used in | 95 * Type representing a grouping of territories that is not to be used in |
97 * the normal WORLD/CONTINENT/SUBCONTINENT/TERRITORY containment tree. | 96 * the normal WORLD/CONTINENT/SUBCONTINENT/TERRITORY containment tree. |
98 * @draft ICU 51 | 97 * @stable ICU 51 |
99 */ | 98 */ |
100 URGN_GROUPING, | 99 URGN_GROUPING, |
101 | 100 |
102 /** | 101 /** |
103 * Type representing a region whose code has been deprecated, usually | 102 * Type representing a region whose code has been deprecated, usually |
104 * due to a country splitting into multiple territories or changing its name
. | 103 * due to a country splitting into multiple territories or changing its name
. |
105 * @draft ICU 51 | 104 * @stable ICU 51 |
106 */ | 105 */ |
107 URGN_DEPRECATED, | 106 URGN_DEPRECATED, |
108 | 107 |
109 /** | 108 /** |
110 * Maximum value for this unumeration. | 109 * Maximum value for this unumeration. |
111 * @draft ICU 51 | 110 * @stable ICU 51 |
112 */ | 111 */ |
113 URGN_LIMIT | 112 URGN_LIMIT |
114 } URegionType; | 113 } URegionType; |
115 #endif /* U_HIDE_DRAFT_API */ | |
116 | 114 |
117 #if !UCONFIG_NO_FORMATTING | 115 #if !UCONFIG_NO_FORMATTING |
118 | 116 |
119 #ifndef U_HIDE_DRAFT_API | |
120 | |
121 /** | 117 /** |
122 * Opaque URegion object for use in C programs. | 118 * Opaque URegion object for use in C programs. |
123 * @draft ICU 52 | 119 * @stable ICU 52 |
124 */ | 120 */ |
125 struct URegion; | 121 struct URegion; |
126 typedef struct URegion URegion; /**< @draft ICU 52 */ | 122 typedef struct URegion URegion; /**< @stable ICU 52 */ |
127 | 123 |
128 /** | 124 /** |
129 * Returns a pointer to a URegion for the specified region code: A 2-letter or 3
-letter ISO 3166 | 125 * Returns a pointer to a URegion for the specified region code: A 2-letter or 3
-letter ISO 3166 |
130 * code, UN M.49 numeric code (superset of ISO 3166 numeric codes), or other val
id Unicode Region | 126 * code, UN M.49 numeric code (superset of ISO 3166 numeric codes), or other val
id Unicode Region |
131 * Code as defined by the LDML specification. The code will be canonicalized int
ernally. If the | 127 * Code as defined by the LDML specification. The code will be canonicalized int
ernally. If the |
132 * region code is NULL or not recognized, the appropriate error code will be set | 128 * region code is NULL or not recognized, the appropriate error code will be set |
133 * (U_ILLEGAL_ARGUMENT_ERROR). | 129 * (U_ILLEGAL_ARGUMENT_ERROR). |
134 * @draft ICU 52 | 130 * @stable ICU 52 |
135 */ | 131 */ |
136 U_DRAFT const URegion* U_EXPORT2 | 132 U_STABLE const URegion* U_EXPORT2 |
137 uregion_getRegionFromCode(const char *regionCode, UErrorCode *status); | 133 uregion_getRegionFromCode(const char *regionCode, UErrorCode *status); |
138 | 134 |
139 /** | 135 /** |
140 * Returns a pointer to a URegion for the specified numeric region code. If the
numeric region | 136 * Returns a pointer to a URegion for the specified numeric region code. If the
numeric region |
141 * code is not recognized, the appropriate error code will be set (U_ILLEGAL_ARG
UMENT_ERROR). | 137 * code is not recognized, the appropriate error code will be set (U_ILLEGAL_ARG
UMENT_ERROR). |
142 * @draft ICU 52 | 138 * @stable ICU 52 |
143 */ | 139 */ |
144 U_DRAFT const URegion* U_EXPORT2 | 140 U_STABLE const URegion* U_EXPORT2 |
145 uregion_getRegionFromNumericCode (int32_t code, UErrorCode *status); | 141 uregion_getRegionFromNumericCode (int32_t code, UErrorCode *status); |
146 | 142 |
147 /** | 143 /** |
148 * Returns an enumeration over the canonical codes of all known regions that mat
ch the given type. | 144 * Returns an enumeration over the canonical codes of all known regions that mat
ch the given type. |
149 * The enumeration must be closed with with uenum_close(). | 145 * The enumeration must be closed with with uenum_close(). |
150 * @draft ICU 52 | 146 * @stable ICU 52 |
151 */ | 147 */ |
152 U_DRAFT UEnumeration* U_EXPORT2 | 148 U_STABLE UEnumeration* U_EXPORT2 |
153 uregion_getAvailable(URegionType type, UErrorCode *status); | 149 uregion_getAvailable(URegionType type, UErrorCode *status); |
154 | 150 |
155 /** | 151 /** |
156 * Returns true if the specified uregion is equal to the specified otherRegion. | 152 * Returns true if the specified uregion is equal to the specified otherRegion. |
157 * @draft ICU 52 | 153 * @stable ICU 52 |
158 */ | 154 */ |
159 U_DRAFT UBool U_EXPORT2 | 155 U_STABLE UBool U_EXPORT2 |
160 uregion_areEqual(const URegion* uregion, const URegion* otherRegion); | 156 uregion_areEqual(const URegion* uregion, const URegion* otherRegion); |
161 | 157 |
162 /** | 158 /** |
163 * Returns a pointer to the URegion that contains the specified uregion. Returns
NULL if the | 159 * Returns a pointer to the URegion that contains the specified uregion. Returns
NULL if the |
164 * specified uregion is code "001" (World) or "ZZ" (Unknown region). For example
, calling | 160 * specified uregion is code "001" (World) or "ZZ" (Unknown region). For example
, calling |
165 * this method with region "IT" (Italy) returns the URegion for "039" (Southern
Europe). | 161 * this method with region "IT" (Italy) returns the URegion for "039" (Southern
Europe). |
166 * @draft ICU 52 | 162 * @stable ICU 52 |
167 */ | 163 */ |
168 U_DRAFT const URegion* U_EXPORT2 | 164 U_STABLE const URegion* U_EXPORT2 |
169 uregion_getContainingRegion(const URegion* uregion); | 165 uregion_getContainingRegion(const URegion* uregion); |
170 | 166 |
171 /** | 167 /** |
172 * Return a pointer to the URegion that geographically contains this uregion and
matches the | 168 * Return a pointer to the URegion that geographically contains this uregion and
matches the |
173 * specified type, moving multiple steps up the containment chain if necessary.
Returns NULL if no | 169 * specified type, moving multiple steps up the containment chain if necessary.
Returns NULL if no |
174 * containing region can be found that matches the specified type. Will return N
ULL if URegionType | 170 * containing region can be found that matches the specified type. Will return N
ULL if URegionType |
175 * is URGN_GROUPING, URGN_DEPRECATED, or URGN_UNKNOWN which are not appropriate
for this API. | 171 * is URGN_GROUPING, URGN_DEPRECATED, or URGN_UNKNOWN which are not appropriate
for this API. |
176 * For example, calling this method with uregion "IT" (Italy) for type URGN_CONT
INENT returns the | 172 * For example, calling this method with uregion "IT" (Italy) for type URGN_CONT
INENT returns the |
177 * URegion "150" (Europe). | 173 * URegion "150" (Europe). |
178 * @draft ICU 52 | 174 * @stable ICU 52 |
179 */ | 175 */ |
180 U_DRAFT const URegion* U_EXPORT2 | 176 U_STABLE const URegion* U_EXPORT2 |
181 uregion_getContainingRegionOfType(const URegion* uregion, URegionType type); | 177 uregion_getContainingRegionOfType(const URegion* uregion, URegionType type); |
182 | 178 |
183 /** | 179 /** |
184 * Return an enumeration over the canonical codes of all the regions that are im
mediate children | 180 * Return an enumeration over the canonical codes of all the regions that are im
mediate children |
185 * of the specified uregion in the region hierarchy. These returned regions coul
d be either macro | 181 * of the specified uregion in the region hierarchy. These returned regions coul
d be either macro |
186 * regions, territories, or a mixture of the two, depending on the containment d
ata as defined in | 182 * regions, territories, or a mixture of the two, depending on the containment d
ata as defined in |
187 * CLDR. This API returns NULL if this uregion doesn't have any sub-regions. For
example, calling | 183 * CLDR. This API returns NULL if this uregion doesn't have any sub-regions. For
example, calling |
188 * this function for uregion "150" (Europe) returns an enumeration containing th
e various | 184 * this function for uregion "150" (Europe) returns an enumeration containing th
e various |
189 * sub-regions of Europe: "039" (Southern Europe), "151" (Eastern Europe), "154"
(Northern Europe), | 185 * sub-regions of Europe: "039" (Southern Europe), "151" (Eastern Europe), "154"
(Northern Europe), |
190 * and "155" (Western Europe). The enumeration must be closed with with uenum_cl
ose(). | 186 * and "155" (Western Europe). The enumeration must be closed with with uenum_cl
ose(). |
191 * @draft ICU 52 | 187 * @stable ICU 52 |
192 */ | 188 */ |
193 U_DRAFT UEnumeration* U_EXPORT2 | 189 U_STABLE UEnumeration* U_EXPORT2 |
194 uregion_getContainedRegions(const URegion* uregion, UErrorCode *status); | 190 uregion_getContainedRegions(const URegion* uregion, UErrorCode *status); |
195 | 191 |
196 /** | 192 /** |
197 * Returns an enumeration over the canonical codes of all the regions that are c
hildren of the | 193 * Returns an enumeration over the canonical codes of all the regions that are c
hildren of the |
198 * specified uregion anywhere in the region hierarchy and match the given type.
This API may return | 194 * specified uregion anywhere in the region hierarchy and match the given type.
This API may return |
199 * an empty enumeration if this uregion doesn't have any sub-regions that match
the given type. | 195 * an empty enumeration if this uregion doesn't have any sub-regions that match
the given type. |
200 * For example, calling this method with region "150" (Europe) and type URGN_TER
RITORY" returns an | 196 * For example, calling this method with region "150" (Europe) and type URGN_TER
RITORY" returns an |
201 * enumeration containing all the territories in Europe: "FR" (France), "IT" (It
aly), "DE" (Germany), | 197 * enumeration containing all the territories in Europe: "FR" (France), "IT" (It
aly), "DE" (Germany), |
202 * etc. The enumeration must be closed with with uenum_close(). | 198 * etc. The enumeration must be closed with with uenum_close(). |
203 * @draft ICU 52 | 199 * @stable ICU 52 |
204 */ | 200 */ |
205 U_DRAFT UEnumeration* U_EXPORT2 | 201 U_STABLE UEnumeration* U_EXPORT2 |
206 uregion_getContainedRegionsOfType(const URegion* uregion, URegionType type, UErr
orCode *status); | 202 uregion_getContainedRegionsOfType(const URegion* uregion, URegionType type, UErr
orCode *status); |
207 | 203 |
208 /** | 204 /** |
209 * Returns true if the specified uregion contains the specified otherRegion anyw
here in the region | 205 * Returns true if the specified uregion contains the specified otherRegion anyw
here in the region |
210 * hierarchy. | 206 * hierarchy. |
211 * @draft ICU 52 | 207 * @stable ICU 52 |
212 */ | 208 */ |
213 U_DRAFT UBool U_EXPORT2 | 209 U_STABLE UBool U_EXPORT2 |
214 uregion_contains(const URegion* uregion, const URegion* otherRegion); | 210 uregion_contains(const URegion* uregion, const URegion* otherRegion); |
215 | 211 |
216 /** | 212 /** |
217 * If the specified uregion is deprecated, returns an enumeration over the canon
ical codes of the | 213 * If the specified uregion is deprecated, returns an enumeration over the canon
ical codes of the |
218 * regions that are the preferred replacement regions for the specified uregion.
If the specified | 214 * regions that are the preferred replacement regions for the specified uregion.
If the specified |
219 * uregion is not deprecated, returns NULL. For example, calling this method wit
h uregion | 215 * uregion is not deprecated, returns NULL. For example, calling this method wit
h uregion |
220 * "SU" (Soviet Union) returns a list of the regions containing "RU" (Russia), "
AM" (Armenia), | 216 * "SU" (Soviet Union) returns a list of the regions containing "RU" (Russia), "
AM" (Armenia), |
221 * "AZ" (Azerbaijan), etc... The enumeration must be closed with with uenum_clos
e(). | 217 * "AZ" (Azerbaijan), etc... The enumeration must be closed with with uenum_clos
e(). |
222 * @draft ICU 52 | 218 * @stable ICU 52 |
223 */ | 219 */ |
224 U_DRAFT UEnumeration* U_EXPORT2 | 220 U_STABLE UEnumeration* U_EXPORT2 |
225 uregion_getPreferredValues(const URegion* uregion, UErrorCode *status); | 221 uregion_getPreferredValues(const URegion* uregion, UErrorCode *status); |
226 | 222 |
227 /** | 223 /** |
228 * Returns the specified uregion's canonical code. | 224 * Returns the specified uregion's canonical code. |
229 * @draft ICU 52 | 225 * @stable ICU 52 |
230 */ | 226 */ |
231 U_DRAFT const char* U_EXPORT2 | 227 U_STABLE const char* U_EXPORT2 |
232 uregion_getRegionCode(const URegion* uregion); | 228 uregion_getRegionCode(const URegion* uregion); |
233 | 229 |
234 /** | 230 /** |
235 * Returns the specified uregion's numeric code, or a negative value if there is
no numeric code | 231 * Returns the specified uregion's numeric code, or a negative value if there is
no numeric code |
236 * for the specified uregion. | 232 * for the specified uregion. |
237 * @draft ICU 52 | 233 * @stable ICU 52 |
238 */ | 234 */ |
239 U_DRAFT int32_t U_EXPORT2 | 235 U_STABLE int32_t U_EXPORT2 |
240 uregion_getNumericCode(const URegion* uregion); | 236 uregion_getNumericCode(const URegion* uregion); |
241 | 237 |
242 /** | 238 /** |
243 * Returns the URegionType of the specified uregion. | 239 * Returns the URegionType of the specified uregion. |
244 * @draft ICU 52 | 240 * @stable ICU 52 |
245 */ | 241 */ |
246 U_DRAFT URegionType U_EXPORT2 | 242 U_STABLE URegionType U_EXPORT2 |
247 uregion_getType(const URegion* uregion); | 243 uregion_getType(const URegion* uregion); |
248 | 244 |
249 #endif /* U_HIDE_DRAFT_API */ | |
250 | 245 |
251 #endif /* #if !UCONFIG_NO_FORMATTING */ | 246 #endif /* #if !UCONFIG_NO_FORMATTING */ |
252 | 247 |
253 #endif | 248 #endif |
OLD | NEW |