1 // Copyright (C) 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ***************************************************************************************** 5 * Copyright (C) 2014, International Business Machines 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 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 * 63 * @stable ICU 51 64 */ 65 typedef enum URegionType { 66 /** 67 * Type representing the unknown region. 68 * @stable ICU 51 69 */ 70 URGN_UNKNOWN, 71 72 /** 73 * Type representing a territory. 74 * @stable ICU 51 75 */ 76 URGN_TERRITORY, 77 78 /** 79 * Type representing the whole world. 80 * @stable ICU 51 81 */ 82 URGN_WORLD, 83 84 /** 85 * Type representing a continent. 86 * @stable ICU 51 87 */ 88 URGN_CONTINENT, 89 90 /** 91 * Type representing a sub-continent. 92 * @stable ICU 51 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. 99 * @stable ICU 51 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. 106 * @stable ICU 51 107 */ 108 URGN_DEPRECATED, 109 110 #ifndef U_HIDE_DEPRECATED_API 111 /** 112 * One more than the highest normal URegionType value. 113 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 114 */ 115 URGN_LIMIT 116 #endif // U_HIDE_DEPRECATED_API 117 } URegionType; 118 119 #if !UCONFIG_NO_FORMATTING 120 121 /** 122 * Opaque URegion object for use in C programs. 123 * @stable ICU 52 124 */ 125 struct URegion; 126 typedef struct URegion URegion; /**< @stable ICU 52 */ 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). 134 * @stable ICU 52 135 */ 136 U_STABLE const URegion* U_EXPORT2 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). 142 * @stable ICU 52 143 */ 144 U_STABLE const URegion* U_EXPORT2 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(). 150 * @stable ICU 52 151 */ 152 U_STABLE UEnumeration* U_EXPORT2 153 uregion_getAvailable(URegionType type, UErrorCode *status); 154 155 /** 156 * Returns true if the specified uregion is equal to the specified otherRegion. 157 * @stable ICU 52 158 */ 159 U_STABLE UBool U_EXPORT2 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). 166 * @stable ICU 52 167 */ 168 U_STABLE const URegion* U_EXPORT2 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). 178 * @stable ICU 52 179 */ 180 U_STABLE const URegion* U_EXPORT2 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(). 191 * @stable ICU 52 192 */ 193 U_STABLE UEnumeration* U_EXPORT2 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(). 203 * @stable ICU 52 204 */ 205 U_STABLE UEnumeration* U_EXPORT2 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. 211 * @stable ICU 52 212 */ 213 U_STABLE UBool U_EXPORT2 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(). 222 * @stable ICU 52 223 */ 224 U_STABLE UEnumeration* U_EXPORT2 225 uregion_getPreferredValues(const URegion* uregion, UErrorCode *status); 226 227 /** 228 * Returns the specified uregion's canonical code. 229 * @stable ICU 52 230 */ 231 U_STABLE const char* U_EXPORT2 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. 237 * @stable ICU 52 238 */ 239 U_STABLE int32_t U_EXPORT2 240 uregion_getNumericCode(const URegion* uregion); 241 242 /** 243 * Returns the URegionType of the specified uregion. 244 * @stable ICU 52 245 */ 246 U_STABLE URegionType U_EXPORT2 247 uregion_getType(const URegion* uregion); 248 249 250 #endif /* #if !UCONFIG_NO_FORMATTING */ 251 252 #endif 253