Top Description Inners Fields Constructors Methods
com.ibm.icu.util

public Class Region

extends Object
implements Comparable<Region>
Class Inheritance
All Implemented Interfaces
java.lang.Comparable
Imports
java.util.ArrayList, .Arrays, .Collections, .Enumeration, .HashMap, .List, .Map, .Set, .TreeSet, com.ibm.icu.impl.ICUData, .ICUResourceBundle
Region 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.

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 ).

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.

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.

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.

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.

Author
John Emmons
ICU Status
Stable since ICU 50.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
Region.RegionType

RegionType is an enumeration defining the different types of regions.

Field Summary

Modifier and TypeField and Description
private static ArrayList<Set<Region>>
availableRegions

private int
code

private Set<Region>
containedRegions

private Region
containingRegion

private String
id

private static Map<Integer, Region>
numericCodeMap

private static final String
OUTLYING_OCEANIA_REGION_ID

private List<Region>
preferredValues

private static Map<String, Region>
regionAliases

private static boolean
regionDataIsLoaded

private static Map<String, Region>
regionIDMap

private static ArrayList<Region>
regions

private Region.RegionType
type

private static final String
UNKNOWN_REGION_ID

private static final String
WORLD_ID

Constructor Summary

AccessConstructor and Description
private
Region()

Method Summary

Modifier and TypeMethod and Description
public int
compareTo(Region
the object to be compared.
other)

Implements java.lang.Comparable.compareTo.

Compares this object with the specified object for order.
public boolean

Returns:

Returns true if this region contains the supplied other region anywhere in the region hierarchy.
contains(Region other)

public static Set<Region>

Returns:

An unmodifiable set of all known regions that match the given type.
getAvailable(Region.RegionType
The type of regions to be returned ( TERRITORY, MACROREGION, etc. )
type)

Used to retrieve all available regions of a specific type.

public Set<Region>

Returns:

An unmodifiable set containing 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 an empty set if this region doesn't have any sub-regions. For example, calling this method with region "150" (Europe) returns a set containing the various sub regions of Europe - "039" (Southern Europe) - "151" (Eastern Europe) - "154" (Northern Europe) and "155" (Western Europe).
getContainedRegions()

Used to determine the sub-regions that are contained within this region.

public Set<Region>

Returns:

An unmodifiable set containing 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 set 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 "TERRITORY" returns a set containing all the territories in Europe ( "FR" (France) - "IT" (Italy) - "DE" (Germany) etc. )
getContainedRegions(Region.RegionType type)

Used to determine all the regions that are contained within this region and that match the given type

public Region

Returns:

The region that geographically 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).
getContainingRegion()

Used to determine the macroregion that geographically contains this region.

public Region

Returns:

The region that geographically contains this region and matches the given type. May return NULL if no containing region can be found that matches the given type. For example, calling this method with region "IT" (Italy) and type CONTINENT returns the region "150" (Europe).
getContainingRegion(Region.RegionType type)

Used to determine the macroregion that geographically contains this region and that matches the given type.

public static Region

Returns:

The corresponding region.
getInstance(String
The id of the region to be retrieved.
id)

Returns a Region using the given region ID. The region ID can be either a 2-letter ISO code, 3-letter ISO code, UNM.49 numeric code, or other valid Unicode Region Code as defined by the CLDR.

public static Region

Returns:

The corresponding region.
getInstance(int
The numeric code of the region to be retrieved.
code)

Returns a Region using the given numeric code as defined by UNM.49

public int

Returns:

The numeric code for this region. Returns a negative value if the given region does not have a numeric code assigned to it. This is a very rare case and only occurs for a few very small territories.
getNumericCode()

Returns the numeric code for this region

public List<Region>

Returns:

For deprecated regions, return an unmodifiable list 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...
getPreferredValues()

public Region.RegionType

Returns:

This region's type classification, such as MACROREGION or TERRITORY.
getType()

Returns this region's type.

private static synchronized void
loadRegionData()

public String

Returns:

The string representation of this region, which is its ID.
toString()

Overrides java.lang.Object.toString.

Returns the string representation of this region
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

