1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/region.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,225 @@
1.4 +/*
1.5 + *******************************************************************************
1.6 + * Copyright (C) 2013, International Business Machines Corporation and others.
1.7 + * All Rights Reserved.
1.8 + *******************************************************************************
1.9 + */
1.10 +
1.11 +#ifndef REGION_H
1.12 +#define REGION_H
1.13 +
1.14 +/**
1.15 + * \file
1.16 + * \brief C++ API: Region classes (territory containment)
1.17 + */
1.18 +
1.19 +#include "unicode/utypes.h"
1.20 +#include "unicode/uregion.h"
1.21 +
1.22 +#if !UCONFIG_NO_FORMATTING
1.23 +#ifndef U_HIDE_DRAFT_API
1.24 +
1.25 +#include "unicode/uobject.h"
1.26 +#include "unicode/uniset.h"
1.27 +#include "unicode/unistr.h"
1.28 +#include "unicode/strenum.h"
1.29 +
1.30 +U_NAMESPACE_BEGIN
1.31 +
1.32 +/**
1.33 + * <code>Region</code> is the class representing a Unicode Region Code, also known as a
1.34 + * Unicode Region Subtag, which is defined based upon the BCP 47 standard. We often think of
1.35 + * "regions" as "countries" when defining the characteristics of a locale. Region codes There are different
1.36 + * types of region codes that are important to distinguish.
1.37 + * <p>
1.38 + * Macroregion - A code for a "macro geographical (continental) region, geographical sub-region, or
1.39 + * selected economic and other grouping" as defined in
1.40 + * UN M.49 (http://unstats.un.org/unsd/methods/m49/m49regin.htm).
1.41 + * These are typically 3-digit codes, but contain some 2-letter codes, such as the LDML code QO
1.42 + * added for Outlying Oceania. Not all UNM.49 codes are defined in LDML, but most of them are.
1.43 + * Macroregions are represented in ICU by one of three region types: WORLD ( region code 001 ),
1.44 + * CONTINENTS ( regions contained directly by WORLD ), and SUBCONTINENTS ( things contained directly
1.45 + * by a continent ).
1.46 + * <p>
1.47 + * TERRITORY - A Region that is not a Macroregion. These are typically codes for countries, but also
1.48 + * include areas that are not separate countries, such as the code "AQ" for Antarctica or the code
1.49 + * "HK" for Hong Kong (SAR China). Overseas dependencies of countries may or may not have separate
1.50 + * codes. The codes are typically 2-letter codes aligned with the ISO 3166 standard, but BCP47 allows
1.51 + * for the use of 3-digit codes in the future.
1.52 + * <p>
1.53 + * UNKNOWN - The code ZZ is defined by Unicode LDML for use to indicate that the Region is unknown,
1.54 + * or that the value supplied as a region was invalid.
1.55 + * <p>
1.56 + * DEPRECATED - Region codes that have been defined in the past but are no longer in modern usage,
1.57 + * usually due to a country splitting into multiple territories or changing its name.
1.58 + * <p>
1.59 + * GROUPING - A widely understood grouping of territories that has a well defined membership such
1.60 + * that a region code has been assigned for it. Some of these are UNM.49 codes that do't fall into
1.61 + * the world/continent/sub-continent hierarchy, while others are just well known groupings that have
1.62 + * their own region code. Region "EU" (European Union) is one such region code that is a grouping.
1.63 + * Groupings will never be returned by the getContainingRegion() API, since a different type of region
1.64 + * ( WORLD, CONTINENT, or SUBCONTINENT ) will always be the containing region instead.
1.65 + *
1.66 + * The Region class is not intended for public subclassing.
1.67 + *
1.68 + * @author John Emmons
1.69 + * @draft ICU 51
1.70 + */
1.71 +
1.72 +class U_I18N_API Region : public UObject {
1.73 +public:
1.74 + /**
1.75 + * Destructor.
1.76 + * @draft ICU 51
1.77 + */
1.78 + virtual ~Region();
1.79 +
1.80 + /**
1.81 + * Returns true if the two regions are equal.
1.82 + * @draft ICU 51
1.83 + */
1.84 + UBool operator==(const Region &that) const;
1.85 +
1.86 + /**
1.87 + * Returns true if the two regions are NOT equal; that is, if operator ==() returns false.
1.88 + * @draft ICU 51
1.89 + */
1.90 + UBool operator!=(const Region &that) const;
1.91 +
1.92 + /**
1.93 + * Returns a pointer to a Region using the given region code. The region code can be either 2-letter ISO code,
1.94 + * 3-letter ISO code, UNM.49 numeric code, or other valid Unicode Region Code as defined by the LDML specification.
1.95 + * The identifier will be canonicalized internally using the supplemental metadata as defined in the CLDR.
1.96 + * If the region code is NULL or not recognized, the appropriate error code will be set ( U_ILLEGAL_ARGUMENT_ERROR )
1.97 + * @draft ICU 51
1.98 + */
1.99 + static const Region* U_EXPORT2 getInstance(const char *region_code, UErrorCode &status);
1.100 +
1.101 + /**
1.102 + * Returns a pointer to a Region using the given numeric region code. If the numeric region code is not recognized,
1.103 + * the appropriate error code will be set ( U_ILLEGAL_ARGUMENT_ERROR ).
1.104 + * @draft ICU 51
1.105 + */
1.106 + static const Region* U_EXPORT2 getInstance (int32_t code, UErrorCode &status);
1.107 +
1.108 + /**
1.109 + * Returns an enumeration over the IDs of all known regions that match the given type.
1.110 + * @draft ICU 51
1.111 + */
1.112 + static StringEnumeration* U_EXPORT2 getAvailable(URegionType type);
1.113 +
1.114 + /**
1.115 + * Returns a pointer to the region that contains this region. Returns NULL if this region is code "001" (World)
1.116 + * or "ZZ" (Unknown region). For example, calling this method with region "IT" (Italy) returns the
1.117 + * region "039" (Southern Europe).
1.118 + * @draft ICU 51
1.119 + */
1.120 + const Region* getContainingRegion() const;
1.121 +
1.122 + /**
1.123 + * Return a pointer to the region that geographically contains this region and matches the given type,
1.124 + * moving multiple steps up the containment chain if necessary. Returns NULL if no containing region can be found
1.125 + * that matches the given type. Note: The URegionTypes = "URGN_GROUPING", "URGN_DEPRECATED", or "URGN_UNKNOWN"
1.126 + * are not appropriate for use in this API. NULL will be returned in this case. For example, calling this method
1.127 + * with region "IT" (Italy) for type "URGN_CONTINENT" returns the region "150" ( Europe ).
1.128 + * @draft ICU 51
1.129 + */
1.130 + const Region* getContainingRegion(URegionType type) const;
1.131 +
1.132 + /**
1.133 + * Return an enumeration over the IDs of all the regions that are immediate children of this region in the
1.134 + * region hierarchy. These returned regions could be either macro regions, territories, or a mixture of the two,
1.135 + * depending on the containment data as defined in CLDR. This API may return NULL if this region doesn't have
1.136 + * any sub-regions. For example, calling this method with region "150" (Europe) returns an enumeration containing
1.137 + * the various sub regions of Europe - "039" (Southern Europe) - "151" (Eastern Europe) - "154" (Northern Europe)
1.138 + * and "155" (Western Europe).
1.139 + * @draft ICU 51
1.140 + */
1.141 + StringEnumeration* getContainedRegions() const;
1.142 +
1.143 + /**
1.144 + * Returns an enumeration over the IDs of all the regions that are children of this region anywhere in the region
1.145 + * hierarchy and match the given type. This API may return an empty enumeration if this region doesn't have any
1.146 + * sub-regions that match the given type. For example, calling this method with region "150" (Europe) and type
1.147 + * "URGN_TERRITORY" returns a set containing all the territories in Europe ( "FR" (France) - "IT" (Italy) - "DE" (Germany) etc. )
1.148 + * @draft ICU 51
1.149 + */
1.150 + StringEnumeration* getContainedRegions( URegionType type ) const;
1.151 +
1.152 + /**
1.153 + * Returns true if this region contains the supplied other region anywhere in the region hierarchy.
1.154 + * @draft ICU 51
1.155 + */
1.156 + UBool contains(const Region &other) const;
1.157 +
1.158 + /**
1.159 + * For deprecated regions, return an enumeration over the IDs of the regions that are the preferred replacement
1.160 + * regions for this region. Returns null for a non-deprecated region. For example, calling this method with region
1.161 + * "SU" (Soviet Union) would return a list of the regions containing "RU" (Russia), "AM" (Armenia), "AZ" (Azerbaijan), etc...
1.162 + * @draft ICU 51
1.163 + */
1.164 + StringEnumeration* getPreferredValues() const;
1.165 +
1.166 +
1.167 + /**
1.168 + * Return this region's canonical region code.
1.169 + * @draft ICU 51
1.170 + */
1.171 + const char* getRegionCode() const;
1.172 +
1.173 + /**
1.174 + * Return this region's numeric code.
1.175 + * Returns a negative value if the given region does not have a numeric code assigned to it.
1.176 + * @draft ICU 51
1.177 + */
1.178 + int32_t getNumericCode() const;
1.179 +
1.180 + /**
1.181 + * Returns the region type of this region.
1.182 + * @draft ICU 51
1.183 + */
1.184 + URegionType getType() const;
1.185 +
1.186 +#ifndef U_HIDE_INTERNAL_API
1.187 + /**
1.188 + * Cleans up statically allocated memory.
1.189 + * @internal
1.190 + */
1.191 + static void cleanupRegionData();
1.192 +#endif /* U_HIDE_INTERNAL_API */
1.193 +
1.194 +private:
1.195 + char id[4];
1.196 + UnicodeString idStr;
1.197 + int32_t code;
1.198 + URegionType type;
1.199 + Region *containingRegion;
1.200 + UVector *containedRegions;
1.201 + UVector *preferredValues;
1.202 +
1.203 + /**
1.204 + * Default Constructor. Internal - use factory methods only.
1.205 + */
1.206 + Region();
1.207 +
1.208 +
1.209 + /*
1.210 + * Initializes the region data from the ICU resource bundles. The region data
1.211 + * contains the basic relationships such as which regions are known, what the numeric
1.212 + * codes are, any known aliases, and the territory containment data.
1.213 + *
1.214 + * If the region data has already loaded, then this method simply returns without doing
1.215 + * anything meaningful.
1.216 + */
1.217 +
1.218 + static void loadRegionData();
1.219 +
1.220 +};
1.221 +
1.222 +U_NAMESPACE_END
1.223 +
1.224 +#endif /* U_HIDE_DRAFT_API */
1.225 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.226 +#endif // REGION_H
1.227 +
1.228 +//eof
