argsort writes the sorted permutation of a slice into a caller-provided order slice, while argsort_by sorts by a byte-slice key extracted from each element.
Both write the sorting permutation of data into a caller-supplied order buffer of length at least data.len(), or return Status::UnexpectedDimensions. argsort_by sorts by a byte-slice key of each element, ideal for sorting structs by a field.
The binding indexes data itself, so the key only projects an element onto its bytes; it runs inside the C call, where a panic cannot unwind and aborts the process.
ArgsortOptions is a builder; the default is a full, ascending, byte-lexicographic, stable sort:
reversed() / field reverse: bool — descending order, still stable on ties.
uncased() / field uncased: bool — order under Unicode case folding instead of raw bytes.
top(k) / field top: Option<usize> — only fully order the leading k elements, a top-K or partial sort.
use stringzilla::{self as sz, ArgsortOptions};let fruits = ["banana", "apple", "cherry"];let mut order = [0; 3];sz::argsort(&fruits, &mut order, Default::default()).unwrap();assert_eq!(&order, &[1, 0, 2]); // apple, banana, cherry// Descending + uncasedlet labels = ["beta", "Alpha", "BETA"];let mut order = [0; 3];sz::argsort(&labels, &mut order, ArgsortOptions::default().reversed().uncased()).unwrap();// Sort structs by a keystruct Person { name: &'static str }let people = [Person { name: "Charlie" }, Person { name: "Alice" }, Person { name: "Bob" }];let mut order = [0; 3];sz::argsort_by(&people, |person| person.name.as_bytes(), &mut order, Default::default()).unwrap();assert_eq!(&order, &[1, 2, 0]); // Alice, Bob, Charlie
intersection matches two collections directly, while intersection_by matches by a byte-slice key extracted from each element, both writing the matched positions of each side.
Both compute the intersection of two collections, which may differ in length and, for intersection_by, in element type.
They write the matching positions into output buffers each sized at least min(data1.len(), data2.len()), or return Status::UnexpectedDimensions, and return the intersection size:
use stringzilla as sz;let set1 = ["banana", "apple", "cherry"];let set2 = ["cherry", "orange", "pineapple", "banana"];let (mut p1, mut p2) = ([0; 3], [0; 3]);let n = sz::intersection(&set1, &set2, 0, &mut p1, &mut p2).unwrap();assert_eq!(n, 2); // "banana" and "cherry"
fill_random overwrites a buffer with deterministic pseudo-random bytes for a given nonce — the same nonce always yields the same output — useful for generating test data:
use stringzilla as sz;let mut a = vec![0u8; 10];let mut b = vec![1u8; 10];sz::fill_random(&mut a, 42);sz::fill_random(&mut b, 42);assert_eq!(a, b); // identical nonce → identical bytes
A column of strings comes in two types.
A StringsView borrows one in any layout C reads: an Apache Arrow String or LargeString tape of bytes and offsets, or a slice of anything AsRef<[u8]>, read in place through an accessor.
A Strings<A> owns one tape, its payload and its offsets both from the allocator A, Global unless named, and frees them on drop.
Every conversion writes a new Strings, or a joined Vec<u8, A>, from the allocator it is given, on the device of the stream it is given, joining that stream before returning:
from_u32_tape and from_u64_tape refuse offsets that fall or run past the data with Status::UnexpectedDimensions, and accept a sliced Arrow array whose first offset is past zero. EscapeKind names the format: Json, JsonAscii, Csv, Html, Url, Hex or Console, the last one keeping logs safe from control bytes and bidirectional overrides. unescape_in stops at the first malformed string, like a CSV field with an unbalanced quote, and reports its position as StringsError::Malformed. find writes each string’s first match of one needle, usize::MAX where there is none, and hashes each string’s hash_with_seed, both into a slice of exactly len() entries. utf8_count validates every string as UTF-8, reporting the first ill-formed one as StringsError::Malformed, and writes each one’s rune count into such a slice unless given None. split_in cuts a text at the bytes of a Byteset, every delimiter ending a part with SplitKind::Each, like slice::split, or every run of them with SplitKind::Runs, like str::split_ascii_whitespace. split_lines_in cuts UTF-8 at the line breaks of Python’s str.splitlines(), CR LF counting as one, leaving no empty line after the last. join_columns_in writes row r as frames[0], columns[0][r], frames[1] and so on, with between between rows, serializing CSV lines or JSON records without a string per cell, and join_in joins one column like slice::join. to_rows writes NUL-padded fixed-width rows, truncating longer strings, and returns the longest length to retry with wider rows:
The default is a full, ascending, byte-lexicographic, stable sort (equal elements keep their
input order). Tweak the public fields directly or chain the builder methods:
use stringzilla as sz;let descending = sz::ArgsortOptions::default().reversed();let top_10_folded = sz::ArgsortOptions { uncased: true, top: Some(10), ..Default::default() };
Fields
reverse
bool
Sort in descending order; equal elements still keep their input order, as the
sort is stable.
uncased
bool
Order under Unicode case-folding instead of raw bytes.
top
Option<usize>
Only fully order the leading Some(k) elements (top-K / partial sort); None sorts
everything. The remaining entries of order stay a valid - but arbitrary - permutation of
the leftover indices.
RFC 8259 string bodies: \", \\, short forms like \n, and \u00XX for the other bytes
below 0x20, every other byte kept as it is.
Hex
1
Two lowercase hexadecimal digits per byte, decoding either case.
Html
2
HTML and XML text and attribute values: &, <, >, " and '.
Url
3
RFC 3986 percent-encoding of every byte outside A-Z a-z 0-9 - . _ ~.
Console
4
Terminal-safe logs: short forms like \n, \xHH for the other control bytes and ill-formed
UTF-8, and \uXXXX for C1 controls and the bidirectional overrides that reorder what a
reader sees.
Csv
5
RFC 4180 fields, quoted only when holding a comma, a quote, CR or LF, with inner quotes
doubled.
JsonAscii
6
RFC 8259 string bodies in ASCII alone: every other codepoint becomes \uXXXX, a surrogate
pair beyond the Basic Multilingual Plane, and every ill-formed byte the escaped U+FFFD.
The sequences may differ in length and element type, and each output buffer must hold at least
as many positions as the shorter sequence has elements, or Status::UnexpectedDimensions is
returned. The keys run inside the C call, where a panic cannot unwind and aborts the process.
Examples
use stringzilla as sz;struct Person { name: &'static str, age: u32 }let people = [ Person { name: "Charlie", age: 20 }, Person { name: "Alice", age: 25 }, Person { name: "Bob", age: 30 },];let invited = ["Alice", "Bob", "Dave", "Eve"];let mut positions1 = [0; 3]; // min(people.len(), invited.len())let mut positions2 = [0; 3];let n = sz::intersection_by( &people, |person| person.name.as_bytes(), &invited, |name| name.as_bytes(), 0, &mut positions1, &mut positions2,).expect("intersection_by failed");assert!(n == 2); // "Alice" and "Bob" are common.
argsortComputes the permutation that sorts data by its byte-slice representations.
The caller supplies an output buffer order of length at least data.len(), or gets
Status::UnexpectedDimensions; on success the sorted permutation indices are written into its
first data.len() slots. See ArgsortOptions for descending, uncased, and top-K variants.
Examples
use stringzilla as sz;let fruits = ["banana", "apple", "cherry"];let mut order = [0; 3];sz::argsort(&fruits, &mut order, Default::default()).expect("sort failed");assert_eq!(&order, &[1, 0, 2]); // "apple", "banana", "cherry"// Descending, uncased:let labels = ["beta", "Alpha", "BETA"];let mut order = [0; 3];sz::argsort(&labels, &mut order, sz::ArgsortOptions::default().reversed().uncased()).unwrap();assert_eq!(labels[order[0]], "beta"); // "beta"/"BETA" (fold-equal) before "Alpha", stable on ties
argsort_byComputes the permutation that sorts data by a byte-slice key of each element.
This function mutates text in place, replacing each byte with a random one
from alphabet. It is designed for situations where you need to generate random strings or
data sequences based on a specific set of characters, such as generating random DNA
sequences or testing inputs.
Arguments
buffer: A mutable reference to the data to randomize. This data will be mutated in place.
nonce: A 64-bit "number used once", or nonce, value to seed the random number generator.
Examples
use stringzilla as sz;let mut buffer = vec![0; 10];sz::fill_random(&mut buffer, 42);
After than, buffer is filled with random byte values from 0 to 255.