APIdia Launch Partner
Top Description Inners Fields Constructors Methods
jdk.internal.icu.lang

public final Class UCharacter

extends Object
Class Inheritance
Imports
jdk.internal.icu.impl.UBiDiProps, .UCharacterProperty, jdk.internal.icu.text.Normalizer2, .UTF16, jdk.internal.icu.util.VersionInfo

The UCharacter class provides extensions to the java.lang.Character class. These extensions provide support for more Unicode properties and together with the UTF16 class, provide support for supplementary characters (those with code points above U+FFFF). Each ICU release supports the latest version of Unicode available at that time.

Code points are represented in these API using ints. While it would be more convenient in Java to have a separate primitive datatype for them, ints suffice in the meantime.

To use this class please add the jar file name icu4j.jar to the class path, since it contains data files which supply the information used by this file.
E.g. In Windows
set CLASSPATH=%CLASSPATH%;$JAR_FILE_PATH/ucharacter.jar.
Otherwise, another method would be to copy the files uprops.dat and unames.icu from the icu4j source subdirectory $ICU4J_SRC/src/com.ibm.icu.impl.data to your class directory $ICU4J_CLASS/com.ibm.icu.impl.data.

Aside from the additions for UTF-16 support, and the updated Unicode properties, the main differences between UCharacter and Character are:

Further detail on differences can be determined using the program com.ibm.icu.dev.test.lang.UCharacterCompare

In addition to Java compatibility functions, which calculate derived properties, this API provides low-level access to the Unicode Character Database.

Unicode assigns each code point (not just assigned character) values for many properties. Most of them are simple boolean flags, or constants from a small enumerated list. For some properties, values are strings or other relatively more complex types.

