Region (ICU4J 76)

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

All Implemented Interfaces:

Comparable<Region>
```
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:
Stable ICU 50.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Region.RegionType
RegionType is an enumeration defining the different types of regions.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Region.RegionType` RegionType is an enumeration defining the different types of regions.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`compareTo(Region other)`
`boolean`	`contains(Region other)`
`static Set<Region>`	`getAvailable(Region.RegionType type)` Used to retrieve all available regions of a specific type.
`Set<Region>`	`getContainedRegions()` Used to determine the sub-regions that are contained within this region.
`Set<Region>`	`getContainedRegions(Region.RegionType type)` Used to determine all the regions that are contained within this region and that match the given type
`Region`	`getContainingRegion()` Used to determine the macroregion that geographically contains this region.
`Region`	`getContainingRegion(Region.RegionType type)` Used to determine the macroregion that geographically contains this region and that matches the given type.
`static Region`	`getInstance(int code)` Returns a Region using the given numeric code as defined by UNM.49
`static Region`	`getInstance(String id)` Returns a Region using the given region ID.
`int`	`getNumericCode()` Returns the numeric code for this region
`List<Region>`	`getPreferredValues()`
`Region.RegionType`	`getType()` Returns this region's type.
`String`	`toString()` Returns the string representation of this region

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - getInstance
```
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 - 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:
    Stable ICU 50.
  - getInstance
```
public static Region getInstance(int code)
```
    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:
    Stable ICU 50.
  - getAvailable
```
public static Set<Region> getAvailable(Region.RegionType type)
```
    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:
    Stable ICU 50.
  - getContainingRegion
```
public Region getContainingRegion()
```
    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:
    Stable ICU 50.
  - getContainingRegion
```
public Region getContainingRegion(Region.RegionType type)
```
    Used to determine the macroregion that geographically contains this region and that matches the given type.
    
    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).
    
    Status:
    Stable ICU 50.
  - getContainedRegions
```
public Set<Region> getContainedRegions()
```
    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:
    Stable ICU 50.
  - getContainedRegions
```
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:
    
    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. )
    
    Status:
    Stable ICU 50.
  - getPreferredValues
```
public List<Region> getPreferredValues()
```
    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...
    
    Status:
    Stable ICU 50.
  - contains
```
public boolean contains(Region other)
```
    Returns:
    
    Returns true if this region contains the supplied other region anywhere in the region hierarchy.
    
    Status:
    Stable ICU 50.
  - toString
```
public String toString()
```
    Returns the string representation of this region
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    The string representation of this region, which is its ID.
    
    Status:
    Stable ICU 50.
  - getNumericCode
```
public int getNumericCode()
```
    Returns the numeric code for this region
    
    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.
    
    Status:
    Stable ICU 50.
  - getType
```
public Region.RegionType getType()
```
    Returns this region's type.
    
    Returns:
    
    This region's type classification, such as MACROREGION or TERRITORY.
    
    Status:
    Stable ICU 50.
  - compareTo
```
public int compareTo(Region other)
```
    Specified by:
    
    compareTo in interface Comparable<Region>
    
    Status:
    Stable ICU 50.

Class Region

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstance

getInstance

getAvailable

getContainingRegion

getContainingRegion

getContainedRegions

getContainedRegions

getPreferredValues

contains

toString

getNumericCode

getType

compareTo