1 /* 2 ******************************************************************************* 3 * Copyright (C) 2014-2015, International Business Machines Corporation and others. 4 * All Rights Reserved. 5 ******************************************************************************* 6 */ 7 8 #ifndef REGION_H 9 #define REGION_H 10 11 /** 12 * \file 13 * \brief C++ API: Region classes (territory containment) 14 */ 15 16 #include "unicode/utypes.h" 17 #include "unicode/uregion.h" 18 19 #if !UCONFIG_NO_FORMATTING 20 21 #include "unicode/uobject.h" 22 #include "unicode/uniset.h" 23 #include "unicode/unistr.h" 24 #include "unicode/strenum.h" 25 26 U_NAMESPACE_BEGIN 27 28 /** 29 * <code>Region</code> is the class representing a Unicode Region Code, also known as a 30 * Unicode Region Subtag, which is defined based upon the BCP 47 standard. We often think of 31 * "regions" as "countries" when defining the characteristics of a locale. Region codes There are different 32 * types of region codes that are important to distinguish. 33 * <p> 34 * Macroregion - A code for a "macro geographical (continental) region, geographical sub-region, or 35 * selected economic and other grouping" as defined in 36 * UN M.49 (http://unstats.un.org/unsd/methods/m49/m49regin.htm). 37 * These are typically 3-digit codes, but contain some 2-letter codes, such as the LDML code QO 38 * added for Outlying Oceania. Not all UNM.49 codes are defined in LDML, but most of them are. 39 * Macroregions are represented in ICU by one of three region types: WORLD ( region code 001 ), 40 * CONTINENTS ( regions contained directly by WORLD ), and SUBCONTINENTS ( things contained directly 41 * by a continent ). 42 * <p> 43 * TERRITORY - A Region that is not a Macroregion. These are typically codes for countries, but also 44 * include areas that are not separate countries, such as the code "AQ" for Antarctica or the code 45 * "HK" for Hong Kong (SAR China). Overseas dependencies of countries may or may not have separate 46 * codes. The codes are typically 2-letter codes aligned with the ISO 3166 standard, but BCP47 allows 47 * for the use of 3-digit codes in the future. 48 * <p> 49 * UNKNOWN - The code ZZ is defined by Unicode LDML for use to indicate that the Region is unknown, 50 * or that the value supplied as a region was invalid. 51 * <p> 52 * DEPRECATED - Region codes that have been defined in the past but are no longer in modern usage, 53 * usually due to a country splitting into multiple territories or changing its name. 54 * <p> 55 * GROUPING - A widely understood grouping of territories that has a well defined membership such 56 * that a region code has been assigned for it. Some of these are UNM.49 codes that do't fall into 57 * the world/continent/sub-continent hierarchy, while others are just well known groupings that have 58 * their own region code. Region "EU" (European Union) is one such region code that is a grouping. 59 * Groupings will never be returned by the getContainingRegion() API, since a different type of region 60 * ( WORLD, CONTINENT, or SUBCONTINENT ) will always be the containing region instead. 61 * 62 * The Region class is not intended for public subclassing. 63 * 64 * @author John Emmons 65 * @stable ICU 51 66 */ 67 68 class U_I18N_API Region : public UObject { 69 public: 70 /** 71 * Destructor. 72 * @stable ICU 51 73 */ 74 virtual ~Region(); 75 76 /** 77 * Returns true if the two regions are equal. 78 * @stable ICU 51 79 */ 80 UBool operator==(const Region &that) const; 81 82 /** 83 * Returns true if the two regions are NOT equal; that is, if operator ==() returns false. 84 * @stable ICU 51 85 */ 86 UBool operator!=(const Region &that) const; 87 88 /** 89 * Returns a pointer to a Region using the given region code. The region code can be either 2-letter ISO code, 90 * 3-letter ISO code, UNM.49 numeric code, or other valid Unicode Region Code as defined by the LDML specification. 91 * The identifier will be canonicalized internally using the supplemental metadata as defined in the CLDR. 92 * If the region code is NULL or not recognized, the appropriate error code will be set ( U_ILLEGAL_ARGUMENT_ERROR ) 93 * @stable ICU 51 94 */ 95 static const Region* U_EXPORT2 getInstance(const char *region_code, UErrorCode &status); 96 97 /** 98 * Returns a pointer to a Region using the given numeric region code. If the numeric region code is not recognized, 99 * the appropriate error code will be set ( U_ILLEGAL_ARGUMENT_ERROR ). 100 * @stable ICU 51 101 */ 102 static const Region* U_EXPORT2 getInstance (int32_t code, UErrorCode &status); 103 104 #ifndef U_HIDE_DRAFT_API 105 /** 106 * Returns an enumeration over the IDs of all known regions that match the given type. 107 * @draft ICU 55 108 */ 109 static StringEnumeration* U_EXPORT2 getAvailable(URegionType type, UErrorCode &status); 110 #endif /* U_HIDE_DRAFT_API */ 111 112 /** 113 * Returns a pointer to the region that contains this region. Returns NULL if this region is code "001" (World) 114 * or "ZZ" (Unknown region). For example, calling this method with region "IT" (Italy) returns the 115 * region "039" (Southern Europe). 116 * @stable ICU 51 117 */ 118 const Region* getContainingRegion() const; 119 120 /** 121 * Return a pointer to the region that geographically contains this region and matches the given type, 122 * moving multiple steps up the containment chain if necessary. Returns NULL if no containing region can be found 123 * that matches the given type. Note: The URegionTypes = "URGN_GROUPING", "URGN_DEPRECATED", or "URGN_UNKNOWN" 124 * are not appropriate for use in this API. NULL will be returned in this case. For example, calling this method 125 * with region "IT" (Italy) for type "URGN_CONTINENT" returns the region "150" ( Europe ). 126 * @stable ICU 51 127 */ 128 const Region* getContainingRegion(URegionType type) const; 129 130 #ifndef U_HIDE_DRAFT_API 131 /** 132 * Return an enumeration over the IDs of all the regions that are immediate children of this region in the 133 * region hierarchy. These returned regions could be either macro regions, territories, or a mixture of the two, 134 * depending on the containment data as defined in CLDR. This API may return NULL if this region doesn't have 135 * any sub-regions. For example, calling this method with region "150" (Europe) returns an enumeration containing 136 * the various sub regions of Europe - "039" (Southern Europe) - "151" (Eastern Europe) - "154" (Northern Europe) 137 * and "155" (Western Europe). 138 * @draft ICU 55 139 */ 140 StringEnumeration* getContainedRegions(UErrorCode &status) const; 141 142 /** 143 * Returns an enumeration over the IDs of all the regions that are children of this region anywhere in the region 144 * hierarchy and match the given type. This API may return an empty enumeration if this region doesn't have any 145 * sub-regions that match the given type. For example, calling this method with region "150" (Europe) and type 146 * "URGN_TERRITORY" returns a set containing all the territories in Europe ( "FR" (France) - "IT" (Italy) - "DE" (Germany) etc. ) 147 * @draft ICU 55 148 */ 149 StringEnumeration* getContainedRegions( URegionType type, UErrorCode &status ) const; 150 #endif /* U_HIDE_DRAFT_API */ 151 152 /** 153 * Returns true if this region contains the supplied other region anywhere in the region hierarchy. 154 * @stable ICU 51 155 */ 156 UBool contains(const Region &other) const; 157 158 #ifndef U_HIDE_DRAFT_API 159 /** 160 * For deprecated regions, return an enumeration over the IDs of the regions that are the preferred replacement 161 * regions for this region. Returns null for a non-deprecated region. For example, calling this method with region 162 * "SU" (Soviet Union) would return a list of the regions containing "RU" (Russia), "AM" (Armenia), "AZ" (Azerbaijan), etc... 163 * @draft ICU 55 164 */ 165 StringEnumeration* getPreferredValues(UErrorCode &status) const; 166 #endif /* U_HIDE_DRAFT_API */ 167 168 /** 169 * Return this region's canonical region code. 170 * @stable ICU 51 171 */ 172 const char* getRegionCode() const; 173 174 /** 175 * Return this region's numeric code. 176 * Returns a negative value if the given region does not have a numeric code assigned to it. 177 * @stable ICU 51 178 */ 179 int32_t getNumericCode() const; 180 181 /** 182 * Returns the region type of this region. 183 * @stable ICU 51 184 */ 185 URegionType getType() const; 186 187 #ifndef U_HIDE_INTERNAL_API 188 /** 189 * Cleans up statically allocated memory. 190 * @internal 191 */ 192 static void cleanupRegionData(); 193 #endif /* U_HIDE_INTERNAL_API */ 194 195 private: 196 char id[4]; 197 UnicodeString idStr; 198 int32_t code; 199 URegionType type; 200 Region *containingRegion; 201 UVector *containedRegions; 202 UVector *preferredValues; 203 204 /** 205 * Default Constructor. Internal - use factory methods only. 206 */ 207 Region(); 208 209 210 /* 211 * Initializes the region data from the ICU resource bundles. The region data 212 * contains the basic relationships such as which regions are known, what the numeric 213 * codes are, any known aliases, and the territory containment data. 214 * 215 * If the region data has already loaded, then this method simply returns without doing 216 * anything meaningful. 217 */ 218 219 static void loadRegionData(UErrorCode &status); 220 221 }; 222 223 U_NAMESPACE_END 224 225 #endif /* #if !UCONFIG_NO_FORMATTING */ 226 #endif // REGION_H 227 228 //eof 229