For more information see "About the Unicode Character Database" (http://www.unicode.org/ucd/) and the ICU User Guide chapter on Properties (https://unicode-org.github.io/icu/userguide/strings/properties).

There are also functions that provide easy migration from C/POSIX functions like isblank(). Their use is generally discouraged because the C/POSIX standards do not define their semantics beyond the ASCII range, which means that different implementations exhibit very different behavior. Instead, Unicode properties should be used directly.

There are also only a few, broad C/POSIX character classes, and they tend to be used for conflicting purposes. For example, the "isalpha()" class is sometimes used to determine word boundaries, while a more sophisticated approach would at least distinguish initial letters from continuation characters (the latter including combining marks). (In ICU, BreakIterator is the most sophisticated API for word boundaries.) Another example: There is no "istitle()" class for titlecase characters.

ICU 3.4 and later provides API access for all twelve C/POSIX character classes. ICU implements them according to the Standard Recommendations in Annex C: Compatibility Properties of UTS #18 Unicode Regular Expressions (http://www.unicode.org/reports/tr18/#Compatibility_Properties).

API access for C/POSIX character classes is as follows: 

- alpha:     isUAlphabetic(c) or hasBinaryProperty(c, UProperty.ALPHABETIC)
- lower:     isULowercase(c) or hasBinaryProperty(c, UProperty.LOWERCASE)
- upper:     isUUppercase(c) or hasBinaryProperty(c, UProperty.UPPERCASE)
- punct:     ((1<<getType(c)) & ((1<<DASH_PUNCTUATION)|(1<<START_PUNCTUATION)|
              (1<<END_PUNCTUATION)|(1<<CONNECTOR_PUNCTUATION)|(1<<OTHER_PUNCTUATION)|
              (1<<INITIAL_PUNCTUATION)|(1<<FINAL_PUNCTUATION)))!=0
- digit:     isDigit(c) or getType(c)==DECIMAL_DIGIT_NUMBER
- xdigit:    hasBinaryProperty(c, UProperty.POSIX_XDIGIT)
- alnum:     hasBinaryProperty(c, UProperty.POSIX_ALNUM)
- space:     isUWhiteSpace(c) or hasBinaryProperty(c, UProperty.WHITE_SPACE)
- blank:     hasBinaryProperty(c, UProperty.POSIX_BLANK)
- cntrl:     getType(c)==CONTROL
- graph:     hasBinaryProperty(c, UProperty.POSIX_GRAPH)
- print:     hasBinaryProperty(c, UProperty.POSIX_PRINT)

The C/POSIX character classes are also available in UnicodeSet patterns, using patterns like [:graph:] or \p{graph}.

There are several ICU (and Java) whitespace functions. Comparison:

This class is not subclassable.

Author
Syn Wee Quek
ICU Status
Stable since ICU 2.1.
See Also
com.ibm.icu.lang.UCharacterEnums

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
UCharacter.HangulSyllableType

Hangul Syllable Type constants.

public static interface
UCharacter.JoiningGroup

Joining Group constants.

public static interface
UCharacter.NumericType

Numeric Type constants.

Field Summary

Modifier and TypeField and Description
public static final byte
CHAR_CATEGORY_COUNT

Character type count

public static final byte
COMBINING_SPACING_MARK

Character type Mc

public static final byte
ENCLOSING_MARK

Character type Me

public static final int
MAX_VALUE

The highest Unicode code point value (scalar value) according to the Unicode Standard.

public static final int
MIN_VALUE

The lowest Unicode code point value.

public static final byte
NON_SPACING_MARK

Character type Mn

public static final int
RIGHT_TO_LEFT

Directional type R

public static final int
RIGHT_TO_LEFT_ARABIC

Directional type AL

Constructor Summary

AccessConstructor and Description
private
UCharacter()

Private constructor to prevent instantiation

Method Summary

Modifier and TypeMethod and Description
public static int

Returns:

the numeric value represented by the code point in the specified radix, or -1 if the code point is not a decimal digit or if its value is too large for the radix
digit(int
the code point to query
ch, int
the radix
radix)

Returns the numeric value of a decimal digit code point.

public static int

Returns:

the numeric value represented by the code point, or -1 if the code point is not a decimal digit or if its value is too large for a decimal radix
digit(int
the code point to query
ch)

Returns the numeric value of a decimal digit code point.

public static VersionInfo

Returns:

the Unicode version number
getAge(int
The code point.
ch)

Returns the "age" of the code point.

public static int

Returns:

the paired bracket code point, or c itself if there is no such mapping (Bidi_Paired_Bracket_Type=None)
getBidiPairedBracket(int
the code point to be mapped
c)

Maps the specified character to its paired bracket character.

public static int

Returns:

code point if surrogate characters are valid.
getCodePoint(char
the lead char
lead, char
the trail char
trail)

Returns a code point corresponding to the two UTF16 characters.

public static int

Returns:

the combining class of the codepoint
getCombiningClass(int
code point whose combining is to be retrieved
ch)

Returns the combining class of the argument codepoint

public static int

Returns:

direction constant from UCharacterDirection.
getDirection(int
the code point to be determined its direction
ch)

Returns the Bidirection property of a code point.

public static int

Returns:

numeric value that is directly the property value or, for enumerated properties, corresponds to the numeric value of the enumerated constant of the respective property value enumeration type (cast to enum type if necessary). Returns 0 or 1 (for false / true) for binary Unicode properties. Returns a bit-mask for mask properties. Returns 0 if 'type' is out of bounds or if the Unicode version does not have data for the property at all, or not for this code point.
getIntPropertyValue(int
code point to test.
ch, int
UProperty selector constant, identifies which binary property to check. Must be UProperty.BINARY_START <= type < UProperty.BINARY_LIMIT or UProperty.INT_START <= type < UProperty.INT_LIMIT or UProperty.MASK_START <= type < UProperty.MASK_LIMIT.
type)

Returns the property value for an Unicode property type of a code point.

public static int

Returns:

another code point that may serve as a mirror-image substitute, or ch itself if there is no such mapping or ch does not have the "mirrored" property
getMirror(int
code point whose mirror is to be retrieved
ch)

Maps the specified code point to a "mirror-image" code point.

public static int

Returns:

category which is a value of UCharacterCategory
getType(int
code point whose type is to be determined
ch)

Returns a value indicating a code point's Unicode category.

public static VersionInfo

Returns:

the unicode version number used
getUnicodeVersion()

Returns the version of Unicode data used.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

CHAR_CATEGORY_COUNTback to summary
public static final byte CHAR_CATEGORY_COUNT

Character type count

ICU Status
Stable since ICU 2.1.
COMBINING_SPACING_MARKback to summary
public static final byte COMBINING_SPACING_MARK

Character type Mc

ICU Status
Stable since ICU 2.1.
ENCLOSING_MARKback to summary
public static final byte ENCLOSING_MARK

Character type Me

ICU Status
Stable since ICU 2.1.
MAX_VALUEback to summary
public static final int MAX_VALUE

The highest Unicode code point value (scalar value) according to the Unicode Standard. This is a 21-bit value (21 bits, rounded up).
Up-to-date Unicode implementation of java.lang.Character.MAX_VALUE

ICU Status
Stable since ICU 2.1.
MIN_VALUEback to summary
public static final int MIN_VALUE

The lowest Unicode code point value.

ICU Status
Stable since ICU 2.1.
NON_SPACING_MARKback to summary
public static final byte NON_SPACING_MARK

Character type Mn

ICU Status
Stable since ICU 2.1.
RIGHT_TO_LEFTback to summary
public static final int RIGHT_TO_LEFT

Directional type R

ICU Status
Stable since ICU 2.1.
RIGHT_TO_LEFT_ARABICback to summary
public static final int RIGHT_TO_LEFT_ARABIC

Directional type AL

ICU Status
Stable since ICU 2.1.

Constructor Detail

UCharacterback to summary
private UCharacter()

Private constructor to prevent instantiation

Method Detail

digitback to summary
public static int digit(int ch, int radix)

Returns the numeric value of a decimal digit code point.
This method observes the semantics of java.lang.Character.digit(). Note that this will return positive values for code points for which isDigit returns false, just like java.lang.Character.
Semantic Change: In release 1.3.1 and prior, this did not treat the European letters as having a digit value, and also treated numeric letters and other numbers as digits. This has been changed to conform to the java semantics.
A code point is a valid digit if and only if:

  • ch is a decimal digit or one of the european letters, and
  • the value of ch is less than the specified radix.
Parameters
ch:int

the code point to query

radix:int

the radix

Returns:int

the numeric value represented by the code point in the specified radix, or -1 if the code point is not a decimal digit or if its value is too large for the radix

ICU Status
Stable since ICU 2.1.
digitback to summary
public static int digit(int ch)

Returns the numeric value of a decimal digit code point.
This is a convenience overload of digit(int, int) that provides a decimal radix.
Semantic Change: In release 1.3.1 and prior, this treated numeric letters and other numbers as digits. This has been changed to conform to the java semantics.

Parameters
ch:int

the code point to query

Returns:int

the numeric value represented by the code point, or -1 if the code point is not a decimal digit or if its value is too large for a decimal radix

ICU Status
Stable since ICU 2.1.
getAgeback to summary
public static VersionInfo getAge(int ch)

Returns the "age" of the code point.

The "age" is the Unicode version when the code point was first designated (as a non-character or for Private Use) or assigned a character.

This can be useful to avoid emitting code points to receiving processes that do not accept newer characters.

The data is from the UCD file DerivedAge.txt.

Parameters
ch:int

The code point.

Returns:VersionInfo

the Unicode version number

ICU Status
Stable since ICU 2.6.
getBidiPairedBracketback to summary
public static int getBidiPairedBracket(int c)

Maps the specified character to its paired bracket character. For Bidi_Paired_Bracket_Type!=None, this is the same as getMirror(int). Otherwise c itself is returned. See http://www.unicode.org/reports/tr9/

Parameters
c:int

the code point to be mapped

Returns:int

the paired bracket code point, or c itself if there is no such mapping (Bidi_Paired_Bracket_Type=None)

ICU Status
Stable since ICU 52.
See Also
UProperty#BIDI_PAIRED_BRACKET, UProperty#BIDI_PAIRED_BRACKET_TYPE, getMirror(int)
getCodePointback to summary
public static int getCodePoint(char lead, char trail)

Returns a code point corresponding to the two UTF16 characters.

Parameters
lead:char

the lead char

trail:char

the trail char

Returns:int

code point if surrogate characters are valid.

Exceptions
IllegalArgumentException:
thrown when argument characters do not form a valid codepoint
ICU Status
Stable since ICU 2.1.
getCombiningClassback to summary
public static int getCombiningClass(int ch)

Returns the combining class of the argument codepoint

Parameters
ch:int

code point whose combining is to be retrieved

Returns:int

the combining class of the codepoint

ICU Status
Stable since ICU 2.1.
getDirectionback to summary
public static int getDirection(int ch)

Returns the Bidirection property of a code point. For example, 0x0041 (letter A) has the LEFT_TO_RIGHT directional property.
Result returned belongs to the interface UCharacterDirection

Parameters
ch:int

the code point to be determined its direction

Returns:int

direction constant from UCharacterDirection.

ICU Status
Stable since ICU 2.1.
getIntPropertyValueback to summary
public static int getIntPropertyValue(int ch, int type)

Returns the property value for an Unicode property type of a code point. Also returns binary and mask property values.

Unicode, especially in version 3.2, defines many more properties than the original set in UnicodeData.txt.

The properties APIs are intended to reflect Unicode properties as defined in the Unicode Character Database (UCD) and Unicode Technical Reports (UTR). For details about the properties see http://www.unicode.org/.

For names of Unicode properties see the UCD file PropertyAliases.txt. 

Sample usage:
int ea = UCharacter.getIntPropertyValue(c, UProperty.EAST_ASIAN_WIDTH);
int ideo = UCharacter.getIntPropertyValue(c, UProperty.IDEOGRAPHIC);
boolean b = (ideo == 1) ? true : false;
Parameters
ch:int

code point to test.

type:int

UProperty selector constant, identifies which binary property to check. Must be UProperty.BINARY_START <= type < UProperty.BINARY_LIMIT or UProperty.INT_START <= type < UProperty.INT_LIMIT or UProperty.MASK_START <= type < UProperty.MASK_LIMIT.

Returns:int

numeric value that is directly the property value or, for enumerated properties, corresponds to the numeric value of the enumerated constant of the respective property value enumeration type (cast to enum type if necessary). Returns 0 or 1 (for false / true) for binary Unicode properties. Returns a bit-mask for mask properties. Returns 0 if 'type' is out of bounds or if the Unicode version does not have data for the property at all, or not for this code point.

ICU Status
Stable since ICU 2.4.
See Also
UProperty, hasBinaryProperty, getIntPropertyMinValue, getIntPropertyMaxValue, getUnicodeVersion
getMirrorback to summary
public static int getMirror(int ch)

Maps the specified code point to a "mirror-image" code point. For code points with the "mirrored" property, implementations sometimes need a "poor man's" mapping to another code point such that the default glyph may serve as the mirror-image of the default glyph of the specified code point.
This is useful for text conversion to and from codepages with visual order, and for displays without glyph selection capabilities.

Parameters
ch:int

code point whose mirror is to be retrieved

Returns:int

another code point that may serve as a mirror-image substitute, or ch itself if there is no such mapping or ch does not have the "mirrored" property

ICU Status
Stable since ICU 2.1.
getTypeback to summary
public static int getType(int ch)

Returns a value indicating a code point's Unicode category. Up-to-date Unicode implementation of java.lang.Character.getType() except for the above mentioned code points that had their category changed.
Return results are constants from the interface UCharacterCategory

Note

the UCharacterCategory values are not compatible with those returned by java.lang.Character.getType. UCharacterCategory values match the ones used in ICU4C, while java.lang.Character type values, though similar, skip the value 17.

Parameters
ch:int

code point whose type is to be determined

Returns:int

category which is a value of UCharacterCategory

ICU Status
Stable since ICU 2.1.
getUnicodeVersionback to summary
public static VersionInfo getUnicodeVersion()

Returns the version of Unicode data used.

Returns:VersionInfo

the unicode version number used

ICU Status
Stable since ICU 2.1.
jdk.internal.icu.lang back to summary

public Interface UCharacter.HangulSyllableType

Hangul Syllable Type constants.
ICU Status
Stable since ICU 2.6.
See Also
UProperty#HANGUL_SYLLABLE_TYPE

Field Summary

Modifier and TypeField and Description
public static final int
COUNT

public static final int
LEADING_JAMO

public static final int
LV_SYLLABLE

public static final int
LVT_SYLLABLE

public static final int
NOT_APPLICABLE

public static final int
TRAILING_JAMO

public static final int
VOWEL_JAMO

Field Detail

COUNTback to summary
public static final int COUNT
ICU Status
Stable since ICU 2.6.
LEADING_JAMOback to summary
public static final int LEADING_JAMO
ICU Status
Stable since ICU 2.6.
LV_SYLLABLEback to summary
public static final int LV_SYLLABLE
ICU Status
Stable since ICU 2.6.
LVT_SYLLABLEback to summary
public static final int LVT_SYLLABLE
ICU Status
Stable since ICU 2.6.
NOT_APPLICABLEback to summary
public static final int NOT_APPLICABLE
ICU Status
Stable since ICU 2.6.
TRAILING_JAMOback to summary
public static final int TRAILING_JAMO
ICU Status
Stable since ICU 2.6.
VOWEL_JAMOback to summary
public static final int VOWEL_JAMO
ICU Status
Stable since ICU 2.6.
jdk.internal.icu.lang back to summary

public Interface UCharacter.JoiningGroup

Joining Group constants.
ICU Status
Stable since ICU 2.4.
See Also
UProperty#JOINING_GROUP

Field Summary

Modifier and TypeField and Description
public static final int
NO_JOINING_GROUP

Field Detail

NO_JOINING_GROUPback to summary
public static final int NO_JOINING_GROUP
ICU Status
Stable since ICU 2.4.
jdk.internal.icu.lang back to summary

public Interface UCharacter.NumericType

Numeric Type constants.
ICU Status
Stable since ICU 2.4.
See Also
UProperty#NUMERIC_TYPE

Field Summary

Modifier and TypeField and Description
public static final int
COUNT

public static final int
DECIMAL

public static final int
DIGIT

public static final int
NONE

public static final int
NUMERIC

Field Detail

COUNTback to summary
public static final int COUNT
ICU Status
Stable since ICU 2.4.
DECIMALback to summary
public static final int DECIMAL
ICU Status
Stable since ICU 2.4.
DIGITback to summary
public static final int DIGIT
ICU Status
Stable since ICU 2.4.
NONEback to summary
public static final int NONE
ICU Status
Stable since ICU 2.4.
NUMERICback to summary
public static final int NUMERIC
ICU Status
Stable since ICU 2.4.