availableRegionsback to summary
private static ArrayList<Set<Region>> availableRegions
codeback to summary
private int code
containedRegionsback to summary
private Set<Region> containedRegions
containingRegionback to summary
private Region containingRegion
idback to summary
private String id
numericCodeMapback to summary
private static Map<Integer, Region> numericCodeMap
OUTLYING_OCEANIA_REGION_IDback to summary
private static final String OUTLYING_OCEANIA_REGION_ID
preferredValuesback to summary
private List<Region> preferredValues
regionAliasesback to summary
private static Map<String, Region> regionAliases
regionDataIsLoadedback to summary
private static boolean regionDataIsLoaded
regionIDMapback to summary
private static Map<String, Region> regionIDMap
regionsback to summary
private static ArrayList<Region> regions
typeback to summary
private Region.RegionType type
UNKNOWN_REGION_IDback to summary
private static final String UNKNOWN_REGION_ID
WORLD_IDback to summary
private static final String WORLD_ID

Constructor Detail

Regionback to summary
private Region()

Method Detail

compareToback to summary
public int compareTo(Region other)

Implements java.lang.Comparable.compareTo.

Doc from java.lang.Comparable.compareTo.

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

The implementor must ensure signum(x.compareTo(y)) == -signum(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception if and only if y.compareTo(x) throws an exception.)

The implementor must also ensure that the relation is transitive: (x.compareTo(y) > 0 && y.compareTo(z) > 0) implies x.compareTo(z) > 0.

Finally, the implementor must ensure that x.compareTo(y)==0 implies that signum(x.compareTo(z)) == signum(y.compareTo(z)), for all z.

Parameters
other:Region

the object to be compared.

Returns:int

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

ICU Status
Stable since ICU 50.
containsback to summary
public boolean contains(Region other)
Returns:boolean

Returns true if this region contains the supplied other region anywhere in the region hierarchy.

ICU Status
Stable since ICU 50.
getAvailableback to summary
public static Set<Region> getAvailable(Region.RegionType type)

Used to retrieve all available regions of a specific type.

Parameters
type:Region.RegionType

The type of regions to be returned ( TERRITORY, MACROREGION, etc. )

Returns:Set<Region>

An unmodifiable set of all known regions that match the given type.

ICU Status
Stable since ICU 50.
getContainedRegionsback to summary
public Set<Region> getContainedRegions()

Used to determine the sub-regions that are contained within this region.

Returns:Set<Region>

An unmodifiable set containing 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 an empty set if this region doesn't have any sub-regions. For example, calling this method with region "150" (Europe) returns a set containing the various sub regions of Europe - "039" (Southern Europe) - "151" (Eastern Europe) - "154" (Northern Europe) and "155" (Western Europe).

ICU Status
Stable since ICU 50.
getContainedRegionsback to summary
public Set<Region> getContainedRegions(Region.RegionType type)

Used to determine all the regions that are contained within this region and that match the given type

Returns:Set<Region>

An unmodifiable set containing 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 set 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 "TERRITORY" returns a set containing all the territories in Europe ( "FR" (France) - "IT" (Italy) - "DE" (Germany) etc. )

ICU Status
Stable since ICU 50.
getContainingRegionback to summary
public Region getContainingRegion()

Used to determine the macroregion that geographically contains this region.

Returns:Region

The region that geographically 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).

ICU Status
Stable since ICU 50.
getContainingRegionback to summary
public Region getContainingRegion(Region.RegionType type)

Used to determine the macroregion that geographically contains this region and that matches the given type.

Returns:Region

The region that geographically contains this region and matches the given type. May return NULL if no containing region can be found that matches the given type. For example, calling this method with region "IT" (Italy) and type CONTINENT returns the region "150" (Europe).

ICU Status
Stable since ICU 50.
getInstanceback to summary
public static Region getInstance(String id)

Returns a Region using the given region ID. The region ID can be either a 2-letter ISO code, 3-letter ISO code, UNM.49 numeric code, or other valid Unicode Region Code as defined by the CLDR.

Parameters
id:String

The id of the region to be retrieved.

Returns:Region

The corresponding region.

