What is the difference between String.chars() and String.codePoints(), and why does it matter for characters like emoji?

## Background: how Java stores text Java strings are sequences of **`char`** values, and a `char` is a **16-bit UTF-16 code unit**. Unicode assigns each character a **code point** — an integer identity, e.g. 'A' is U+0041, the grinning-face emoji is U+1F600. Code points up to U+FFFF (the 'Basic Multilingual Plane', BMP) fit in one 16-bit char. Code points above that (**supplementary characters**, U+10000–U+10FFFF, including most emoji and many rare scripts) do **not** fit in 16 bits, so UTF-16 encodes them as a **surrogate pair**: two special char values, a 'high surrogate' (U+D800–DBFF) followed by a 'low surrogate' (U+DC00–DFFF). Together they represent one code point. This is why `"😀".length()` is **2**, not 1 — `length()` counts char/code units, not characters. ## chars() `chars()` returns an `IntStream` (a primitive stream of `int`) with **one element per char (UTF-16 code unit)**. Its count equals `length()`. For a supplementary character you get **two** ints — the surrogate values — each meaningless on its own. It returns `int` rather than `char` simply because `IntStream` is the primitive stream type Java offers; the values are still 16-bit char values widened to int. Example: `"a😀b".chars().count()` → 4 (a, high surrogate, low surrogate, b). ## codePoints() `codePoints()` returns an `IntStream` with **one element per Unicode code point**: it scans the string, and whenever it sees a valid surrogate pair it **combines** the two chars into the single code point integer. So each emoji is exactly one int, and that int can be larger than 0xFFFF — which is precisely why the stream is of `int`, not `char` (a char cannot hold a supplementary code point). Example: `"a😀b".codePoints().count()` → 3 (a, 😀, b). This is the correct way to count 'characters' for most purposes. ## Why it matters Using `chars()` or `length()` to count or slice user-visible text breaks on emoji and many non-Latin scripts: you over-count, and slicing can cut a surrogate pair in half, producing an invalid lone surrogate that renders as garbage. `codePoints()` (and code-point-aware methods like `codePointCount`, `offsetByCodePoints`) avoid that class of bug. ## Reconstructing strings from an int stream Since elements are ints, you cannot just `Stream<Character>`-collect them. To rebuild text from code points use, e.g., `codePoints().collect(StringBuilder::new, StringBuilder::appendCodePoint, StringBuilder::append).toString()`, or `Character.toChars(cp)` to get the char(s) for one code point. `appendCodePoint` correctly emits one or two chars as needed. ## The remaining limit: grapheme clusters Even a code point is not always a single **user-perceived character** (a 'grapheme cluster'). A base letter plus a combining accent, an emoji with a skin-tone modifier, or a flag (two regional-indicator code points) are multiple code points that display as one symbol. Neither `chars()` nor `codePoints()` groups these. For true visual-character segmentation use `java.text.BreakIterator.getCharacterInstance()`, which iterates grapheme boundaries. ## Practical guidance - Counting/processing characters → `codePoints()`. - Working at the encoding/buffer level → `chars()`. - Visual character count, cursor movement, truncation that must not split emoji → `BreakIterator`. - Both streams are lazy `IntStream`s, so you can `filter`, `map`, `mapToObj`, etc.