Java 8 String chars() and codePoints() with Examples

Introduction

This tutorial explains the two methods Java 8 added to turn a string into a stream of its characters: chars() and codePoints(). Both are declared in CharSequence, so they work on String, StringBuilder and StringBuffer, and both return an IntStream - not a stream of Characters. We will see why, how to get chars back, and use the two methods for the everyday string tasks: counting a character or the vowels, checking that a string is all digits, counting how often each character occurs, finding the first character that does not repeat, and filtering a string. Lastly we will see where the two methods differ - characters outside the Basic Multilingual Plane, such as emoji - and which one to use.

(Note - This tutorial uses IntStream and mapToObj(), explained in Java 8 primitive streamsClick to read tutorial: Java 8 Primitive Streams: mapToInt, mapToObj and boxed.)

chars() and codePoints()

  • IntStream chars(): one int for every char of the sequence - every UTF-16 code unit. The stream has as many elements as length() returns.
  • IntStream codePoints(): one int for every Unicode code point, that is, every character as Unicode counts them. A character outside the Basic Multilingual Plane is stored as two chars - a surrogate pair - and appears in this stream as a single value.
Both return an IntStream because there is no CharStream in Java, and because a code point does not fit into a char anyway. The values are the character codes - 'a' is 97 - so you will often cast them back with (char) c, or pass them to the int versions of the Character methods, such as Character.isDigit(int) and Character.isLetter(int).

Java 8 code example of String.chars()

The first program uses chars() for the common string tasks.
Java 8 code using String.chars() to count, check, group and filter the characters of a string
//StringChars.java
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;

public class StringChars {

  public static void main(String[] args) {
    String text = "hello world";

    // 1. Count one character and count the vowels
    long os = text.chars().filter(c -> c == 'o').count();
    long vowels = text.chars().filter(c -> "aeiou".indexOf(c) >= 0).count();
    System.out.println("1. 'o' occurs " + os + " times, vowels: " + vowels);

    // 2. The elements are ints: printing them directly shows the character codes
    System.out.print("2. as ints: ");
    "Java".chars().forEach(c -> System.out.print(c + " "));
    System.out.print(" as chars: ");
    "Java".chars().forEach(c -> System.out.print((char) c));
    System.out.println();

    // 3. Check every character: allMatch with Character.isDigit(int)
    System.out.println("3. \"2026\" all digits? " + "2026".chars().allMatch(Character::isDigit)
        + ", \"20x6\" all digits? " + "20x6".chars().allMatch(Character::isDigit));

    // 4. How often each character occurs, in the order of first appearance
    Map<Character, Long> frequency = "mississippi".chars()
        .mapToObj(c -> (char) c)
        .collect(Collectors.groupingBy(Function.identity(), LinkedHashMap::new, Collectors.counting()));
    System.out.println("4. " + frequency);

    // 5. The first character that does not repeat
    Map<Character, Long> counts = "swiss".chars()
        .mapToObj(c -> (char) c)
        .collect(Collectors.groupingBy(Function.identity(), LinkedHashMap::new, Collectors.counting()));
    Character firstUnique = counts.entrySet().stream()
        .filter(e -> e.getValue() == 1)
        .map(Map.Entry::getKey)
        .findFirst()
        .orElse(null);
    System.out.println("5. first non-repeated character in \"swiss\": " + firstUnique);

    // 6. Filter a string and build a new one from the stream
    String cleaned = "J-a v@a 8!".chars()
        .filter(Character::isLetterOrDigit)
        .collect(StringBuilder::new, StringBuilder::appendCodePoint, StringBuilder::append)
        .toString();
    System.out.println("6. cleaned: " + cleaned);

    // 7. Each character as a String, joined with Collectors.joining()
    String upper = "stream".chars()
        .mapToObj(c -> String.valueOf((char) Character.toUpperCase(c)))
        .collect(Collectors.joining("-"));
    System.out.println("7. " + upper);
  }
}
 OUTPUT of the above code
1. 'o' occurs 2 times, vowels: 3
2. as ints: 74 97 118 97  as chars: Java
3. "2026" all digits? true, "20x6" all digits? false
4. {m=1, i=4, s=4, p=2}
5. first non-repeated character in "swiss": w
6. cleaned: Java8
7. S-T-R-E-A-M

