Java Reference · Text, Formatting and Regex
Unicode and code points in Java
Reference for Unicode in Java: UTF-16 chars versus code points, surrogate pairs, codePoints(), Character methods, normalization and safe string handling.
Unicode assigns a number, a code point, to every character, from U+0000 up to U+10FFFF. Java strings do not store code points directly; they store UTF-16 code units, which are 16-bit char values. A code point up to U+FFFF (the Basic Multilingual Plane) fits in one char. A larger one, such as most emoji, needs two chars called a surrogate pair.
Because of that, String.length() counts code units, not what a reader sees as characters. Code that indexes with charAt() or reverses with a char loop works for ordinary text and silently breaks for supplementary characters. The codePoint* methods and Character utilities exist to do it correctly.
String s = "A" + Character.toString(0x1F600); // 'A' and a grinning face s.length(); // 3 (A + two surrogates) s.codePointCount(0, 3); // 2
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
| Member | Description |
|---|---|
String.codePointAt(int index) |
the code point starting at a char index |
String.codePointCount(int begin, int end) |
number of code points in a range |
String.offsetByCodePoints(int index, int n) |
char index reached after moving n code points |
String.codePoints() |
IntStream of code points (since Java 8) |
Character.toChars(int cp) |
char[] with one or two units |
Character.toString(int cp) |
a string for one code point (Java 11) |
Character.charCount(int cp) |
1 for BMP, 2 for supplementary |
Character.isSurrogate(char), isHighSurrogate, isLowSurrogate |
surrogate tests |
Character.isSupplementaryCodePoint(int), isValidCodePoint(int) |
range checks |
Character.isLetter(int), isDigit(int), isWhitespace(int), getType(int) |
classification (use the int overloads) |
Character.getName(int), UnicodeScript.of(int), UnicodeBlock.of(int) |
metadata |
StringBuilder.appendCodePoint(int) |
append a code point |
Normalizer.normalize(CharSequence, Form) |
NFC, NFD, NFKC, NFKD normalization |
Usage notes
charis not a character. Treat it as a UTF-16 code unit. Acharvariable cannot hold an emoji; useintfor code points.- Use the
intoverloads.Character.isLetter(char)returnsfalsefor half of a surrogate pair;Character.isLetter(int)sees the whole code point. - Lone surrogates are legal in a
String. Java does not reject them, but they cannot be encoded to valid UTF-8 and become?or a replacement character when written. - Code points are still not "what users see". An emoji with a skin-tone modifier or a flag is several code points, and
eplus an accent is two. For grapheme clusters usejava.text.BreakIterator.getCharacterInstance()(or\Xin regex since Java 9). - Compare normalized text. Visually identical strings can differ in code points, so normalize (usually NFC) before comparing or hashing user input.
- Case and length. Upper-casing
ßproducesSS, so a string can get longer. Always usetoUpperCase(Locale.ROOT)for machine data. - Source encoding. Since Java 18 the default charset is UTF-8, and source files are read as UTF-8 unless you configure otherwise. Unicode escapes are a safe fallback for non-ASCII literals; see escape sequences.
- Length limits. Databases and protocols may count bytes or code points;
String.length()matches neither. UsegetBytes(StandardCharsets.UTF_8).lengthfor bytes.