Struct UnescapeStream 

pub struct UnescapeStream { /* private fields */ }

A streaming JSON string unescaper that operates over byte slices.

This struct is the main entry point for streaming unescaping. It maintains a small internal buffer to handle escape sequences that are split across slice boundaries without requiring heap allocations.

See the module-level documentation for examples and more details.

Implementations

impl UnescapeStream

pub fn new() -> Self

Creates a new, empty UnescapeStream.

pub fn try_unescape_next<'a, 'b, I: AsRef<[u8]> + ?Sized>( &'a mut self, next_part: &'b I, ) -> Result<(Option<char>, UnescapeNext<'a, 'b>), UnescapeError>

Processes the next byte slice, returning a fallible result.

This is a convenience wrapper around UnescapeStream::unescape_next. Instead of returning an Option<Result<...>>, it “hoists” a potential boundary error into the main Result.

This simplifies error handling, as you can use the ? operator to handle errors from both the boundary character and the rest of the stream.

Returns

• Ok((Option<char>, UnescapeNext)) on success. The Option<char> contains the successfully unescaped character from a boundary-spanning sequence.
• Err(UnescapeError) if completing a boundary-spanning sequence results in a parsing error.

pub fn unescape_next<'a, 'b, I: AsRef<[u8]> + ?Sized>( &'a mut self, next_part: &'b I, ) -> (Option<Result<char, UnescapeError>>, UnescapeNext<'a, 'b>)

Processes the next byte slice in the stream.

This is the primary method for feeding data to the unescaper. It returns a tuple:

1. An Option<Result<char, UnescapeError>> for the character that may have spanned the boundary from the previous slice. None if the previous slice ended cleanly.
2. An UnescapeNext iterator for the remainder of the current slice.

If the current slice ends with an incomplete escape sequence, that partial data is saved internally. It will be resolved on the next call to unescape_next again with the subsequent slice or reported as an error by finish.

pub fn finish(self) -> Result<(), UnescapeError>

Finalizes the unescaping process, checking for leftover incomplete data.

This method must be called after all slices have been processed. It checks if there is an incomplete escape sequence stored in its internal buffer. If so, it means the stream ended unexpectedly, and an Err(UnescapeError) is returned.

This method consumes the UnescapeStream, preventing further use.

pub fn clear(&mut self)

Clears any partial escape sequence data from the internal buffer.

You might call this after encountering a non-fatal error if you want to discard the invalid partial data and continue processing the stream from a fresh state.

Warning: If you clear() the state after an error and then call finish() without processing more data, finish() will return Ok(()) because the partial state that caused the original error has been erased.

pub fn unescape_from_fn<Src, Dst, SrcError, DstError, B>( self, src: Src, dst: Dst, ) -> Result<(), UnescapeFnError<SrcError, DstError>>

where Src: FnMut() -> Option<Result<B, SrcError>>, Dst: FnMut(UnescapedToken<'_>) -> Result<(), DstError>, B: AsRef<[u8]>,

👎Deprecated since 0.3.1: This sync-only function is superseded by the runtime-agnostic unescape_stream_into! macro.

Unescapes a stream of byte chunks from a source function to a destination function.

This function acts as a driver for the UnescapeStream. It repeatedly calls a source function (src) to get the next chunk of data, unescapes it, and then calls a destination function (dst) for each resulting UnescapedToken.

This provides a flexible way to connect any data source (like a file reader or network socket) to any data sink without manually iterating.

Parameters

• self: The UnescapeStream instance, which will be consumed.
• src: A closure or function that, when called, returns the next chunk of data as Option<Result<B, SrcError>>. It should return Some(Ok(chunk)) for data, Some(Err(e)) for a source error, and None to signal the end of the stream.
• dst: A closure or function that receives an UnescapedToken. It should return Ok(()) on success or Err(DstError) on failure.

Errors

Returns an UnescapeFnError if an error occurs at any point:

• UnescapeFnError::Src if the src function returns an error.
• UnescapeFnError::Unescape if the JSON string is malformed (e.g., an invalid escape sequence or incomplete data at the end of the stream).
• UnescapeFnError::Dst if the dst function returns an error.

pub fn unescape_from_source<Src, Dst, SrcError, DstError>( self, src: Src, dst: Dst, ) -> Result<(), UnescapeFnError<SrcError, DstError>>

where Src: ChunkSource<Error = SrcError>, Dst: FnMut(UnescapedToken<'_>) -> Result<(), DstError>,

👎Deprecated since 0.3.1: This sync-only function is superseded by the runtime-agnostic unescape_stream_into! macro.

Processes a stream of byte chunks from a source and unescapes them to a destination.

This function drives the unescaping process by repeatedly calling a src (source) to get a chunk of bytes, unescaping the data, and then passing the resulting UnescapedTokens to a dst (destination).

This provides a flexible pipeline for connecting any byte source (e.g., a file or network stream) to any byte sink without manual iteration.

Parameters

• src: A ChunkSource that provides the raw, escaped byte chunks.
• dst: A closure that receives each UnescapedToken and processes it.

Errors

This function returns an UnescapeFnError if an error occurs at any stage:

• UnescapeFnError::Src: An error from the source (src).
• UnescapeFnError::Unescape: The data is malformed (e.g., an invalid escape sequence).
• UnescapeFnError::Dst: An error from the destination (dst).

Trait Implementations

impl Clone for UnescapeStream

fn clone(&self) -> UnescapeStream

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UnescapeStream

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for UnescapeStream

fn default() -> Self

Returns the “default value” for a type.