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.
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:
StringZilla.TokenSplitter splitter = StringZilla.splitNewlines(buffer).cursor();
while (splitter.next()) record(splitter.startOffset(), splitter.length());