Expand description
§ZCString
ZCString is a context-aware string handle wrapping arcstr::Substr, designed
for efficient, zero-copy string manipulation and deserialization.
It uses thread-local storage to track an active “source” string buffer. When substrings are parsed or derived from that buffer, they can be created as zero-allocation sub-slices referencing the original buffer rather than duplicating string contents into new heap allocations.
§Core Features
- Context-Aware Slicing: Maintains an active
SOURCEstring in thread-local storage. When creating aZCStringfrom a&str(viaZCString::fromor deserialization), it checks if the string slice resides within the active source buffer. If so, it returns a zero-copy slice; otherwise, it falls back to a standard allocation. - RAII Scope Guards: Provides
SourceGuardandZCString::with_sourceto safely scope the lifetime of the active source, supporting arbitrary nesting with automatic restoration of outer sources upon scope exit. - Serde Integration: Provides
serde_json_from_zcstringfor zero-copy deserialization of JSON strings. Unescaped strings become zero-copy slices pointing directly into the JSON payload, while escaped strings (which require unescaping) fall back to allocated strings. - Raw and Lazy JSON Values:
ZCRawValue: Preserves unparsed JSON fragments as zero-copy raw string slices.ZCRawValueAnd: Holds both the unparsed raw JSON slice and the eagerly parsed Rust valueT.ZCLazyValue: Defers parsing of a raw JSON slice intoTuntil first access, caching the result in a thread-safestd::sync::OnceLock.
- Stream and File Reading: Utility functions
ZCString::read_range,ZCString::read_exact, andZCString::from_fileallow efficient loading of UTF-8 string data from files and byte streams. - Thread Safety:
ZCStringimplementsSendandSync. The thread-local source context is strictly thread-isolated;SourceGuardis!Sendand!Syncto guarantee scope stack integrity.
§Serde JSON Example
use arcstr::literal;
use serde::Deserialize;
use std::error::Error;
use zcstring::{serde_json_from_zcstring, ZCString};
#[derive(Debug, Deserialize)]
struct Animal {
animal: ZCString,
color: ZCString,
}
fn main() -> Result<(), Box<dyn Error>> {
let json = literal!(r#"{"animal":"cat", "color": "red"}"#);
// serde_json_from_zcstring sets `json` as the active thread-local source.
// When done, struct members point directly to memory within the `json` string.
let animal = serde_json_from_zcstring::<Animal>(json.into())?;
println!("animal: {:?}", animal);
Ok(())
}Macros§
- literal
- Create a const
ArcStrfrom a string literal. The resultingArcStrrequire no heap allocation, can be freely cloned and used interchangeably withArcStrs from the heap, and are effectively “free”. - literal_
substr feature = "substr": Create aconstSubstr.
Structs§
- Source
Guard - An RAII guard used to manage the lifecycle of the thread-local string source.
- ZCLazy
Value - A Serde type that preserves unparsed raw JSON and defers deserializing into
Tuntil accessed. - ZCRaw
Value - A Serde wrapper holding an unparsed raw JSON string slice within a
ZCString. - ZCRaw
Value And - A Serde composite holding both the unparsed raw JSON string slice and an eagerly decoded value
T. - ZCString
- A context-aware string handle for zero-copy string slicing and deserialization.
- ZCString
Iter Wrapper - An iterator wrapper that converts yielded
&strslices into zero-copyZCStringitems.
Enums§
- Reader
Error - Errors that can occur during file reading, streaming, or range operations.
Functions§
- serde_
json_ from_ zcstring - Parses a JSON string into type
Twhile using the providedZCStringas the active context for zero-copy deserialization.