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(): oneintfor everycharof the sequence - every UTF-16 code unit. The stream has as many elements aslength()returns.IntStream codePoints(): oneintfor every Unicode code point, that is, every character as Unicode counts them. A character outside the Basic Multilingual Plane is stored as twochars - a surrogate pair - and appears in this stream as a single value.
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 useschars() 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);
}
}
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 theintwith thecharliteral, which Java widens to 111, so no cast is needed."aeiou".indexOf(c)takes aninttoo. - Part 2: the trap everyone meets once.
forEach(c -> System.out.print(c))prints the numbers 74, 97, 118 and 97; cast tocharto print the letters. - Part 3:
Character::isDigitmatchesIntPredicatethroughCharacter.isDigit(int).allMatch()stops at the first character that is not a digit. - Part 4:
mapToObj(c -> (char) c)turns theIntStreaminto aStream<Character>, which can be groupedClick to read: Tutorial on grouping with collectors. TheLinkedHashMap::newfactory 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, becausesappears three times. This is a popular interview question. - Part 6: an
IntStreamcannot useCollectors.joining(), but its three-argumentcollect()can build aStringBuilder:appendCodePoint(int)adds each value as a character, andappendmerges two builders when the stream runs in parallel. - Part 7: the alternative: turn each value into a one-character
StringwithmapToObj(), then use any string collector, herejoining("-").
ints to Characters, then a collector.
Where chars() and codePoints() differ
Achar 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.
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));
}
}
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()andchars()count five, because the emoji takes twochars.codePoints()counts four. - Part 2: in hexadecimal,
chars()returns the surrogates D83D and DE00, andcodePoints()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::isLetterresolves toisLetter(int)in both streams. A surrogate is not a letter, sochars()finds only B and C, whilecodePoints()also counts the double-struck A. - Part 5: collecting with
appendCodePoint()writes each code point back as one or twochars, so the emoji survives the round trip: three code points, fourchars. - Part 6: splitting the greeting into one
Stringper character. Casting eachchars()value tochargives five one-charstrings, 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 twochars it needs, socodePoints()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
EvencodePoints() 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)));
}
}
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.
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
codePoints()- use for text that may contain any character - user input, names, chat messages etc. Reason being - counting, filtering or classifying withchars()would split emoji and other supplementary characters in two.chars()- Use when text is known to be ASCII or within the BMP - for codes, identifiers, digits, most interview puzzles etcchars()is fine, as those types of values can be cast tocharsafely.- Getting characters back:
mapToObj(c -> (char) c)forchars(); forcodePoints()usemapToObj(c -> new String(Character.toChars(c))), because a code point may not fit into onechar(part 6 of the second program). - 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). - 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 thatchars() 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.Java 8 Tutorials
Java 8 Primitive Streams: mapToInt, mapToObj and boxedClick to read tutorial: Java 8 Primitive Streams: mapToInt, mapToObj and boxed Java 8 IntSummaryStatistics and summaryStatistics()Click to read tutorial: Java 8 IntSummaryStatistics and summaryStatistics() Java 8 Stream forEach vs forEachOrdered with ExamplesClick to read tutorial: Java 8 Stream forEach vs forEachOrdered with Examples Java 8 Streams API Tutorial with ExamplesClick to read tutorial: Java 8 Streams API Tutorial with Examples Java 8 IntStream range() and rangeClosed() with ExamplesClick to read tutorial: Java 8 IntStream range() and rangeClosed() with Examples Java 8 Primitive Functional Interfaces TutorialClick to read tutorial: Java 8 Primitive Functional Interfaces Tutorial Java 8 Parallel Streams Tutorial with ExamplesClick to read tutorial: Java 8 Parallel Streams Tutorial with Examples
Java 8 Primitive Streams: mapToInt, mapToObj and boxedClick to read tutorial: Java 8 Primitive Streams: mapToInt, mapToObj and boxed Java 8 IntSummaryStatistics and summaryStatistics()Click to read tutorial: Java 8 IntSummaryStatistics and summaryStatistics() Java 8 Stream forEach vs forEachOrdered with ExamplesClick to read tutorial: Java 8 Stream forEach vs forEachOrdered with Examples Java 8 Streams API Tutorial with ExamplesClick to read tutorial: Java 8 Streams API Tutorial with Examples Java 8 IntStream range() and rangeClosed() with ExamplesClick to read tutorial: Java 8 IntStream range() and rangeClosed() with Examples Java 8 Primitive Functional Interfaces TutorialClick to read tutorial: Java 8 Primitive Functional Interfaces Tutorial Java 8 Parallel Streams Tutorial with ExamplesClick to read tutorial: Java 8 Parallel Streams Tutorial with Examples