# Splitting and Partitioning

> StringZilla for Java

Every factory takes an on-heap `byte[]` or any `MemorySegment` (e.g. an off-heap Spark `UTF8String`, a direct `ByteBuffer`, or an mmap'd file).
The word, grapheme, sentence, line-break, and separator-token iterators are always zero-copy and batch 64 boundaries per native call.
The substring and byte-set splits (`split`/`rsplit`/`splitAny`) and the match iterators scan native segments in place; for on-heap inputs they copy the text off-heap once per `cursor()`, because pointer-returning finds need a stable address that the JVM does not expose for heap memory.
The `Iterable`/`Stream` adapters are the ergonomic path; a `cursor()` (a `boolean next()` plus `startOffset()`/`length()`) is the zero-allocation escape hatch.

```java
StringZilla.runes(text).forEach(this::use);                       // IntStream of codepoints
for (MemorySegment word : StringZilla.words(text)) use(word);     // also graphemes/sentences/lineBreaks

for (MemorySegment field : StringZilla.split(line, comma)) use(field);          // cf. String.split, zero-copy
for (MemorySegment part : StringZilla.rsplit(path, slash).withMaxSplit(1)) use(part); // from the end
for (MemorySegment token : StringZilla.splitAny(text, separators)) use(token);  // any byte in a Byteset
for (MemorySegment line : StringZilla.splitWhitespaces(text).skipEmpty()) use(line); // collapse runs

long[] offsets = StringZilla.matches(haystack, needle).toArray(); // every offset; .overlapping() for overlaps
StringZilla.uncasedMatches(haystack, needle).stream().forEach(this::use); // caseless; Match.offset/matchedLength

StringZilla.Partition parts = StringZilla.partition(text, equals); // (before, separator, after)
```

`withMaxSplit(n)` stops after `n` separators: `0` yields the whole text, and a negative `n`, the default, splits at every separator.
An empty separator yields the whole text, a trailing separator leaves a final empty segment unless `.skipEmpty()`, and an empty needle matches at every offset up to and including the end, or at every codepoint boundary when uncased.

The zero-allocation cursor, e.g. to sort a file's lines without materializing them:

```java
StringZilla.TokenSplitter splitter = StringZilla.splitNewlines(buffer).cursor();
while (splitter.next()) record(splitter.startOffset(), splitter.length());
```