Java Doc for UCharacter.java in  » Internationalization-Localization » icu4j » com » ibm » icu » lang » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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:

• UCharacter is not designed to be a char wrapper and does not have APIs to which involves management of that single char.
  These include:
  • char charValue(),
  • int compareTo(java.lang.Character, java.lang.Character), etc.
• UCharacter does not include Character APIs that are deprecated, nor does it include the Java-specific character information, such as boolean isJavaIdentifierPart(char ch).
• Character maps characters 'A' - 'Z' and 'a' - 'z' to the numeric values '10' - '35'. UCharacter also does this in digit and getNumericValue, to adhere to the java semantics of these methods. New methods unicodeDigit, and getUnicodeNumericValue do not treat the above code points as having numeric values. This is a semantic change from ICU4J 1.3.1.

Further detail differences can be determined from 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 (http://icu.sourceforge.net/userguide/properties.html).

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<

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

Note: There are several ICU (and Java) whitespace functions. Comparison: - isUWhiteSpace=UCHAR_WHITE_SPACE: Unicode White_Space property; most of general categories "Z" (separators) + most whitespace ISO controls (including no-break spaces, but excluding IS1..IS4 and ZWSP) - isWhitespace: Java isWhitespace; Z + whitespace ISO controls but excluding no-break spaces - isSpaceChar: just Z (including no-break spaces)

This class is not subclassable

This function only returns the simple, single-code point case mapping. Full case mappings should be used whenever possible because they produce better results by working on whole strings. They can map to a result string with a different length as appropriate. Full case mappings are applied by the case mapping functions that take String parameters rather than code points (int). See also the User Guide chapter on C/POSIX migration: http://icu.sourceforge.net/userguide/posix.html#case_mappings
Parameters:
  ch - the character to be converted
Parameters:
  defaultmapping - Indicates if all mappings defined in CaseFolding.txt is to be used, otherwise the mappings for dotted I and dotless i marked with 'I' in CaseFolding.txt will be skipped.

This function only returns the simple, single-code point case mapping. Full case mappings should be used whenever possible because they produce better results by working on whole strings. They can map to a result string with a different length as appropriate. Full case mappings are applied by the case mapping functions that take String parameters rather than code points (int). See also the User Guide chapter on C/POSIX migration: http://icu.sourceforge.net/userguide/posix.html#case_mappings
Parameters:
  ch - the character to be converted
Parameters:
  options - A bit set for special processing.

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

Find a Unicode character by either its name and return its code point value.

Find a Unicode code point by its most current Unicode name and return its code point value.

Find a Unicode character by its version 1.0 Unicode name and return its code point value.

Retrieves a name for a valid codepoint.

Gets an iterator for character names, iterating over codepoints.

This API only gets the iterator for the extended names.

• UProperty.BIDI_CLASS: 0/18 (UCharacterDirection.LEFT_TO_RIGHT/UCharacterDirection.BOUNDARY_NEUTRAL)
• UProperty.SCRIPT: 0/45 (UScript.COMMON/UScript.TAGBANWA)
• UProperty.IDEOGRAPHIC: 0/1 (false/true)

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

Gets an iterator for character names, iterating over codepoints.

This API only gets the iterator for the older 1.0 Unicode names.

Gets an iterator for character names, iterating over codepoints.

This API only gets the iterator for the modern, most up-to-date Unicode names.

Get the numeric value for a Unicode code point as defined in the Unicode Character Database.

A "double" return type is necessary because some numeric values are fractions, negative, or too large for int.

For characters without any numeric values in the Unicode Character Database, this function will return NO_NUMERIC_VALUE.

API Change: In release 2.2 and prior, this API has a return type int and returns -1 when the argument ch does not have a corresponding numeric value.

Check a binary Unicode property for a code point.

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

This API is 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.

This API does not check the validity of the codepoint.

Important: If ICU is built with UCD files from Unicode versions below 3.2, then properties marked with "new" are not or not fully available.

• Out of bounds, less than 0 or greater than UCharacter.MAX_VALUE
• A surrogate value, 0xD800 to 0xDFFF
• Not-a-character, having the form 0x xxFFFF or 0x xxFFFE

• Out of bounds, less than 0 or greater than UCharacter.MAX_VALUE
• A surrogate value, 0xD800 to 0xDFFF
• Not-a-character, having the form 0x xxFFFF or 0x xxFFFE

• It is a Unicode space separator (category "Zs"), but is not a no-break space (\u00A0 or \u202F or \uFEFF).
• It is a Unicode line separator (category "Zl").
• It is a Unicode paragraph separator (category "Zp").
• It is \u0009, HORIZONTAL TABULATION.

Gets the titlecase version of the argument string.

Position for titlecasing is determined by the argument break iterator, hence the user can customized his break iterator for a specialized titlecasing.

Gets the titlecase version of the argument string.

Position for titlecasing is determined by the argument break iterator, hence the user can customized his break iterator for a specialized titlecasing.

Gets the titlecase version of the argument string.

Position for titlecasing is determined by the argument break iterator, hence the user can customized his break iterator for a specialized titlecasing.

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

This function only returns the simple, single-code point case mapping. Full case mappings should be used whenever possible because they produce better results by working on whole strings. They can map to a result string with a different length as appropriate. Full case mappings are applied by the case mapping functions that take String parameters rather than code points (int). See also the User Guide chapter on C/POSIX migration: http://icu.sourceforge.net/userguide/posix.html#case_mappings
Parameters:
  ch - the character to be converted
Parameters:
  defaultmapping - Indicates if all mappings defined in CaseFolding.txt is to be used, otherwise the mappings for dotted I and dotless i marked with 'I' in CaseFolding.txt will be skipped. the case folding equivalent of the character, if any; otherwise the character itself.
See Also:   UCharacter.foldCase(String,boolean)

This function only returns the simple, single-code point case mapping. Full case mappings should be used whenever possible because they produce better results by working on whole strings. They can map to a result string with a different length as appropriate. Full case mappings are applied by the case mapping functions that take String parameters rather than code points (int). See also the User Guide chapter on C/POSIX migration: http://icu.sourceforge.net/userguide/posix.html#case_mappings
Parameters:
  ch - the character to be converted
Parameters:
  options - A bit set for special processing. Currently the recognised options areFOLD_CASE_EXCLUDE_SPECIAL_I and FOLD_CASE_DEFAULT the case folding equivalent of the character, if any; otherwise the character itself.
See Also:   UCharacter.foldCase(String,boolean)

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

Find a Unicode character by either its name and return its code point value. All Unicode names are in uppercase. Extended names are all lowercase except for numbers and are contained within angle brackets.

• Most current Unicode name if there is any
• Unicode 1.0 name if there is any
• Extended name in the form of "". E.g.

Find a Unicode code point by its most current Unicode name and return its code point value. All Unicode names are in uppercase.

Find a Unicode character by its version 1.0 Unicode name and return its code point value. All Unicode names are in uppercase.

Retrieves a name for a valid codepoint. Unlike, getName(int) and getName1_0(int), this method will return a name even for codepoints that are not assigned a name in UnicodeData.txt.

• Most current Unicode name if there is any
• Unicode 1.0 name if there is any
• Extended name in the form of "". E.g.

Gets an iterator for character names, iterating over codepoints.

This API only gets the iterator for the extended names. For modern, most up-to-date Unicode names use getNameIterator() or for older 1.0 Unicode names use get1_0NameIterator().

 ValueIterator iterator = UCharacter.getExtendedNameIterator();
 ValueIterator.Element element = new ValueIterator.Element();
 while (iterator.next(element)) {
 System.out.println("Codepoint \\u" + 
 Integer.toHexString(element.codepoint) +
 " has the name " + (String)element.value);
 }
 

The maximal range which the name iterator iterates is from an iterator

• UProperty.BIDI_CLASS: 0/18 (UCharacterDirection.LEFT_TO_RIGHT/UCharacterDirection.BOUNDARY_NEUTRAL)
• UProperty.SCRIPT: 0/45 (UScript.COMMON/UScript.TAGBANWA)
• UProperty.IDEOGRAPHIC: 0/1 (false/true)

Gets 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; 
 

Gets an iterator for character names, iterating over codepoints.

This API only gets the iterator for the older 1.0 Unicode names. For modern, most up-to-date Unicode names use getNameIterator() or for extended names use getExtendedNameIterator().

 ValueIterator iterator = UCharacter.get1_0NameIterator();
 ValueIterator.Element element = new ValueIterator.Element();
 while (iterator.next(element)) {
 System.out.println("Codepoint \\u" + 
 Integer.toHexString(element.codepoint) +
 " has the name " + (String)element.value);
 }
 

The maximal range which the name iterator iterates is from an iterator

Gets an iterator for character names, iterating over codepoints.

This API only gets the iterator for the modern, most up-to-date Unicode names. For older 1.0 Unicode names use get1_0NameIterator() or for extended names use getExtendedNameIterator().

 ValueIterator iterator = UCharacter.getNameIterator();
 ValueIterator.Element element = new ValueIterator.Element();
 while (iterator.next(element)) {
 System.out.println("Codepoint \\u" + 
 Integer.toHexString(element.codepoint) +
 " has the name " + (String)element.value);
 }
 

The maximal range which the name iterator iterates is from UCharacter.MIN_VALUE to UCharacter.MAX_VALUE.

Gets an iterator for character types, iterating over codepoints.

 RangeValueIterator iterator = UCharacter.getTypeIterator();
 RangeValueIterator.Element element = new RangeValueIterator.Element();
 while (iterator.next(element)) {
 System.out.println("Codepoint \\u" + 
 Integer.toHexString(element.start) + 
 " to codepoint \\u" +
 Integer.toHexString(element.limit - 1) + 
 " has the character type " + 
 element.value);
 }
 

Get the numeric value for a Unicode code point as defined in the Unicode Character Database.

A "double" return type is necessary because some numeric values are fractions, negative, or too large for int.

For characters without any numeric values in the Unicode Character Database, this function will return NO_NUMERIC_VALUE.

API Change: In release 2.2 and prior, this API has a return type int and returns -1 when the argument ch does not have a corresponding numeric value. This has been changed to synch with ICU4C

Check a binary Unicode property for a code point.

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

This API is 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.

This API does not check the validity of the codepoint.

Important: If ICU is built with UCD files from Unicode versions below 3.2, then properties marked with "new" are not or not fully available.

• Out of bounds, less than 0 or greater than UCharacter.MAX_VALUE
• A surrogate value, 0xD800 to 0xDFFF
• Not-a-character, having the form 0x xxFFFF or 0x xxFFFE

• Out of bounds, less than 0 or greater than UCharacter.MAX_VALUE
• A surrogate value, 0xD800 to 0xDFFF
• Not-a-character, having the form 0x xxFFFF or 0x xxFFFE

Check if a code point has the Alphabetic Unicode property.

Same as UCharacter.hasBinaryProperty(ch, UProperty.ALPHABETIC).

Different from UCharacter.isLetter(ch)!

Check if a code point has the Lowercase Unicode property.

Same as UCharacter.hasBinaryProperty(ch, UProperty.LOWERCASE).

This is different from UCharacter.isLowerCase(ch)!

Check if a code point has the Uppercase Unicode property.

Same as UCharacter.hasBinaryProperty(ch, UProperty.UPPERCASE).

This is different from UCharacter.isUpperCase(ch)!

Check if a code point has the White_Space Unicode property.

Same as UCharacter.hasBinaryProperty(ch, UProperty.WHITE_SPACE).

This is different from both UCharacter.isSpace(ch) and UCharacter.isWhitespace(ch)!

• Lu Uppercase letter
• Ll Lowercase letter
• Lt Titlecase letter
• Lm Modifier letter
• Lo Other letter
• Nl Letter number
• Pc Connecting punctuation character
• Nd decimal number
• Mc Spacing combining mark
• Mn Non-spacing mark
• Cf formatting code

• Lu Uppercase letter
• Ll Lowercase letter
• Lt Titlecase letter
• Lm Modifier letter
• Lo Other letter
• Nl Letter number

• It is a Unicode space separator (category "Zs"), but is not a no-break space (\u00A0 or \u202F or \uFEFF).
• It is a Unicode line separator (category "Zl").
• It is a Unicode paragraph separator (category "Zp").
• It is \u0009, HORIZONTAL TABULATION.
• It is \u000A, LINE FEED.
• It is \u000B, VERTICAL TABULATION.
• It is \u000C, FORM FEED.
• It is \u000D, CARRIAGE RETURN.
• It is \u001C, FILE SEPARATOR.
• It is \u001D, GROUP SEPARATOR.
• It is \u001E, RECORD SEPARATOR.
• It is \u001F, UNIT SEPARATOR.

This function only returns the simple, single-code point case mapping. Full case mappings should be used whenever possible because they produce better results by working on whole strings. They take into account the string context and the language and can map to a result string with a different length as appropriate. Full case mappings are applied by the case mapping functions that take String parameters rather than code points (int). See also the User Guide chapter on C/POSIX migration: http://icu.sourceforge.net/userguide/posix.html#case_mappings
Parameters:
  ch - code point whose lowercase equivalent is to be retrieved the lowercase equivalent code point

This function only returns the simple, single-code point case mapping. Full case mappings should be used whenever possible because they produce better results by working on whole strings. They take into account the string context and the language and can map to a result string with a different length as appropriate. Full case mappings are applied by the case mapping functions that take String parameters rather than code points (int). See also the User Guide chapter on C/POSIX migration: http://icu.sourceforge.net/userguide/posix.html#case_mappings
Parameters:
  ch - code point whose title case is to be retrieved titlecase code point

Gets the titlecase version of the argument string.

Position for titlecasing is determined by the argument break iterator, hence the user can customized his break iterator for a specialized titlecasing. In this case only the forward iteration needs to be implemented. If the break iterator passed in is null, the default Unicode algorithm will be used to determine the titlecase positions.

Only positions returned by the break iterator will be title cased, character in between the positions will all be in lower case.

Casing is dependent on the default locale and context-sensitive

Gets the titlecase version of the argument string.

Position for titlecasing is determined by the argument break iterator, hence the user can customized his break iterator for a specialized titlecasing. In this case only the forward iteration needs to be implemented. If the break iterator passed in is null, the default Unicode algorithm will be used to determine the titlecase positions.

Only positions returned by the break iterator will be title cased, character in between the positions will all be in lower case.

Casing is dependent on the argument locale and context-sensitive

Gets the titlecase version of the argument string.

Position for titlecasing is determined by the argument break iterator, hence the user can customized his break iterator for a specialized titlecasing. In this case only the forward iteration needs to be implemented. If the break iterator passed in is null, the default Unicode algorithm will be used to determine the titlecase positions.

Only positions returned by the break iterator will be title cased, character in between the positions will all be in lower case.

Casing is dependent on the argument locale and context-sensitive

This function only returns the simple, single-code point case mapping. Full case mappings should be used whenever possible because they produce better results by working on whole strings. They take into account the string context and the language and can map to a result string with a different length as appropriate. Full case mappings are applied by the case mapping functions that take String parameters rather than code points (int). See also the User Guide chapter on C/POSIX migration: http://icu.sourceforge.net/userguide/posix.html#case_mappings
Parameters:
  ch - code point whose uppercase is to be retrieved uppercase code point