]>
Commit | Line | Data |
---|---|---|
f3c0d7a5 A |
1 | // © 2016 and later: Unicode, Inc. and others. |
2 | // License & terms of use: http://www.unicode.org/copyright.html | |
51004dcb A |
3 | /* |
4 | ***************************************************************************************** | |
57a6839d | 5 | * Copyright (C) 2014, International Business Machines |
51004dcb A |
6 | * Corporation and others. All Rights Reserved. |
7 | ***************************************************************************************** | |
8 | */ | |
9 | ||
10 | #ifndef UREGION_H | |
11 | #define UREGION_H | |
12 | ||
13 | #include "unicode/utypes.h" | |
14 | #include "unicode/uenum.h" | |
15 | ||
16 | /** | |
17 | * \file | |
18 | * \brief C API: URegion (territory containment and mapping) | |
19 | * | |
20 | * URegion objects represent data associated with a particular Unicode Region Code, also known as a | |
21 | * Unicode Region Subtag, which is defined based upon the BCP 47 standard. These include: | |
22 | * * Two-letter codes defined by ISO 3166-1, with special LDML treatment of certain private-use or | |
23 | * reserved codes; | |
24 | * * A subset of 3-digit numeric codes defined by UN M.49. | |
25 | * URegion objects can also provide mappings to and from additional codes. There are different types | |
26 | * of regions that are important to distinguish: | |
27 | * <p> | |
28 | * Macroregion - A code for a "macro geographical (continental) region, geographical sub-region, or | |
29 | * selected economic and other grouping" as defined in UN M.49. These are typically 3-digit codes, | |
30 | * but contain some 2-letter codes for LDML extensions, such as "QO" for Outlying Oceania. | |
31 | * Macroregions are represented in ICU by one of three region types: WORLD (code 001), | |
32 | * CONTINENTS (regions contained directly by WORLD), and SUBCONTINENTS (regions contained directly | |
33 | * by a continent ). | |
34 | * <p> | |
35 | * TERRITORY - A Region that is not a Macroregion. These are typically codes for countries, but also | |
36 | * include areas that are not separate countries, such as the code "AQ" for Antarctica or the code | |
37 | * "HK" for Hong Kong (SAR China). Overseas dependencies of countries may or may not have separate | |
38 | * codes. The codes are typically 2-letter codes aligned with ISO 3166, but BCP47 allows for the use | |
39 | * of 3-digit codes in the future. | |
40 | * <p> | |
41 | * UNKNOWN - The code ZZ is defined by Unicode LDML for use in indicating that region is unknown, | |
42 | * or that the value supplied as a region was invalid. | |
43 | * <p> | |
44 | * DEPRECATED - Region codes that have been defined in the past but are no longer in modern usage, | |
45 | * usually due to a country splitting into multiple territories or changing its name. | |
46 | * <p> | |
47 | * GROUPING - A widely understood grouping of territories that has a well defined membership such | |
48 | * that a region code has been assigned for it. Some of these are UN M.49 codes that don't fall into | |
49 | * the world/continent/sub-continent hierarchy, while others are just well-known groupings that have | |
50 | * their own region code. Region "EU" (European Union) is one such region code that is a grouping. | |
51 | * Groupings will never be returned by the uregion_getContainingRegion, since a different type of region | |
52 | * (WORLD, CONTINENT, or SUBCONTINENT) will always be the containing region instead. | |
53 | * | |
54 | * URegion objects are const/immutable, owned and maintained by ICU itself, so there are not functions | |
55 | * to open or close them. | |
56 | */ | |
57 | ||
51004dcb A |
58 | /** |
59 | * URegionType is an enumeration defining the different types of regions. Current possible | |
60 | * values are URGN_WORLD, URGN_CONTINENT, URGN_SUBCONTINENT, URGN_TERRITORY, URGN_GROUPING, | |
61 | * URGN_DEPRECATED, and URGN_UNKNOWN. | |
62 | * | |
57a6839d | 63 | * @stable ICU 51 |
51004dcb A |
64 | */ |
65 | typedef enum URegionType { | |
66 | /** | |
67 | * Type representing the unknown region. | |
57a6839d | 68 | * @stable ICU 51 |
51004dcb A |
69 | */ |
70 | URGN_UNKNOWN, | |
71 | ||
72 | /** | |
73 | * Type representing a territory. | |
57a6839d | 74 | * @stable ICU 51 |
51004dcb A |
75 | */ |
76 | URGN_TERRITORY, | |
77 | ||
78 | /** | |
79 | * Type representing the whole world. | |
57a6839d | 80 | * @stable ICU 51 |
51004dcb A |
81 | */ |
82 | URGN_WORLD, | |
83 | ||
84 | /** | |
85 | * Type representing a continent. | |
57a6839d | 86 | * @stable ICU 51 |
51004dcb A |
87 | */ |
88 | URGN_CONTINENT, | |
89 | ||
90 | /** | |
91 | * Type representing a sub-continent. | |
57a6839d | 92 | * @stable ICU 51 |
51004dcb A |
93 | */ |
94 | URGN_SUBCONTINENT, | |
95 | ||
96 | /** | |
97 | * Type representing a grouping of territories that is not to be used in | |
98 | * the normal WORLD/CONTINENT/SUBCONTINENT/TERRITORY containment tree. | |
57a6839d | 99 | * @stable ICU 51 |
51004dcb A |
100 | */ |
101 | URGN_GROUPING, | |
102 | ||
103 | /** | |
104 | * Type representing a region whose code has been deprecated, usually | |
105 | * due to a country splitting into multiple territories or changing its name. | |
57a6839d | 106 | * @stable ICU 51 |
51004dcb A |
107 | */ |
108 | URGN_DEPRECATED, | |
109 | ||
f3c0d7a5 | 110 | #ifndef U_HIDE_DEPRECATED_API |
51004dcb | 111 | /** |
f3c0d7a5 A |
112 | * One more than the highest normal URegionType value. |
113 | * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. | |
51004dcb A |
114 | */ |
115 | URGN_LIMIT | |
f3c0d7a5 | 116 | #endif /* U_HIDE_DEPRECATED_API */ |
51004dcb | 117 | } URegionType; |
51004dcb A |
118 | |
119 | #if !UCONFIG_NO_FORMATTING | |
120 | ||
51004dcb A |
121 | /** |
122 | * Opaque URegion object for use in C programs. | |
b331163b | 123 | * @stable ICU 52 |
51004dcb A |
124 | */ |
125 | struct URegion; | |
b331163b | 126 | typedef struct URegion URegion; /**< @stable ICU 52 */ |
51004dcb A |
127 | |
128 | /** | |
129 | * 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 valid Unicode Region | |
131 | * Code as defined by the LDML specification. The code will be canonicalized internally. If the | |
132 | * region code is NULL or not recognized, the appropriate error code will be set | |
133 | * (U_ILLEGAL_ARGUMENT_ERROR). | |
b331163b | 134 | * @stable ICU 52 |
51004dcb | 135 | */ |
b331163b | 136 | U_STABLE const URegion* U_EXPORT2 |
51004dcb A |
137 | uregion_getRegionFromCode(const char *regionCode, UErrorCode *status); |
138 | ||
139 | /** | |
140 | * 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_ARGUMENT_ERROR). | |
b331163b | 142 | * @stable ICU 52 |
51004dcb | 143 | */ |
b331163b | 144 | U_STABLE const URegion* U_EXPORT2 |
51004dcb A |
145 | uregion_getRegionFromNumericCode (int32_t code, UErrorCode *status); |
146 | ||
147 | /** | |
148 | * Returns an enumeration over the canonical codes of all known regions that match the given type. | |
149 | * The enumeration must be closed with with uenum_close(). | |
b331163b | 150 | * @stable ICU 52 |
51004dcb | 151 | */ |
b331163b | 152 | U_STABLE UEnumeration* U_EXPORT2 |
51004dcb A |
153 | uregion_getAvailable(URegionType type, UErrorCode *status); |
154 | ||
155 | /** | |
156 | * Returns true if the specified uregion is equal to the specified otherRegion. | |
b331163b | 157 | * @stable ICU 52 |
51004dcb | 158 | */ |
b331163b | 159 | U_STABLE UBool U_EXPORT2 |
51004dcb A |
160 | uregion_areEqual(const URegion* uregion, const URegion* otherRegion); |
161 | ||
162 | /** | |
163 | * 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 | |
165 | * this method with region "IT" (Italy) returns the URegion for "039" (Southern Europe). | |
b331163b | 166 | * @stable ICU 52 |
51004dcb | 167 | */ |
b331163b | 168 | U_STABLE const URegion* U_EXPORT2 |
51004dcb A |
169 | uregion_getContainingRegion(const URegion* uregion); |
170 | ||
171 | /** | |
172 | * 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 | |
174 | * containing region can be found that matches the specified type. Will return NULL if URegionType | |
175 | * 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_CONTINENT returns the | |
177 | * URegion "150" (Europe). | |
b331163b | 178 | * @stable ICU 52 |
51004dcb | 179 | */ |
b331163b | 180 | U_STABLE const URegion* U_EXPORT2 |
51004dcb A |
181 | uregion_getContainingRegionOfType(const URegion* uregion, URegionType type); |
182 | ||
183 | /** | |
184 | * Return an enumeration over the canonical codes of all the regions that are immediate children | |
185 | * of the specified uregion in the region hierarchy. These returned regions could be either macro | |
186 | * regions, territories, or a mixture of the two, depending on the containment data as defined in | |
187 | * 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 the various | |
189 | * 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_close(). | |
b331163b | 191 | * @stable ICU 52 |
51004dcb | 192 | */ |
b331163b | 193 | U_STABLE UEnumeration* U_EXPORT2 |
51004dcb A |
194 | uregion_getContainedRegions(const URegion* uregion, UErrorCode *status); |
195 | ||
196 | /** | |
197 | * Returns an enumeration over the canonical codes of all the regions that are children of the | |
198 | * 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. | |
200 | * For example, calling this method with region "150" (Europe) and type URGN_TERRITORY" returns an | |
201 | * enumeration containing all the territories in Europe: "FR" (France), "IT" (Italy), "DE" (Germany), | |
202 | * etc. The enumeration must be closed with with uenum_close(). | |
b331163b | 203 | * @stable ICU 52 |
51004dcb | 204 | */ |
b331163b | 205 | U_STABLE UEnumeration* U_EXPORT2 |
51004dcb A |
206 | uregion_getContainedRegionsOfType(const URegion* uregion, URegionType type, UErrorCode *status); |
207 | ||
208 | /** | |
209 | * Returns true if the specified uregion contains the specified otherRegion anywhere in the region | |
210 | * hierarchy. | |
b331163b | 211 | * @stable ICU 52 |
51004dcb | 212 | */ |
b331163b | 213 | U_STABLE UBool U_EXPORT2 |
51004dcb A |
214 | uregion_contains(const URegion* uregion, const URegion* otherRegion); |
215 | ||
216 | /** | |
217 | * If the specified uregion is deprecated, returns an enumeration over the canonical codes of the | |
218 | * 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 with uregion | |
220 | * "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_close(). | |
b331163b | 222 | * @stable ICU 52 |
51004dcb | 223 | */ |
b331163b | 224 | U_STABLE UEnumeration* U_EXPORT2 |
51004dcb A |
225 | uregion_getPreferredValues(const URegion* uregion, UErrorCode *status); |
226 | ||
227 | /** | |
228 | * Returns the specified uregion's canonical code. | |
b331163b | 229 | * @stable ICU 52 |
51004dcb | 230 | */ |
b331163b | 231 | U_STABLE const char* U_EXPORT2 |
51004dcb A |
232 | uregion_getRegionCode(const URegion* uregion); |
233 | ||
234 | /** | |
235 | * Returns the specified uregion's numeric code, or a negative value if there is no numeric code | |
236 | * for the specified uregion. | |
b331163b | 237 | * @stable ICU 52 |
51004dcb | 238 | */ |
b331163b | 239 | U_STABLE int32_t U_EXPORT2 |
51004dcb A |
240 | uregion_getNumericCode(const URegion* uregion); |
241 | ||
242 | /** | |
243 | * Returns the URegionType of the specified uregion. | |
b331163b | 244 | * @stable ICU 52 |
51004dcb | 245 | */ |
b331163b | 246 | U_STABLE URegionType U_EXPORT2 |
51004dcb A |
247 | uregion_getType(const URegion* uregion); |
248 | ||
51004dcb A |
249 | |
250 | #endif /* #if !UCONFIG_NO_FORMATTING */ | |
251 | ||
252 | #endif |