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