Explanation of the code

  • Part 1: c == 'o' compares the int with the char literal, which Java widens to 111, so no cast is needed. "aeiou".indexOf(c) takes an int too.
  • Part 2: the trap everyone meets once. forEach(c -> System.out.print(c)) prints the numbers 74, 97, 118 and 97; cast to char to print the letters.
  • Part 3: Character::isDigit matches IntPredicate through Character.isDigit(int). allMatch() stops at the first character that is not a digit.
  • Part 4: mapToObj(c -> (char) c) turns the IntStream into a Stream<Character>, which can be groupedClick to read: Tutorial on grouping with collectors. The LinkedHashMap::new factory keeps the characters in the order they first appear; counting() counts each group.
  • Part 5: with the counts in order of first appearance, the first entry with a count of 1 is the answer - w, because s appears three times. This is a popular interview question.
  • Part 6: an IntStream cannot use Collectors.joining(), but its three-argument collect() can build a StringBuilder: appendCodePoint(int) adds each value as a character, and append merges two builders when the stream runs in parallel.
  • Part 7: the alternative: turn each value into a one-character String with mapToObj(), then use any string collector, here joining("-").
Parts 4 and 5 follow the pattern behind most character puzzles: from ints to Characters, then a collector. Java 8 pipeline counting characters - String.chars() IntStream, mapToObj to Character, groupingBy with counting into a LinkedHashMap

Where chars() and codePoints() differ

A char holds 16 bits, enough for the 65,536 characters of the Basic Multilingual Plane - Latin, Greek, Cyrillic, Chinese and most other scripts. Unicode has more than a million code points, though. Emoji, many mathematical symbols and some rarer scripts lie above U+FFFF, and a Java string stores each of them as two chars, a high and a low surrogate. Java 8 String chars() returns two surrogate code units for an emoji while codePoints() returns one code point The method chars() returns the two surrogates as two separate values, neither of which is a valid character on its own. codePoints() combines them into one value. The second program shows the difference with a grinning-face emoji (U+1F600) and the mathematical letter double-struck A (U+1D538), written with \u escapes so the source file stays plain ASCII.

Java 8 code comparing String.chars() and codePoints() on characters outside the Basic Multilingual Plane
//CodePoints.java
import java.util.List;
import java.util.stream.Collectors;

public class CodePoints {

  // each piece as the hex value of its first code point, and its length in chars
  static String describe(List<String> pieces) {
    return pieces.stream()
        .map(p -> Integer.toHexString(p.codePointAt(0)).toUpperCase() + "(" + p.length() + ")")
        .collect(Collectors.joining(" "));
  }

  public static void main(String[] args) {
    String greeting = "Hi😀!";            // H, i, grinning face (U+1F600), !

    // 1. length() and chars() count UTF-16 code units, codePoints() counts characters
    System.out.println("1. length: " + greeting.length()
        + ", chars: " + greeting.chars().count()
        + ", codePoints: " + greeting.codePoints().count());

    // 2. The values each stream returns
    System.out.print("2. chars():      ");
    greeting.chars().forEach(c -> System.out.printf("%04X ", c));
    System.out.print("\n   codePoints(): ");
    greeting.codePoints().forEach(c -> System.out.printf("%04X ", c));
    System.out.println();

    // 3. Character.getName() works on code points
    System.out.print("3. ");
    greeting.codePoints().forEach(c -> System.out.print(Character.getName(c) + "; "));
    System.out.println();

    // 4. Counting letters: a surrogate on its own is not a letter
    String letters = "𝔸BC";             // double-struck A (U+1D538), B, C
    System.out.println("4. letters by chars(): " + letters.chars().filter(Character::isLetter).count()
        + ", by codePoints(): " + letters.codePoints().filter(Character::isLetter).count());

    // 5. Building a string from code points keeps the pairs together
    String noPunctuation = greeting.codePoints()
        .filter(c -> c != '!')
        .collect(StringBuilder::new, StringBuilder::appendCodePoint, StringBuilder::append)
        .toString();
    System.out.println("5. without '!': " + noPunctuation.codePoints().count() + " code points, "
        + noPunctuation.length() + " chars");

    // 6. Getting the characters back as Strings: chars() splits the emoji, codePoints() keeps it whole
    List<String> byChars = greeting.chars()
        .mapToObj(c -> String.valueOf((char) c))
        .collect(Collectors.toList());
    List<String> byCodePoints = greeting.codePoints()
        .mapToObj(c -> new String(Character.toChars(c)))
        .collect(Collectors.toList());
    System.out.println("6. from chars():      " + describe(byChars));
    System.out.println("   from codePoints(): " + describe(byCodePoints));
  }
}
 OUTPUT of the above code
1. length: 5, chars: 5, codePoints: 4
2. chars():      0048 0069 D83D DE00 0021
   codePoints(): 0048 0069 1F600 0021
