class StringZillaPure FFM, JDK 22+.
API
ClassStringZillaCore StringZilla operations: search, compare, hash.64
indexOfFirst byte offset of needle in the off-heap haystack, or -1.
long indexOf(MemorySegment haystack, MemorySegment needle);long indexOf(byte[] haystack, byte[] needle);First byte offset of needle in haystack, or -1.
long indexOf(byte[] haystack, int off, int len, byte[] needle);Like indexOf(byte[], byte[]), but searches len bytes of haystack from off, and the returned offset is relative to off.
Like String#indexOf(String), but SIMD-accelerated over UTF-8 bytes. Keywords: find, search, substring.
lastIndexOfLast byte offset of needle in the off-heap haystack, or -1.
long lastIndexOf(MemorySegment haystack, MemorySegment needle);long lastIndexOf(byte[] haystack, byte[] needle);Last byte offset of needle in haystack, or -1.
The byte[] form of lastIndexOf(MemorySegment, MemorySegment).
indexOfAnyFirst offset of any byte in set, or -1.
long indexOfAny(byte[] haystack, Byteset set);lastIndexOfAnyLast offset of any byte in set, or -1.
long lastIndexOfAny(byte[] haystack, Byteset set);The reverse of indexOfAny.
equalByte-wise equality.
boolean equal(byte[] a, byte[] b);Like java.util.Arrays#equals(byte[], byte[]), SIMD-accelerated.
compareLexicographic byte comparison: -1, 0, or 1.
int compare(byte[] a, byte[] b);Like java.util.Arrays#compare(byte[], byte[]).
hashFast 64-bit AES-based hash (SMHasher-quality), stable across runs and identical across all StringZilla bindings — unlike String#hashCode().
long hash(byte[] data);long hash(byte[] data, long seed);Like hash(byte[]), under the given seed.
long hash(MemorySegment data, long seed);Like hash(byte[], long), over a MemorySegment.
For cryptographic hashing use Sha256.
byteSumSums the bytes of data, computed by the native sz_bytesum_best.
long byteSum(byte[] data);countRunesCounts Unicode scalar values (codepoints).
long countRunes(byte[] text);long countRunes(MemorySegment text);Like countRunes(byte[]), over a MemorySegment.
Like String.codePointCount / Character#codePointCount, SIMD-accelerated over UTF-8 bytes. For example, "你好世界" counts 4 and "Hello🌍" counts 6 — the astral emoji is a single scalar.
seekRuneByte offset of the index-th codepoint (0-based), or -1 if fewer exist.
long seekRune(byte[] text, long index);decodeDecodes codepoints into destination (one Int32 scalar each; ill-formed or truncated → U+FFFD) and returns the count written, stopping early only when destination fills.
int decode(byte[] text, int[] destination);int decode(MemorySegment text, int[] destination);Like decode(byte[], int[]), over a MemorySegment.
Like String.codePoints(), SIMD-accelerated.
decodeAllAllocating convenience: returns all codepoints as a fresh Int32 array.
int[] decodeAll(byte[] text);int[] decodeAll(MemorySegment text);Like decodeAll(byte[]), over a MemorySegment.
segmentWrites the byte lengths of the next segments of text, from textOffset for textLength bytes, into the caller's lengths and returns the count written.
int segment(
byte[] text,
int textOffset,
int textLength,
SegmentKind kind,
long[] lengths);int segment(
MemorySegment text,
long textOffset,
long textLength,
SegmentKind kind,
long[] lengths);Like segment(byte[], int, int, SegmentKind, long[]), over a MemorySegment with long bounds.
Allocation-free. Segments tile the text, each starting where the previous one ended, so resume at the sum of the lengths; only an empty text yields 0. Like java.text.BreakIterator / ICU4J, but deterministic, SIMD-accelerated, over UTF-8 bytes (no locale, no transcode). By GRAPHEMES, the flag 🇺🇸 is one cluster spanning two codepoints; by WORDS, "Hello, 世界" splits the Latin run from the CJK run.
caseFoldFolds into the caller's destination (must hold ≥ text.length*3 bytes) and returns the bytes written.
int caseFold(byte[] text, byte[] destination);byte[] caseFold(byte[] text);Full Unicode case folding (UAX #21, one-to-many, e.g.
Allocation-free.
uncasedIndexOfCase-insensitive (full-fold) search.
Match uncasedIndexOf(byte[] haystack, byte[] needle);Fills a gap: no JDK caseless UTF-8 substring search. For repeated searches with the same needle, prefer UncasedNeedle.
uncasedCompareCase-insensitive (full-fold) lexicographic comparison: -1, 0, or 1.
int uncasedCompare(byte[] a, byte[] b);Fills a gap: no JDK Unicode case-folded ordinal comparison.
hashMultiseedHashes data under each seed, writing results into hashes (must hold ≥ seeds.length).
void hashMultiseed(byte[] data, long[] seeds, long[] hashes);long[] hashMultiseed(byte[] data, long[] seeds);Allocating convenience: returns one hash per seed.
fillRandomFills buffer with deterministic pseudo-random bytes derived from nonce.
void fillRandom(byte[] buffer, long nonce);lookupByte-wise table transform: destination[i] = lut[source[i]].
void lookup(byte[] destination, byte[] source, byte[] lut);lut must be 256 bytes.
normalizeNormalizes into the caller's destination (must hold ≥ text.length*18 bytes) and returns the bytes written.
int normalize(byte[] text, NormalForm form, byte[] destination);byte[] normalize(byte[] text, NormalForm form);Normalizes text to the given form.
Allocation-free.
isNormalizedTrue if text is already in the given form.
boolean isNormalized(byte[] text, NormalForm form);Like java.text.Normalizer#isNormalized.
argSortReturns the permutation that sorts items lexicographically by bytes (stable).
int argSort(
java.util.List<byte[]> items,
long[] order,
boolean reverse,
long top,
boolean uncased);long[] argSort(
java.util.List<byte[]> items,
boolean reverse,
long top,
boolean uncased);Allocating convenience: returns a fresh permutation array.
long[] argSort(java.util.List<byte[]> items);Returns the ascending, case-sensitive permutation of all items, as argSort with no limit.
int argSort(
byte[] text,
long[] starts,
long[] lengths,
long[] order,
boolean reverse,
long top,
boolean uncased);Sorts the segments of a single buffer — given per-segment starts and lengths (as produced by the split iterators) — writing their sorting permutation into order (must hold ≥ starts.length entries) and returning the count.
top > 0 partial-sorts the smallest N. Like Collections.sort with an ordinal comparator, but returns indices over UTF-8 bytes. Writes the sorting permutation of items into order (must hold ≥ items.size() entries) and returns the count of sorted indices (top if > 0, else items.size()). Like Collections.sort with an ordinal comparator, but returns indices over UTF-8 bytes.
intersectInner-join two de-duplicated sequences.
int intersect(
java.util.List<byte[]> a,
java.util.List<byte[]> b,
long[] firstPositions,
long[] secondPositions,
long seed);int intersect(
java.util.List<byte[]> a,
java.util.List<byte[]> b,
long[] firstPositions,
long[] secondPositions);Like intersect, seed 0.
Returns {firstPositions, secondPositions} — the matching index pairs into a and b. Inner-joins two de-duplicated sequences, writing matching index pairs into firstPositions and secondPositions (each must hold ≥ min(a.size(), b.size()) entries) and returns the match count. Allocation-free for the result.
runesDecodes the Unicode scalar values (codepoints) as an IntStream.
IntStream runes(byte[] text);IntStream runes(MemorySegment text);Like runes(byte[]), over a MemorySegment.
Like String.codePoints(). Eager (decodes the whole input up front); for incremental decoding use decode(byte[], int[]).
wordsLazily yields the word segments (UAX #29) as zero-copy MemorySegment views, or a zero-allocation Segmenter cursor via Segments#cursor().
Segments words(byte[] text);Segments words(MemorySegment text);Like words(byte[]), over a MemorySegment.
Accepts an on-heap byte[] or any MemorySegment (e.g. a Spark UTF8String or an mmap'd file).
graphemesLazily yields the grapheme cluster segments, like words(byte[]).
Segments graphemes(byte[] text);Segments graphemes(MemorySegment text);Like graphemes(byte[]), over a MemorySegment.
sentencesLazily yields the sentence segments, like words(byte[]).
Segments sentences(byte[] text);Segments sentences(MemorySegment text);Like sentences(byte[]), over a MemorySegment.
lineBreaksLazily yields the segments between line-break opportunities, like words(byte[]).
Segments lineBreaks(byte[] text);Segments lineBreaks(MemorySegment text);Like lineBreaks(byte[]), over a MemorySegment.
splitLazily splits text on each occurrence of separator, yielding the segments between separators as zero-copy views.
Splits split(byte[] text, byte[] separator);Splits split(MemorySegment text, MemorySegment separator);Like split(byte[], byte[]), over MemorySegment inputs.
Empty segments are kept by default (like String.split with a negative limit); chain .skipEmpty(), .keepSeparator(), or .withMaxSplit(n). Off-heap MemorySegment inputs are scanned in place; on-heap inputs are copied off-heap once per cursor() (pointer-returning finds need a stable address).
rsplitAs split but scanning from the end; yields the last segment first.
Splits rsplit(byte[] text, byte[] separator);Splits rsplit(MemorySegment text, MemorySegment separator);Like rsplit(byte[], byte[]), over MemorySegment inputs.
splitAnyLazily splits on any byte in separators (like splitting on a character set).
Splits splitAny(byte[] text, Byteset separators);Splits splitAny(MemorySegment text, Byteset separators);Like splitAny(byte[], Byteset), over a MemorySegment.
rsplitAnyAs splitAny but scanning from the end.
Splits rsplitAny(byte[] text, Byteset separators);Splits rsplitAny(MemorySegment text, Byteset separators);Like rsplitAny(byte[], Byteset), over a MemorySegment.
splitNewlinesLazily splits on Unicode newline runs, yielding the lines between them.
TokenSplits splitNewlines(byte[] text);TokenSplits splitNewlines(MemorySegment text);Like splitNewlines(byte[]), over a MemorySegment.
Chain .withSeparators() for a lossless interleave or .skipEmpty() to drop blanks.
splitWhitespacesLazily splits on Unicode whitespace, as splitNewlines(byte[]) does on newlines.
TokenSplits splitWhitespaces(byte[] text);TokenSplits splitWhitespaces(MemorySegment text);Like splitWhitespaces(byte[]), over a MemorySegment.
splitDelimitersLazily splits on Unicode delimiters, as splitNewlines(byte[]) does on newlines.
TokenSplits splitDelimiters(byte[] text);TokenSplits splitDelimiters(MemorySegment text);Like splitDelimiters(byte[]), over a MemorySegment.
matchesLazily enumerates the byte offsets of every match of needle in haystack; chain .overlapping() for overlapping matches.
Matches matches(byte[] haystack, byte[] needle);Matches matches(MemorySegment haystack, MemorySegment needle);Like matches(byte[], byte[]), over MemorySegment inputs.
Counting the result is the occurrence count.
uncasedMatchesLazily enumerates case-insensitive (full-fold) matches; chain .overlapping().
UncasedMatches uncasedMatches(byte[] haystack, byte[] needle);UncasedMatches uncasedMatches(
MemorySegment haystack,
MemorySegment needle);Like uncasedMatches(byte[], byte[]), over MemorySegment inputs.
Each Match carries the offset and matched length (folding may make the latter differ). An empty needle matches at every codepoint boundary, the end included.
partitionSplits at the first occurrence of separator into (before, separator, after) views; if absent, returns (text, empty, empty).
Partition partition(byte[] text, byte[] separator);Partition partition(MemorySegment text, MemorySegment separator);Like partition(byte[], byte[]), over MemorySegment inputs.
rpartitionAs partition but at the last occurrence; if absent, returns (empty, empty, text).
Partition rpartition(byte[] text, byte[] separator);Partition rpartition(MemorySegment text, MemorySegment separator);Like rpartition(byte[], byte[]), over MemorySegment inputs.
capabilitiesNameNames the bits of capabilities, comma-separated, like "serial,haswell,skylake".
String capabilitiesName(long capabilities);versionThe native library version, formatted as major.minor.patch.
String version();MatchResult of a case-insensitive search: byte offset (-1 if not found) and the matched byte length (may differ from the needle due to folding).
record Match(long offset, long matchedLength);DeviceOne device StringZilla can run on: the host CPU, or a GPU by its runtime's own ordinal, the one cudaSetDevice or hipSetDevice takes, or the position in Metal's device list.
record Device(DeviceKind kind, long ordinal);Every call of this class dispatches over the CPU's capabilitiesEnabled(); GPUs only report their masks.
Prefer capabilitiesEnabled() unless you specifically mean one of the raw axes: capabilitiesDetected() describes the device and says nothing about whether a kernel was compiled into this binary, so selecting on it alone claims support for code that may not exist.
PartitionA single split point: the spans before, of, and after a separator.
record Partition(
MemorySegment before,
MemorySegment separator,
MemorySegment after);See partition.
SegmentKindA tiling segmentation: every byte lands in exactly one segment.
enum SegmentKindFields
GRAPHEMES | | Grapheme clusters. |
|---|---|---|
WORDS | | Word segments. |
SENTENCES | | Sentence segments. |
LINE_BREAKS | | Segments between line-break opportunities. |
TokenKindThe separator tokens that TokenSplits splits on.
enum TokenKindFields
NEWLINES | | Unicode newlines. |
|---|---|---|
WHITESPACES | | Unicode whitespace. |
DELIMITERS | | Unicode delimiters. |
NormalFormUnicode normalization forms, NFKC_CASEFOLD being NFKC with full case folding and without default-ignorable codepoints, the Unicode toNFKC_Casefold that caseless keys match on.
enum NormalFormFields
NFD | | Canonical decomposition. |
|---|---|---|
NFC | | Canonical decomposition followed by canonical composition. |
NFKD | | Compatibility decomposition. |
NFKC | | Compatibility decomposition followed by canonical composition. |
NFKC_CASEFOLD | | NFKC with full case folding, as described on NormalForm. |
DeviceKindWhich runtime a device belongs to, as the sz_<kind>_* C functions name it.
enum DeviceKindFields
CPU | | The host CPU. |
|---|---|---|
CUDA | | NVIDIA GPUs, through CUDA. |
ROCM | | AMD GPUs, through ROCm. |
METAL | | Apple GPUs, through Metal. |
StatusExceptionA native call returned a non-success sz_status_t, kept in status().
class StatusExceptionBytesetA 256-bit set of byte values.
class BytesetHasherIncremental (streaming) hash.
UncasedNeedleA case-folding search needle, prepared once and reusable from any thread.
Sha256Incremental SHA-256.
SplitPartsWhich spans a separator-token split yields: the gaps, the separator runs, or both (lossless).
enum SplitPartsFields
BETWEEN | | The gaps between separator runs. |
|---|---|---|
SEPARATORS | | The separator runs only. |
BOTH | | The gaps and the separator runs, interleaved. |
SegmenterZero-allocation forward cursor over tiling UTF-8 segments (words, graphemes, …).
class SegmenterReuses one 64-entry batch buffer; call next() then read startOffset()/length().
SegmentsIterable / streamable view over tiling segments, yielding zero-copy MemorySegment slices.
SplitterZero-allocation cursor over substring / byte-set splits, with forward and reverse scanning and the keepSeparator / skipEmpty / maxSplit policies.
class SplitterSplitsIterable / streamable view over substring or byte-set splits.
class SplitsFluent policies return a new view; cursor() is the zero-allocation path.
TokenSplitterZero-allocation cursor over separator-token splits (newlines, whitespace, delimiters), batched 64 separators per native call, applying the SplitParts policy.
class TokenSplitterTokenSplitsIterable / streamable view over separator-token splits, yielding zero-copy slices.
class TokenSplitsMatcherZero-allocation cursor over substring matches, yielding each match's byte offset.
class MatcherMatchesStreamable view over substring matches; overlapping() reports overlapping matches and cursor() is the zero-allocation path.
UncasedMatcherZero-allocation cursor over case-insensitive matches of a needle prepared once.
class UncasedMatcherUncasedMatchesStreamable view over case-insensitive matches; overlapping() and cursor() mirror Matches.
class UncasedMatches