Skip to content
Tutorials Center
My learning

Topics

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.

Java
String s = "A" + Character.toString(0x1F600);   // 'A' and a grinning face
s.length();                // 3 (A + two surrogates)
s.codePointCount(0, 3);    // 2

Try it

Java chars versus code points

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.

Java Classification, case and normalization

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

  • char is not a character. Treat it as a UTF-16 code unit. A char variable cannot hold an emoji; use int for code points.
  • Use the int overloads. Character.isLetter(char) returns false for 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 e plus an accent is two. For grapheme clusters use java.text.BreakIterator.getCharacterInstance() (or \X in 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 ß produces SS, so a string can get longer. Always use toUpperCase(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. Use getBytes(StandardCharsets.UTF_8).length for bytes.