3. LATIN CAPITAL LETTER H; LATIN SMALL LETTER I; GRINNING FACE; EXCLAMATION MARK;
4. letters by chars(): 2, by codePoints(): 3
5. without '!': 3 code points, 4 chars
6. from chars():      48(1) 69(1) D83D(1) DE00(1) 21(1)
   from codePoints(): 48(1) 69(1) 1F600(2) 21(1)
  • Part 1: the string has four characters, but length() and chars() count five, because the emoji takes two chars. codePoints() counts four.
  • Part 2: in hexadecimal, chars() returns the surrogates D83D and DE00, and codePoints() the single code point 1F600.
  • Part 3: Character.getName() takes a code point, so it can name the emoji. (The program prints names rather than the emoji itself, which not every console can show.)
  • Part 4: Character::isLetter resolves to isLetter(int) in both streams. A surrogate is not a letter, so chars() finds only B and C, while codePoints() also counts the double-struck A.
  • Part 5: collecting with appendCodePoint() writes each code point back as one or two chars, so the emoji survives the round trip: three code points, four chars.
  • Part 6: splitting the greeting into one String per character. Casting each chars() value to char gives five one-char strings, two of them a lone surrogate - broken halves of the emoji that show as ? or a box. Character.toChars(c) turns a code point into the one or two chars it needs, so codePoints() gives four strings, the emoji whole with a length of 2. (The program prints each string's first code point in hex and its length in brackets.)

Characters made of several code points

Even codePoints() does not always give what a reader would call one character. An accented letter can be stored as one code point - é, U+00E9 - or as two: the plain letter e followed by a combining acute accent, U+0301. Both look the same on screen, but the second is two code points. Splitting text into such user-perceived characters needs java.text.BreakIterator, and java.text.Normalizer converts between the two forms.
Java 8 code counting user-perceived characters with BreakIterator and converting combining accents with Normalizer
//Graphemes.java
import java.text.BreakIterator;
import java.text.Normalizer;

public class Graphemes {

  // counts the user-perceived characters of a string
  static int countCharacters(String s) {
    BreakIterator it = BreakIterator.getCharacterInstance();
    it.setText(s);
    int count = 0;
    while (it.next() != BreakIterator.DONE) {
      count++;
    }
    return count;
  }

  static void show(String label, String s) {
    System.out.println(label + " length: " + s.length() + ", codePoints: " + s.codePoints().count()
        + ", BreakIterator: " + countCharacters(s));
  }

  public static void main(String[] args) {
    String oneCodePoint = "café";          // e with acute accent as one code point
    String combining = "café";            // e + combining acute accent

    show("1. caf\\u00E9: ", oneCodePoint);
    show("2. cafe\\u0301:", combining);
    System.out.println("3. equal? " + oneCodePoint.equals(combining)
        + ", equal after NFC normalization? "
        + oneCodePoint.equals(Normalizer.normalize(combining, Normalizer.Form.NFC)));
  }
}
 OUTPUT of the above code
1. caf\u00E9:  length: 4, codePoints: 4, BreakIterator: 4
2. cafe\u0301: length: 5, codePoints: 5, BreakIterator: 4
3. equal? false, equal after NFC normalization? true
  • Parts 1 and 2: both strings read "café". The first has four code points; the second has five, because its accent is a code point of its own. BreakIterator.getCharacterInstance() finds the boundaries between user-perceived characters and counts four in both.
  • Part 3: the two strings are not equals(), although they look the same. Normalizer.normalize(s, Normalizer.Form.NFC) combines the letter and the accent into one code point, after which they are equal. Normalize text before comparing or searching it when it can come from different sources.
Emoji can be built from several code points as well - a family emoji is several people joined by an invisible zero-width joiner, and a flag is two regional-indicator letters. Java 8's BreakIterator does not keep such sequences together; it does so since JDK 20, which follows the current Unicode rules. From Java 9 on, the regular expression \X also matches one user-perceived character.

Which one to use

  1. codePoints() - use for text that may contain any character - user input, names, chat messages etc. Reason being - counting, filtering or classifying with chars() would split emoji and other supplementary characters in two.
  2. chars() - Use when text is known to be ASCII or within the BMP - for codes, identifiers, digits, most interview puzzles etc chars() is fine, as those types of values can be cast to char safely.
  3. Getting characters back: mapToObj(c -> (char) c) for chars(); for codePoints() use mapToObj(c -> new String(Character.toChars(c))), because a code point may not fit into one char (part 6 of the second program).
  4. Building a string: collect(StringBuilder::new, StringBuilder::appendCodePoint, StringBuilder::append) works for both streams (part 6 of the first program, part 5 of the second).
  5. Not covered by either: a character made of several code points, such as a letter with a combining accent, needs java.text.BreakIterator, as shown in the previous section.

Summary

In this tutorial we saw that chars() and codePoints() return the characters of a string as an IntStream, and how to get chars or strings back with a cast, mapToObj() or a three-argument collect(). We used chars() to count characters and vowels, check for digits, count each character and find the first one that does not repeat. Lastly we saw that chars() returns UTF-16 code units, so it splits emoji and other characters above U+FFFF into two surrogates, while codePoints() returns one value per character - the safer choice for text that can contain anything. For characters made of several code points, such as a letter with a combining accent, we used BreakIterator and Normalizer.