com.ibm.icu.util
Class Region

java.lang.Object
  com.ibm.icu.util.Region

All Implemented Interfaces:

Comparable<Region>

Deprecated. This API might change or be removed in a future release.

public class Region
extends Object
implements Comparable<Region>

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

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

Nested Class Summary

static class

Region.RegionType Deprecated. This API might change or be removed in a future release.

Field Summary

static int

UNDEFINED_NUMERIC_CODE Deprecated. This API might change or be removed in a future release.

Method Summary

static String	canonicalize(String id) Deprecated. This API might change or be removed in a future release.
int	compareTo(Region other) Deprecated. This API might change or be removed in a future release.
static Region	get(int code) Deprecated. This API might change or be removed in a future release.
static Region	get(String id) Deprecated. This API might change or be removed in a future release.
static Set<Region>	getAvailable(Region.RegionType type) Deprecated. This API might change or be removed in a future release.
Set<Region>	getContainedTerritories() Deprecated. This API might change or be removed in a future release.
Region	getContainingRegion() Deprecated. This API might change or be removed in a future release.
int	getNumericCode() Deprecated. This API might change or be removed in a future release.
Set<Region>	getSubRegions() Deprecated. This API might change or be removed in a future release.
Region.RegionType	getType() Deprecated. This API might change or be removed in a future release.
static boolean	isCanonical(String id) Deprecated. This API might change or be removed in a future release.
boolean	isOfType(Region.RegionType type) Deprecated. This API might change or be removed in a future release.
String	toString() Deprecated. This API might change or be removed in a future release.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

UNDEFINED_NUMERIC_CODE

public static final int UNDEFINED_NUMERIC_CODE

Deprecated. This API might change or be removed in a future release.

A constant used for unknown numeric region code.

See Also:

getNumericCode(), Constant Field Values

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

Method Detail

get

public static Region get(String id)

Deprecated. This API might change or be removed in a future release.

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 - The id of the region to be retrieved.

Returns:

The corresponding region.

Throws:

NullPointerException - if the supplied id is null.

IllegalArgumentException - if the supplied ID cannot be canonicalized to a Region ID that is known by ICU.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

get

public static Region get(int code)

Deprecated. This API might change or be removed in a future release.

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

Parameters:

code - The numeric code of the region to be retrieved.

Returns:

The corresponding region.

Throws:

IllegalArgumentException - if the supplied numeric code is not recognized.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

canonicalize

public static String canonicalize(String id)

Deprecated. This API might change or be removed in a future release.

Returns the canonicalized (preferred) form of the Region code. For territories, it will convert the string to the 2-letter ISO 3166 code if at all possible, and will convert any known aliases to their modern counterparts.

Parameters:

id - The string representing the region code to be canonicalized.

Returns:

The canonicalized (preferred) form of the region code. If the supplied region code is not recognized, the unknown region ( code "ZZ" ) is returned.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

isCanonical

public static boolean isCanonical(String id)

Deprecated. This API might change or be removed in a future release.

Returns true if the supplied region code is already in its canonical ( preferred ) form.

Parameters:

id - The string representing the region code to be checked.

Returns:

TRUE if the supplied region code is canonical, FALSE otherwise.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getAvailable

public static Set<Region> getAvailable(Region.RegionType type)

Deprecated. This API might change or be removed in a future release.

Used to retrieve all available regions of a specific type.

Parameters:

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

Returns:

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

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getContainingRegion

public Region getContainingRegion()

Deprecated. This API might change or be removed in a future release.

Used to determine the macroregion that geographically contains this 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).

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getSubRegions

public Set<Region> getSubRegions()

Deprecated. This API might change or be removed in a future release.

Used to determine the sub-regions that are contained within this 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).

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getContainedTerritories

public Set<Region> getContainedTerritories()

Deprecated. This API might change or be removed in a future release.

Used to determine all the territories that are contained within this region.

Returns:

An unmodifiable set containing all the territories that are children of this region anywhere in the region hierarchy. If this region is already a territory, the empty set is returned, since territories by definition do not contain other regions. For example, calling this method with region "150" (Europe) returns a set containing all the territories in Europe ( "FR" (France) - "IT" (Italy) - "DE" (Germany) etc. )

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

toString

public String toString()

Deprecated. This API might change or be removed in a future release.

Returns the string representation of this region

Overrides:

toString in class Object

Returns:

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

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getNumericCode

public int getNumericCode()

Deprecated. This API might change or be removed in a future release.

Returns the numeric code for this region

Returns:

The numeric code for this region. Returns UNDEFINED_NUMERIC_CODE (-1) 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.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

getType

public Region.RegionType getType()

Deprecated. This API might change or be removed in a future release.

Returns this region's type.

Returns:

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

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

isOfType

public boolean isOfType(Region.RegionType type)

Deprecated. This API might change or be removed in a future release.

Checks to see if this region is of a specific type.

Returns:

Returns TRUE if this region matches the supplied type.

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.

compareTo

public int compareTo(Region other)

Deprecated. This API might change or be removed in a future release.

Specified by:

compareTo in interface Comparable<Region>

Status:

Technology Preview. This API is still in the early stages of development. Use at your own risk.