What are Spliterator characteristics, and how does the Streams API use flags like ORDERED, SIZED, DISTINCT, SORTED, and IMMUTABLE?

## What "characteristics" are `int characteristics()` returns a **bitmask** — an integer whose individual bits each stand for a property of the Spliterator's source. You test a flag with `spliterator.hasCharacteristics(Spliterator.SIZED)`. These flags are a **contract the Spliterator makes to the framework**: the stream pipeline trusts them to skip work, so they must be **truthful**. ## The flags, defined - **`ORDERED`** — the elements have a **meaningful encounter order** (a defined first, second, third…). Lists, arrays, and `LinkedHashSet` are ORDERED; a `HashSet`'s Spliterator is **not** (its iteration order is arbitrary). Order matters for operations like `findFirst`, `limit`, `skip`, and `forEachOrdered`. - **`SIZED`** — `estimateSize()` is an **exact** count of remaining elements, not a guess. Collections of known size report this. - **`SUBSIZED`** — additionally, **every** Spliterator produced by `trySplit` is also exactly `SIZED`. (SUBSIZED implies SIZED for the children.) This lets the parallel framework know precise sizes all the way down the split tree. - **`DISTINCT`** — no two elements are equal (per `equals`); i.e. there are no duplicates. `Set` sources report this. - **`SORTED`** — the elements are encountered in a defined **sort order**. SORTED **implies ORDERED**. A source reporting SORTED may expose its `Comparator` via `getComparator()` (returning `null` means natural ordering). `TreeSet` reports this. - **`NONNULL`** — the source is guaranteed to contain **no null** elements (e.g. `ConcurrentHashMap` keys). - **`IMMUTABLE`** — the **structure cannot change** during traversal (no elements added/removed); the source needs no concurrent-modification detection. - **`CONCURRENT`** — the source **may be safely modified concurrently** by other threads during traversal (e.g. `ConcurrentHashMap`). Note: a source is either IMMUTABLE, CONCURRENT, or neither (the "neither" case is the typical fail-fast collection that throws `ConcurrentModificationException`). ## How the Streams API exploits each The whole point of characteristics is **optimization** — the pipeline reads them to avoid redundant work: - **`DISTINCT` → `distinct()` is a no-op.** If the source already guarantees uniqueness, the deduplication step is skipped entirely. - **`SORTED` → `sorted()` may be skipped.** If the stream is already sorted in the order requested (matching comparator), the sort is elided. - **`SIZED` → exact preallocation.** `toArray()`, `collect(toList())`, and internal buffers can allocate the right size up front instead of growing dynamically. `count()` can return the size directly without traversing, when no size-changing ops intervene. - **`SUBSIZED` → better parallel load balancing**, because the framework knows each split chunk's exact size. - **`ORDERED` → ordering obligations.** Stateful operations (`limit`, `skip`, `findFirst`, `forEachOrdered`) must honor encounter order. In a **parallel** pipeline, preserving order costs coordination; if you don't need it, calling `unordered()` (or starting from an unordered source like a HashSet) **drops** the ORDERED flag and can make the parallel pipeline faster. - **`IMMUTABLE`/`CONCURRENT` → no fail-fast bookkeeping** needed during traversal. ## Why truthfulness is mandatory Because the framework *acts* on these flags, **lying corrupts results**. If you report `DISTINCT` but actually have duplicates, `distinct()` is skipped and duplicates leak through. If you report `SIZED` with the wrong count, buffers misallocate. A custom Spliterator must report **only** flags it genuinely satisfies. ## Where the flags come from in practice You rarely set these by hand. Standard collections report sensible defaults: | Source | Typical characteristics | |---|---| | `ArrayList` | ORDERED, SIZED, SUBSIZED | | `HashSet` | DISTINCT, SIZED (not ORDERED) | | `LinkedHashSet` | DISTINCT, ORDERED, SIZED | | `TreeSet` | DISTINCT, SORTED, ORDERED, SIZED | | `ConcurrentHashMap` keys | DISTINCT, CONCURRENT, NONNULL | When you build a custom Spliterator (often via `Spliterators.spliterator(...)` helpers), you pass the bitmask, e.g. `ORDERED | SIZED | SUBSIZED | NONNULL`. ## Quick example of reading flags ```java Spliterator<String> s = new TreeSet<>(List.of("a", "b")).spliterator(); s.hasCharacteristics(Spliterator.SORTED); // true s.hasCharacteristics(Spliterator.DISTINCT); // true s.hasCharacteristics(Spliterator.SIZED); // true // SORTED implies ORDERED: s.hasCharacteristics(Spliterator.ORDERED); // true ```