Skip to main content

Crate zcstring

Crate zcstring 

Source
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 SOURCE string in thread-local storage. When creating a ZCString from a &str (via ZCString::from or 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 SourceGuard and ZCString::with_source to 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_zcstring for 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 value T.
    • ZCLazyValue: Defers parsing of a raw JSON slice into T until first access, caching the result in a thread-safe std::sync::OnceLock.
  • Stream and File Reading: Utility functions ZCString::read_range, ZCString::read_exact, and ZCString::from_file allow efficient loading of UTF-8 string data from files and byte streams.
  • Thread Safety: ZCString implements Send and Sync. The thread-local source context is strictly thread-isolated; SourceGuard is !Send and !Sync to 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 ArcStr from a string literal. The resulting ArcStr require no heap allocation, can be freely cloned and used interchangeably with ArcStrs from the heap, and are effectively “free”.
literal_substr
feature = "substr": Create a const Substr.

Structs§

SourceGuard
An RAII guard used to manage the lifecycle of the thread-local string source.
ZCLazyValue
A Serde type that preserves unparsed raw JSON and defers deserializing into T until accessed.
ZCRawValue
A Serde wrapper holding an unparsed raw JSON string slice within a ZCString.
ZCRawValueAnd
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.
ZCStringIterWrapper
An iterator wrapper that converts yielded &str slices into zero-copy ZCString items.

Enums§

ReaderError
Errors that can occur during file reading, streaming, or range operations.

Functions§

serde_json_from_zcstring
Parses a JSON string into type T while using the provided ZCString as the active context for zero-copy deserialization.