区域和地区API

ICU第8347号票据(原始ICU4J API-ICU 4.8中的技术预览)和ICU第8451号票据(ICU4J-API端口到ICU4C)-第9587号票据(将ICU4J API移至草稿状态)

为了提供有关地区和遏制的信息,本提案不仅试图提供遏制API,还提供了一个框架,通过该框架可以向用户提供其他基于地区和地区的信息。

术语

Unicode LDML中定义了Unicode区域代码(也称为Unicode区域子标记)(http://unicode.org/reports/tr35/#unicode语言和本地标识符),基于BCP47。有不同类型的地区代码需要区分:

宏观区域-联合国M.49定义的“宏观地理(大陆)区域、地理分区或选定的经济和其他分组”代码(http://unstats.un.org/unsd/methods/m49/m49regin.htm). 这些代码通常是3位数字,但包含一些2个字母的代码,例如为Outlying Oceania添加的LDML代码QO。大区域在ICU中由三种区域类型之一表示:WORLD(区域代码001),

大陆(世界直接包含的地区)和次大陆(大陆直接包含的事物)。

领土-不是宏区域的区域。这些通常是国家代码,但也包括非独立国家的区域,例如南极洲代码“AQ”或香港代码“HK”(中国特别行政区)。国家的海外属地可能有也可能没有单独的代码。这些代码通常是2个字母的代码,但BCP47允许将来使用3位代码。

分组-一个被广泛理解的、具有明确成员身份的地区分组,因此为其分配了一个地区代码。其中一些是UNM.49代码,不属于世界/大陆/次大陆层次结构,而另一些只是拥有自己地区代码的众所周知的分组。区域“EU”(欧盟)就是这样一个区域代码,它是一个分组。getContainingRegion()API永远不会返回分组,因为不同类型的区域(WORLD、CONTAINT或SUBCONTAINT)将始终是包含区域。

未知区域-代码ZZ由Unicode LDML定义,用于指示区域未知或作为区域提供的值无效。

已弃用-过去已定义但现在不再使用的地区代码,通常是由于一个国家分裂为多个领土或更名。

新类-地区

建议将以下新类别和方法纳入ICU:

ICU4J-com.ibm.icu.util。地区

父类-java.lang.Object

嵌套类摘要

区域类型-包含各种类型区域的枚举。目前,它只包含上述术语声明中的以下类型:WORLD、CONTINENT、SUBCONTINENT,TERRITORY、GROUPING、DEPRECATED或UNKNOWN。如果CLDR中包含此类数据,则未来可将此类数据扩展到其他类型的分组,如州、省等。

工厂方法总结

公共静态区域getInstance(String Region_code)

使用给定的区域代码返回区域。地区代码可以是2位ISO代码、3位ISO代码、UNM.49数字代码或CLDR定义的其他有效Unicode地区代码。函数ULocale.getCountry()应该为该函数返回合适的输入。如果区域代码为NULL或无法识别,将抛出相应的异常(分别为NullPointerException或IllegalArgumentException)。

公共静态区域getInstance(int代码)

使用给定的数字区域代码返回区域。如果无法识别数字区域代码,将引发非法参数异常。

方法总结

公共静态集<Region>getAvailable(RegionType类型)

返回与给定类型匹配的所有已知区域(由ICU的区域包含数据定义)的不可修改集合。

公共区域getContainingRegion()

返回地理上包含此区域的区域。如果此区域的代码为“001”(世界)或“ZZ”(未知区域),则返回NULL。例如,使用区域“IT”(意大利)调用此方法将返回区域“039”(南欧)。

公共区域getContainingRegion(RegionType类型)

返回地理上包含此区域并与给定类型匹配的区域,如有必要,将多个步骤向上移动包含链。如果找不到与给定类型匹配的包含区域,则返回NULL。(注意:RegionTypes=“GROUPING”、“DEPRECATED”或“UNKNOWN”不适合在此API中使用。在这种情况下,将抛出IllegalArgumentException。)例如,使用区域“IT”(意大利)调用类型“CONTINENT”的此方法会返回区域“150”(欧洲)。

公共集合<Region>getContainedRegions()

返回一个不可修改的集合,其中包含区域层次结构中该区域的所有直接子区域。根据CLDR中定义的包含数据,这些返回区域可以是宏区域、区域或两者的混合。如果此区域没有任何子区域,则此API可能会返回空集。例如,使用区域“150”(欧洲)调用此方法会返回一个集合,其中包含欧洲的各个子区域-“039”(南欧)-“151”(东欧)-“154”(北欧)和“155”(西欧)。

公共集<Region>getContainedRegions(RegionType类型)

返回一个不可修改的集合,其中包含区域层次结构中该区域的所有子区域,并与给定类型匹配。如果此区域没有任何与给定类型匹配的子区域,则此API可能返回一个空集。例如,使用区域“150”(欧洲)调用此方法并键入“TERRITORY”,将返回一个包含欧洲所有领土的集合(“FR”(法国)-“IT”(意大利)-“DE”(德国)等)

公共布尔值包含(区域-其他)

如果此区域包含区域层次结构中任何位置提供的其他区域,则返回true。

公共列表<Region>getPreferredValues()

对于不推荐使用的区域,返回作为此区域首选替换区域的区域列表。对于不推荐使用的区域,返回null。例如,使用区域“SU”(苏联)调用此方法将返回包含“RU”(俄罗斯)、“AM”(亚美尼亚)、“AZ”(阿塞拜疆)等区域的列表。。。

公共字符串toString()

返回此对象的字符串表示形式,这是区域的规范Unicode区域代码。

public int getNumericCode()

返回区域的数字代码。如果给定区域没有分配数字代码,则返回UNDEFINED_NUMERIC_CODE(-1)。

公共区域。键入getType()

返回此区域的区域类型。

public int compareTo(其他区域)

用于实现区域的Comparable接口。区域的自然顺序是基于其字符串表示形式(规范ID)的字母顺序。

等效API ICU4C

此设计的范围是仅提供C++类接口,而不实现纯C语言接口。区域类型的枚举将是一个C枚举“URegionType”,以便在将来如果我们认为有必要的话,可以添加一个纯C接口。

地区类别参考

C++类名应为“Region”。

#包括<unicode/region.h>

公共枚举

枚举URegionType{

/**

*表示未知区域的类型。

*/

URGN_UNKNOWN公司,

/**

*表示区域的类型。

*/

URGN_TERRITORY(城市_错误),

/**

*代表整个世界的类型。

*/

URGN_WORLD公司,

/**

*代表大陆的类型。

*/

URGN_集装箱,

/**

*代表亚大陆的类型。

*/

URGN_SUBCONTINENT公司,

/**

*表示不在中使用的区域组的类型

*正常的世界/大陆/次大陆/地区包含树。

*/

URGN_分组,

/**

*表示其代码已弃用的区域的类型,通常

*由于一个国家分裂成多个领土或更名。

*/

URGN_推荐,

}

公共成员功能

UBool运算符==(const Region&that)const

如果两个区域相等,则返回true。

UBool运算符!=(const区域&that)const

如果两个区域不相等,则返回true;也就是说,如果operator==()返回false。

const区域*getContainingRegion()

返回指向包含此区域的区域的指针。如果此区域的代码为“001”(世界)或“ZZ”(未知区域),则返回NULL。例如,使用区域“IT”(意大利)调用此方法会返回区域“039”(南欧)。

const区域*getContainingRegion(URegionType类型)

返回一个指针,指向在地理位置上包含此区域并与给定类型匹配的区域,如有必要,将多个步骤向上移动包含链。如果找不到与给定类型匹配的包含区域,则返回NULL。(注意:RegionTypes=“GROUPING”、“DEPRECATED”或“UNKNOWN”不适合在此API中使用。在这种情况下,将返回NULL。)例如,使用区域“IT”(意大利)调用类型“CONTINENT”的此方法将返回区域“150”(欧洲)。

字符串枚举*getContainedRegions()

返回区域层次结构中此区域的直接子区域的所有区域ID的枚举。根据CLDR中定义的包含数据,这些返回的区域可以是宏区域、区域,也可以是两者的混合。如果此区域没有任何子区域,则此API可能会返回NULL。例如,使用区域“150”(欧洲)调用此方法将返回包含欧洲各个子区域的枚举-“039”(南欧)-“151”(东欧)-“154”(北欧)和“155”(西欧)。

StringEnumeration*getContainedRegions(URegionType类型)

返回区域层次结构中属于此区域的子区域并与给定类型匹配的所有区域的ID的枚举。如果此区域没有任何与给定类型匹配的子区域,则此API可能会返回空集。例如,使用区域“150”(欧洲)调用此方法并键入“TERRITORY”,将返回一个包含欧洲所有领土的集合(“FR”(法国)-“IT”(意大利)-“DE”(德国)等)

UBool包含(常量区域和其他)常量

如果此区域包含区域层次结构中任何位置提供的其他区域,则返回true。

字符串枚举*getPreferredValues()

对于不推荐使用的区域,返回作为此区域首选替换区域的区域ID的枚举。对于不推荐使用的区域,返回null。例如,使用区域“SU”(苏联)调用此方法将返回包含“RU”(俄罗斯)、“AM”(亚美尼亚)、“AZ”(阿塞拜疆)等区域的列表。。。

const char*getRegionCode()

返回此区域的规范区域代码。

int32_t获取数字代码()

返回此区域的数字代码。如果给定区域没有分配数字代码,则返回UNDEFINED_NUMERIC_CODE(-1)。

URegionType获取类型()

返回此区域的区域类型。

工厂方法

静态常量区域*getInstance(const char*Region_code,UErrorCode和status)

使用给定的区域代码返回指向区域的指针。地区代码可以是2个字母的ISO代码、3个字母的国际标准化组织代码、UNM.49数字代码或LDML规范定义的其他有效的Unicode地区代码。标识符将使用CLDR中定义的补充元数据在内部规范化。如果地区代码为NULL或无法识别,将设置相应的错误代码(U_ILLEGAL_ARGUMENT_error)

静态常量区域*getInstance(int32_t代码,UErrorCode和状态)

使用给定的数字区域代码返回指向区域的指针。如果无法识别数字区域代码,将设置相应的错误代码(U_ILLEGAL_ARGUMENT_error)

静态公共成员函数

静态StringEnumeration*getAvailable(RegionType类型)

返回与给定类型匹配的所有已知区域的ID的枚举。