Exceptions
NullPointerException:
if the supplied id is null.
IllegalArgumentException:
if the supplied ID cannot be canonicalized to a Region ID that is known by ICU.
ICU Status
Stable since ICU 50.
getInstanceback to summary
public static Region getInstance(int code)

Returns a Region using the given numeric code as defined by UNM.49

Parameters
code:int

The numeric code of the region to be retrieved.

Returns:Region

The corresponding region.

Exceptions
IllegalArgumentException:
if the supplied numeric code is not recognized.
ICU Status
Stable since ICU 50.
getNumericCodeback to summary
public int getNumericCode()

Returns the numeric code for this region

Returns:int

The numeric code for this region. Returns a negative value if the given region does not have a numeric code assigned to it. This is a very rare case and only occurs for a few very small territories.

ICU Status
Stable since ICU 50.
getPreferredValuesback to summary
public List<Region> getPreferredValues()
Returns:List<Region>

For deprecated regions, return an unmodifiable list 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...

ICU Status
Stable since ICU 50.
getTypeback to summary
public Region.RegionType getType()

Returns this region's type.

Returns:Region.RegionType

This region's type classification, such as MACROREGION or TERRITORY.

ICU Status
Stable since ICU 50.
loadRegionDataback to summary
private static synchronized void loadRegionData()
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns the string representation of this region

Returns:String

The string representation of this region, which is its ID.

ICU Status
Stable since ICU 50.
com.ibm.icu.util back to summary

public final Enum Region.RegionType

extends Enum<Region.RegionType>
Class Inheritance
RegionType is an enumeration defining the different types of regions. Current possible values are WORLD, CONTINENT, SUBCONTINENT, TERRITORY, GROUPING, DEPRECATED, and UNKNOWN.
ICU Status
Stable since ICU 50.

Field Summary

Modifier and TypeField and Description
public static final Region.RegionType
CONTINENT

Type representing a continent.

public static final Region.RegionType
DEPRECATED

Type representing a region whose code has been deprecated, usually due to a country splitting into multiple territories or changing its name.

public static final Region.RegionType
GROUPING

Type representing a grouping of territories that is not to be used in the normal WORLD/CONTINENT/SUBCONTINENT/TERRITORY containment tree.

public static final Region.RegionType
SUBCONTINENT

Type representing a sub-continent.

public static final Region.RegionType
TERRITORY

Type representing a territory.

public static final Region.RegionType
UNKNOWN

Type representing the unknown region.

public static final Region.RegionType
WORLD

Type representing the whole world.

Constructor Summary

AccessConstructor and Description
private
RegionType()

Method Summary

Modifier and TypeMethod and Description
public static Region.RegionType
valueOf(String name)

public static Region.RegionType[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

CONTINENTback to summary
public static final Region.RegionType CONTINENT

Type representing a continent.

ICU Status
Stable since ICU 50.
DEPRECATEDback to summary
public static final Region.RegionType DEPRECATED

Type representing a region whose code has been deprecated, usually due to a country splitting into multiple territories or changing its name.

ICU Status
Stable since ICU 50.
GROUPINGback to summary
public static final Region.RegionType GROUPING

Type representing a grouping of territories that is not to be used in the normal WORLD/CONTINENT/SUBCONTINENT/TERRITORY containment tree.

ICU Status
Stable since ICU 50.
SUBCONTINENTback to summary
public static final Region.RegionType SUBCONTINENT

Type representing a sub-continent.

ICU Status
Stable since ICU 50.
TERRITORYback to summary
public static final Region.RegionType TERRITORY

Type representing a territory.

ICU Status
Stable since ICU 50.
UNKNOWNback to summary
public static final Region.RegionType UNKNOWN

Type representing the unknown region.

ICU Status
Stable since ICU 50.
WORLDback to summary
public static final Region.RegionType WORLD

Type representing the whole world.

ICU Status
Stable since ICU 50.

Constructor Detail

RegionTypeback to summary
private RegionType()

Method Detail

valueOfback to summary
public static Region.RegionType valueOf(String name)
valuesback to summary
public static Region.RegionType[] values()