Region is the class representing a Unicode Region Code, also known as a
michael@0: * Unicode Region Subtag, which is defined based upon the BCP 47 standard. We often think of
michael@0: * "regions" as "countries" when defining the characteristics of a locale. Region codes There are different
michael@0: * types of region codes that are important to distinguish.
michael@0: * michael@0: * Macroregion - A code for a "macro geographical (continental) region, geographical sub-region, or michael@0: * selected economic and other grouping" as defined in michael@0: * UN M.49 (http://unstats.un.org/unsd/methods/m49/m49regin.htm). michael@0: * These are typically 3-digit codes, but contain some 2-letter codes, such as the LDML code QO michael@0: * added for Outlying Oceania. Not all UNM.49 codes are defined in LDML, but most of them are. michael@0: * Macroregions are represented in ICU by one of three region types: WORLD ( region code 001 ), michael@0: * CONTINENTS ( regions contained directly by WORLD ), and SUBCONTINENTS ( things contained directly michael@0: * by a continent ). michael@0: *
michael@0: * TERRITORY - A Region that is not a Macroregion. These are typically codes for countries, but also michael@0: * include areas that are not separate countries, such as the code "AQ" for Antarctica or the code michael@0: * "HK" for Hong Kong (SAR China). Overseas dependencies of countries may or may not have separate michael@0: * codes. The codes are typically 2-letter codes aligned with the ISO 3166 standard, but BCP47 allows michael@0: * for the use of 3-digit codes in the future. michael@0: *
michael@0: * UNKNOWN - The code ZZ is defined by Unicode LDML for use to indicate that the Region is unknown, michael@0: * or that the value supplied as a region was invalid. michael@0: *
michael@0: * DEPRECATED - Region codes that have been defined in the past but are no longer in modern usage, michael@0: * usually due to a country splitting into multiple territories or changing its name. michael@0: *
michael@0: * GROUPING - A widely understood grouping of territories that has a well defined membership such michael@0: * that a region code has been assigned for it. Some of these are UNM.49 codes that do't fall into michael@0: * the world/continent/sub-continent hierarchy, while others are just well known groupings that have michael@0: * their own region code. Region "EU" (European Union) is one such region code that is a grouping. michael@0: * Groupings will never be returned by the getContainingRegion() API, since a different type of region michael@0: * ( WORLD, CONTINENT, or SUBCONTINENT ) will always be the containing region instead. michael@0: * michael@0: * The Region class is not intended for public subclassing. michael@0: * michael@0: * @author John Emmons michael@0: * @draft ICU 51 michael@0: */ michael@0: michael@0: class U_I18N_API Region : public UObject { michael@0: public: michael@0: /** michael@0: * Destructor. michael@0: * @draft ICU 51 michael@0: */ michael@0: virtual ~Region(); michael@0: michael@0: /** michael@0: * Returns true if the two regions are equal. michael@0: * @draft ICU 51 michael@0: */ michael@0: UBool operator==(const Region &that) const; michael@0: michael@0: /** michael@0: * Returns true if the two regions are NOT equal; that is, if operator ==() returns false. michael@0: * @draft ICU 51 michael@0: */ michael@0: UBool operator!=(const Region &that) const; michael@0: michael@0: /** michael@0: * Returns a pointer to a Region using the given region code. The region code can be either 2-letter ISO code, michael@0: * 3-letter ISO code, UNM.49 numeric code, or other valid Unicode Region Code as defined by the LDML specification. michael@0: * The identifier will be canonicalized internally using the supplemental metadata as defined in the CLDR. michael@0: * If the region code is NULL or not recognized, the appropriate error code will be set ( U_ILLEGAL_ARGUMENT_ERROR ) michael@0: * @draft ICU 51 michael@0: */ michael@0: static const Region* U_EXPORT2 getInstance(const char *region_code, UErrorCode &status); michael@0: michael@0: /** michael@0: * Returns a pointer to a Region using the given numeric region code. If the numeric region code is not recognized, michael@0: * the appropriate error code will be set ( U_ILLEGAL_ARGUMENT_ERROR ). michael@0: * @draft ICU 51 michael@0: */ michael@0: static const Region* U_EXPORT2 getInstance (int32_t code, UErrorCode &status); michael@0: michael@0: /** michael@0: * Returns an enumeration over the IDs of all known regions that match the given type. michael@0: * @draft ICU 51 michael@0: */ michael@0: static StringEnumeration* U_EXPORT2 getAvailable(URegionType type); michael@0: michael@0: /** michael@0: * Returns a pointer to the region that contains this region. Returns NULL if this region is code "001" (World) michael@0: * or "ZZ" (Unknown region). For example, calling this method with region "IT" (Italy) returns the michael@0: * region "039" (Southern Europe). michael@0: * @draft ICU 51 michael@0: */ michael@0: const Region* getContainingRegion() const; michael@0: michael@0: /** michael@0: * Return a pointer to the region that geographically contains this region and matches the given type, michael@0: * moving multiple steps up the containment chain if necessary. Returns NULL if no containing region can be found michael@0: * that matches the given type. Note: The URegionTypes = "URGN_GROUPING", "URGN_DEPRECATED", or "URGN_UNKNOWN" michael@0: * are not appropriate for use in this API. NULL will be returned in this case. For example, calling this method michael@0: * with region "IT" (Italy) for type "URGN_CONTINENT" returns the region "150" ( Europe ). michael@0: * @draft ICU 51 michael@0: */ michael@0: const Region* getContainingRegion(URegionType type) const; michael@0: michael@0: /** michael@0: * Return an enumeration over the IDs of all the regions that are immediate children of this region in the michael@0: * region hierarchy. These returned regions could be either macro regions, territories, or a mixture of the two, michael@0: * depending on the containment data as defined in CLDR. This API may return NULL if this region doesn't have michael@0: * any sub-regions. For example, calling this method with region "150" (Europe) returns an enumeration containing michael@0: * the various sub regions of Europe - "039" (Southern Europe) - "151" (Eastern Europe) - "154" (Northern Europe) michael@0: * and "155" (Western Europe). michael@0: * @draft ICU 51 michael@0: */ michael@0: StringEnumeration* getContainedRegions() const; michael@0: michael@0: /** michael@0: * Returns an enumeration over the IDs of all the regions that are children of this region anywhere in the region michael@0: * hierarchy and match the given type. This API may return an empty enumeration if this region doesn't have any michael@0: * sub-regions that match the given type. For example, calling this method with region "150" (Europe) and type michael@0: * "URGN_TERRITORY" returns a set containing all the territories in Europe ( "FR" (France) - "IT" (Italy) - "DE" (Germany) etc. ) michael@0: * @draft ICU 51 michael@0: */ michael@0: StringEnumeration* getContainedRegions( URegionType type ) const; michael@0: michael@0: /** michael@0: * Returns true if this region contains the supplied other region anywhere in the region hierarchy. michael@0: * @draft ICU 51 michael@0: */ michael@0: UBool contains(const Region &other) const; michael@0: michael@0: /** michael@0: * For deprecated regions, return an enumeration over the IDs of the regions that are the preferred replacement michael@0: * regions for this region. Returns null for a non-deprecated region. For example, calling this method with region michael@0: * "SU" (Soviet Union) would return a list of the regions containing "RU" (Russia), "AM" (Armenia), "AZ" (Azerbaijan), etc... michael@0: * @draft ICU 51 michael@0: */ michael@0: StringEnumeration* getPreferredValues() const; michael@0: michael@0: michael@0: /** michael@0: * Return this region's canonical region code. michael@0: * @draft ICU 51 michael@0: */ michael@0: const char* getRegionCode() const; michael@0: michael@0: /** michael@0: * Return this region's numeric code. michael@0: * Returns a negative value if the given region does not have a numeric code assigned to it. michael@0: * @draft ICU 51 michael@0: */ michael@0: int32_t getNumericCode() const; michael@0: michael@0: /** michael@0: * Returns the region type of this region. michael@0: * @draft ICU 51 michael@0: */ michael@0: URegionType getType() const; michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Cleans up statically allocated memory. michael@0: * @internal michael@0: */ michael@0: static void cleanupRegionData(); michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: private: michael@0: char id[4]; michael@0: UnicodeString idStr; michael@0: int32_t code; michael@0: URegionType type; michael@0: Region *containingRegion; michael@0: UVector *containedRegions; michael@0: UVector *preferredValues; michael@0: michael@0: /** michael@0: * Default Constructor. Internal - use factory methods only. michael@0: */ michael@0: Region(); michael@0: michael@0: michael@0: /* michael@0: * Initializes the region data from the ICU resource bundles. The region data michael@0: * contains the basic relationships such as which regions are known, what the numeric michael@0: * codes are, any known aliases, and the territory containment data. michael@0: * michael@0: * If the region data has already loaded, then this method simply returns without doing michael@0: * anything meaningful. michael@0: */ michael@0: michael@0: static void loadRegionData(); michael@0: michael@0: }; michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif /* U_HIDE_DRAFT_API */ michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */ michael@0: #endif // REGION_H michael@0: michael@0: //eof