Struct Unescape 

pub struct Unescape<'a> { /* private fields */ }

A streaming JSON string unescaper.

This struct is created by the unescape function. It implements an Iterator that yields Result<&'a [u8], UnescapeError>, lazily decoding the input.

The iterator’s output chunks are one of the following:

• Ok(&'a [u8]): A borrowed slice of the original input for a sequence of non-escaped bytes.
• Ok(&'static [u8]): A single-byte slice for a decoded escape sequence (e.g., \n becomes a slice containing 0x0A). For \uXXXX sequences, it yields a series of single-byte slices representing the UTF-8 encoding of the character.
• Err(UnescapeError): An error indicating an invalid escape sequence, which halts further iteration as described below.

Because the iterator operates on bytes, you can use helper methods like Unescape::decode_utf8 or Unescape::decode_utf8_lossy to convert the final result into a string.

Error Handling

When the iterator encounters an invalid or incomplete escape, it returns an Err(UnescapeError) describing the problem. The iterator then remains in an error state: subsequent calls to next() will continue to return that same error (i.e., the error is idempotent) and the iterator will not produce further Ok chunks. This makes the behavior deterministic for callers that check the first error and then stop.

Errors are classified by the precise condition encountered:

• InvalidEscape: The escape sequence uses an unknown escape character (e.g., \q).
• InvalidHex: A \u escape contains a non-hex character where a hex digit was expected (e.g., \uZ).
• UnexpectedEof: The input ended before a complete escape sequence could be read. This is used when there isn’t enough input yet to decide whether the sequence would be valid (for instance, an incomplete \u or a truncated surrogate pair).
• LoneSurrogate: A complete \uXXXX was read, and it encodes a high surrogate, but the following bytes definitively do not form a valid low surrogate escape (for example, the next character is a space or any non-\u character).

The difference between UnexpectedEof and LoneSurrogate is important:

• UnexpectedEof means we couldn’t decide because the input ended too early.
• LoneSurrogate means we did decide—we saw a full \uXXXX high surrogate, and the following input proves a pair will not follow.

Concrete examples

1. A high surrogate followed by other data (not a \u low-surrogate) → LoneSurrogate:

use json_escape::{unescape, UnescapeErrorKind, LoneSurrogateError};

let mut iter = unescape(r"\uD83D more data");
let err = iter.next().unwrap().unwrap_err();
assert!(matches!(err.kind(), UnescapeErrorKind::LoneSurrogate(LoneSurrogateError { surrogate: 0xD83D, .. })));

// Subsequent calls return the same error (iterator remains in the same error state).
let err = iter.next().unwrap().unwrap_err();
assert!(matches!(err.kind(), UnescapeErrorKind::LoneSurrogate(LoneSurrogateError { surrogate: 0xD83D, .. })));

2. An invalid escape character → InvalidEscape:

use json_escape::{unescape, UnescapeErrorKind, InvalidEscapeError};

let mut iter = unescape(r"\q"); // `\q` is not a defined escape
let err = iter.next().unwrap().unwrap_err();
assert!(matches!(err.kind(), UnescapeErrorKind::InvalidEscape(InvalidEscapeError { found: b'q', .. })));

3. A malformed \u with a non-hex character → InvalidHex:

use json_escape::{unescape, UnescapeErrorKind, InvalidHexError};

let mut iter = unescape(r"\uZ");
let err = iter.next().unwrap().unwrap_err();
assert!(matches!(err.kind(), UnescapeErrorKind::InvalidHex(InvalidHexError { found: b'Z', .. })));

4. Truncated / incomplete input ⇒ UnexpectedEof:

use json_escape::{unescape, UnescapeErrorKind};

// a) truncated after the first \uXXXX (no following bytes yet)
let mut iter = unescape(r"\uD83D");
let err = iter.next().unwrap().unwrap_err();
assert!(matches!(err.kind(), UnescapeErrorKind::UnexpectedEof));

// b) starts a second \u but is truncated before hex digits
let mut iter = unescape(r"\uD83D\u");
let err = iter.next().unwrap().unwrap_err();
assert!(matches!(err.kind(), UnescapeErrorKind::UnexpectedEof));

// c) a lone backslash at end of input
let mut iter = unescape("\\");
let err = iter.next().unwrap().unwrap_err();
assert!(matches!(err.kind(), UnescapeErrorKind::UnexpectedEof));

Note: This behavior intentionally mirrors common JSON parsers (e.g., serde_json, Go’s encoding/json) for the EOF vs. semantic error distinction.

Implemented Traits and Usage

• Iterator<Item = Result<&'a [u8], UnescapeError>>: The core trait for processing the unescaped byte chunks.
• std::io::Read (requires std feature): Lets you use the unescaper as a standard reader, perfect for integrating with other I/O APIs.
• TryFrom<Unescape<'a>> for Cow<'a, [u8]> (requires alloc feature): An efficient way to collect the unescaped bytes, propagating any errors.
• Clone, Debug: Standard utility traits.
• PartialEq<B: AsRef<[u8]>>: Compares the fully unescaped output with a byte slice.

Reading Unescaped Bytes

With the std feature, Unescape can be used as any other std::io::Read source. This is ideal for streaming and decoding large JSON string contents without buffering the entire result in memory first.

use json_escape::unescape;
use std::io::Read;

let mut reader = unescape(r#"chunk1\nchunk2"#);
let mut buf = Vec::new();

// Read all unescaped bytes from the iterator into the buffer.
reader.read_to_end(&mut buf).unwrap();

assert_eq!(buf, b"chunk1\nchunk2");

Implementations

impl<'a> Unescape<'a>

pub fn decode_utf8(self) -> Result<Cow<'a, str>, DecodeUtf8Error>

Decodes the unescaped byte stream into a UTF-8 string.

This method consumes the iterator and collects all resulting byte chunks. If an unescaping error occurs, it’s returned immediately. If the final sequence of bytes is not valid UTF-8, a UTF-8 error is returned.

Like From<Escape>, this is optimized to return a Cow::Borrowed if no escapes were present in the input, avoiding allocation.

Requires the alloc feature.

Example

use json_escape::unescape;

let input = r#"Emoji: \uD83D\uDE00"#;
let cow = unescape(input).decode_utf8().unwrap();

assert_eq!(cow, "Emoji: 😀");

pub fn decode_utf8_lossy(self) -> Result<Cow<'a, str>, UnescapeError>

Decodes the unescaped byte stream lossily into a UTF-8 string.

This is similar to Unescape::decode_utf8 but replaces any invalid UTF-8 sequences with the replacement character (U+FFFD) instead of returning an error.

An UnescapeError can still be returned if the JSON escaping itself is invalid.

Requires the alloc feature.

pub fn display_utf8(self) -> DisplayUnescape<'a>

Returns a wrapper that implements fmt::Display.

This allows an Unescape iterator to be used directly with formatting macros like println!, format!, etc. It writes the unescaped content directly to the formatter’s buffer, avoiding any heap allocations.

The iterator is consumed, and the resulting unescaped string is written to the formatter. Any invalid JSON escape sequences or invalid UTF-8 will cause a fmt::Error. You should be cautious when using this method with the format! macro, as a fmt::Error from us will cause the macro to panic.

For a more robust alternative that will not panic on UnescapeError or invalid bytes, consider using Unescape::display_utf8_lossy instead.

This method is a zero-allocation alternative to Unescape::decode_utf8, which might allocate a String to return the unescaped content.

Example

use json_escape::unescape;

let original = r#"Hello, \uD83C\uDF0E!"#;
let unescaper = unescape(original);

let formatted = format!("{}", unescaper.display_utf8());
assert_eq!(formatted, "Hello, 🌎!");

pub fn display_utf8_lossy(self) -> DisplayUnescapeLossy<'a>

Returns a wrapper that implements fmt::Display lossily.

This method is an allocation-free way to write unescaped content to a formatter. It handles invalid JSON escape sequences and invalid UTF-8 gracefully, making it a “lossy” operation.

• Invalid JSON escape sequences: Instead of causing an error, the iterator terminates without an error.
• Invalid UTF-8 bytes: These are replaced with the Unicode replacement character (U+FFFD).

This method is the zero-allocation counterpart to Unescape::decode_utf8_lossy.

Trait Implementations

impl<'a> Clone for Unescape<'a>

fn clone(&self) -> Unescape<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Unescape<'_>

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

Formats the value using the given formatter.

impl<'a> Iterator for Unescape<'a>

type Item = Result<&'a [u8], UnescapeError>

The type of the elements being iterated over.

fn next(&mut self) -> Option<Self::Item>

Advances the iterator and returns the next value.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the iterator.

fn next_chunk<const N: usize>( &mut self, ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>

where Self: Sized,

🔬This is a nightly-only experimental API. (iter_next_chunk)

Advances the iterator and returns an array containing the next N values.

fn count(self) -> usize

where Self: Sized,

Consumes the iterator, counting the number of iterations and returning it.

fn last(self) -> Option<Self::Item>

where Self: Sized,

Consumes the iterator, returning the last element.

fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>

🔬This is a nightly-only experimental API. (iter_advance_by)

Advances the iterator by n elements.

fn nth(&mut self, n: usize) -> Option<Self::Item>

Returns the nth element of the iterator.

fn step_by(self, step: usize) -> StepBy<Self>

where Self: Sized,

Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter>

where Self: Sized, U: IntoIterator<Item = Self::Item>,

Takes two iterators and creates a new iterator over both in sequence.

fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter>

where Self: Sized, U: IntoIterator,

‘Zips up’ two iterators into a single iterator of pairs.

fn intersperse(self, separator: Self::Item) -> Intersperse<Self>

where Self: Sized, Self::Item: Clone,

🔬This is a nightly-only experimental API. (iter_intersperse)

Creates a new iterator which places a copy of separator between adjacent items of the original iterator.

fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G>

where Self: Sized, G: FnMut() -> Self::Item,

🔬This is a nightly-only experimental API. (iter_intersperse)

Creates a new iterator which places an item generated by separator between adjacent items of the original iterator.

fn map<B, F>(self, f: F) -> Map<Self, F>

where Self: Sized, F: FnMut(Self::Item) -> B,

Takes a closure and creates an iterator which calls that closure on each element.

fn for_each<F>(self, f: F)

where Self: Sized, F: FnMut(Self::Item),

Calls a closure on each element of an iterator.

fn filter<P>(self, predicate: P) -> Filter<Self, P>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Creates an iterator which uses a closure to determine if an element should be yielded.

fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F>

where Self: Sized, F: FnMut(Self::Item) -> Option<B>,

Creates an iterator that both filters and maps.

fn enumerate(self) -> Enumerate<Self>

where Self: Sized,

Creates an iterator which gives the current iteration count as well as the next value.

fn peekable(self) -> Peekable<Self>

where Self: Sized,

Creates an iterator which can use the peek and peek_mut methods to look at the next element of the iterator without consuming it. See their documentation for more information.

fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Creates an iterator that skips elements based on a predicate.

fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Creates an iterator that yields elements based on a predicate.

fn map_while<B, P>(self, predicate: P) -> MapWhile<Self, P>

where Self: Sized, P: FnMut(Self::Item) -> Option<B>,

Creates an iterator that both yields elements based on a predicate and maps.

fn skip(self, n: usize) -> Skip<Self>

where Self: Sized,

Creates an iterator that skips the first n elements.

fn take(self, n: usize) -> Take<Self>

where Self: Sized,

Creates an iterator that yields the first n elements, or fewer if the underlying iterator ends sooner.

fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F>

where Self: Sized, F: FnMut(&mut St, Self::Item) -> Option<B>,

An iterator adapter which, like fold, holds internal state, but unlike fold, produces a new iterator.

fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F>

where Self: Sized, U: IntoIterator, F: FnMut(Self::Item) -> U,

Creates an iterator that works like map, but flattens nested structure.

fn flatten(self) -> Flatten<Self>

where Self: Sized, Self::Item: IntoIterator,

Creates an iterator that flattens nested structure.

fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N>

where Self: Sized, F: FnMut(&[Self::Item; N]) -> R,

🔬This is a nightly-only experimental API. (iter_map_windows)

Calls the given function f for each contiguous window of size N over self and returns an iterator over the outputs of f. Like slice::windows(), the windows during mapping overlap as well.

fn fuse(self) -> Fuse<Self>

where Self: Sized,

Creates an iterator which ends after the first None.

fn inspect<F>(self, f: F) -> Inspect<Self, F>

where Self: Sized, F: FnMut(&Self::Item),

Does something with each element of an iterator, passing the value on.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Iterator.

fn collect<B>(self) -> B

where B: FromIterator<Self::Item>, Self: Sized,

Transforms an iterator into a collection.

fn try_collect<B>( &mut self, ) -> <<Self::Item as Try>::Residual as Residual<B>>::TryType

where Self: Sized, Self::Item: Try, <Self::Item as Try>::Residual: Residual<B>, B: FromIterator<<Self::Item as Try>::Output>,

🔬This is a nightly-only experimental API. (iterator_try_collect)

Fallibly transforms an iterator into a collection, short circuiting if a failure is encountered.

fn collect_into<E>(self, collection: &mut E) -> &mut E

where E: Extend<Self::Item>, Self: Sized,

🔬This is a nightly-only experimental API. (iter_collect_into)

Collects all the items from an iterator into a collection.

fn partition<B, F>(self, f: F) -> (B, B)

where Self: Sized, B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool,

Consumes an iterator, creating two collections from it.

fn is_partitioned<P>(self, predicate: P) -> bool

where Self: Sized, P: FnMut(Self::Item) -> bool,

🔬This is a nightly-only experimental API. (iter_is_partitioned)

Checks if the elements of this iterator are partitioned according to the given predicate, such that all those that return true precede all those that return false.

fn try_fold<B, F, R>(&mut self, init: B, f: F) -> R

where Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try<Output = B>,

An iterator method that applies a function as long as it returns successfully, producing a single, final value.

fn try_for_each<F, R>(&mut self, f: F) -> R

where Self: Sized, F: FnMut(Self::Item) -> R, R: Try<Output = ()>,

An iterator method that applies a fallible function to each item in the iterator, stopping at the first error and returning that error.

fn fold<B, F>(self, init: B, f: F) -> B

where Self: Sized, F: FnMut(B, Self::Item) -> B,

Folds every element into an accumulator by applying an operation, returning the final result.

fn reduce<F>(self, f: F) -> Option<Self::Item>

where Self: Sized, F: FnMut(Self::Item, Self::Item) -> Self::Item,

Reduces the elements to a single one, by repeatedly applying a reducing operation.

fn try_reduce<R>( &mut self, f: impl FnMut(Self::Item, Self::Item) -> R, ) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType

where Self: Sized, R: Try<Output = Self::Item>, <R as Try>::Residual: Residual<Option<Self::Item>>,

🔬This is a nightly-only experimental API. (iterator_try_reduce)

Reduces the elements to a single one by repeatedly applying a reducing operation. If the closure returns a failure, the failure is propagated back to the caller immediately.

fn all<F>(&mut self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if every element of the iterator matches a predicate.

fn any<F>(&mut self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if any element of the iterator matches a predicate.

fn find<P>(&mut self, predicate: P) -> Option<Self::Item>

where Self: Sized, P: FnMut(&Self::Item) -> bool,

Searches for an element of an iterator that satisfies a predicate.

fn find_map<B, F>(&mut self, f: F) -> Option<B>

where Self: Sized, F: FnMut(Self::Item) -> Option<B>,

Applies function to the elements of iterator and returns the first non-none result.

fn try_find<R>( &mut self, f: impl FnMut(&Self::Item) -> R, ) -> <<R as Try>::Residual as Residual<Option<Self::Item>>>::TryType

where Self: Sized, R: Try<Output = bool>, <R as Try>::Residual: Residual<Option<Self::Item>>,

🔬This is a nightly-only experimental API. (try_find)

Applies function to the elements of iterator and returns the first true result or the first error.

fn position<P>(&mut self, predicate: P) -> Option<usize>

where Self: Sized, P: FnMut(Self::Item) -> bool,

Searches for an element in an iterator, returning its index.

fn max(self) -> Option<Self::Item>

where Self: Sized, Self::Item: Ord,

Returns the maximum element of an iterator.

fn min(self) -> Option<Self::Item>

where Self: Sized, Self::Item: Ord,

Returns the minimum element of an iterator.

fn max_by_key<B, F>(self, f: F) -> Option<Self::Item>

where B: Ord, Self: Sized, F: FnMut(&Self::Item) -> B,

Returns the element that gives the maximum value from the specified function.

fn max_by<F>(self, compare: F) -> Option<Self::Item>

where Self: Sized, F: FnMut(&Self::Item, &Self::Item) -> Ordering,

Returns the element that gives the maximum value with respect to the specified comparison function.

fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>

where B: Ord, Self: Sized, F: FnMut(&Self::Item) -> B,

Returns the element that gives the minimum value from the specified function.

fn min_by<F>(self, compare: F) -> Option<Self::Item>

where Self: Sized, F: FnMut(&Self::Item, &Self::Item) -> Ordering,

Returns the element that gives the minimum value with respect to the specified comparison function.

fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)

where FromA: Default + Extend<A>, FromB: Default + Extend<B>, Self: Sized + Iterator<Item = (A, B)>,

Converts an iterator of pairs into a pair of containers.

fn copied<'a, T>(self) -> Copied<Self>

where T: Copy + 'a, Self: Sized + Iterator<Item = &'a T>,

Creates an iterator which copies all of its elements.

fn cloned<'a, T>(self) -> Cloned<Self>

where T: Clone + 'a, Self: Sized + Iterator<Item = &'a T>,

Creates an iterator which clones all of its elements.

fn cycle(self) -> Cycle<Self>

where Self: Sized + Clone,

Repeats an iterator endlessly.

fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N>

where Self: Sized,

🔬This is a nightly-only experimental API. (iter_array_chunks)

Returns an iterator over N elements of the iterator at a time.

fn sum<S>(self) -> S

where Self: Sized, S: Sum<Self::Item>,

Sums the elements of an iterator.

fn product<P>(self) -> P

where Self: Sized, P: Product<Self::Item>,

Iterates over the entire iterator, multiplying all the elements

fn cmp<I>(self, other: I) -> Ordering

where I: IntoIterator<Item = Self::Item>, Self::Item: Ord, Self: Sized,

Lexicographically compares the elements of this Iterator with those of another.

fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering

where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Ordering,

🔬This is a nightly-only experimental API. (iter_order_by)

Lexicographically compares the elements of this Iterator with those of another with respect to the specified comparison function.

fn partial_cmp<I>(self, other: I) -> Option<Ordering>

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Lexicographically compares the PartialOrd elements of this Iterator with those of another. The comparison works like short-circuit evaluation, returning a result without comparing the remaining elements. As soon as an order can be determined, the evaluation stops and a result is returned.

fn partial_cmp_by<I, F>(self, other: I, partial_cmp: F) -> Option<Ordering>

where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Option<Ordering>,

🔬This is a nightly-only experimental API. (iter_order_by)

Lexicographically compares the elements of this Iterator with those of another with respect to the specified comparison function.

fn eq<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialEq<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are equal to those of another.

fn eq_by<I, F>(self, other: I, eq: F) -> bool

where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, <I as IntoIterator>::Item) -> bool,

🔬This is a nightly-only experimental API. (iter_order_by)

Determines if the elements of this Iterator are equal to those of another with respect to the specified equality function.

fn ne<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialEq<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are not equal to those of another.

fn lt<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically less than those of another.

fn le<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically less or equal to those of another.

fn gt<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically greater than those of another.

fn ge<I>(self, other: I) -> bool

where I: IntoIterator, Self::Item: PartialOrd<<I as IntoIterator>::Item>, Self: Sized,

Determines if the elements of this Iterator are lexicographically greater than or equal to those of another.

fn is_sorted(self) -> bool

where Self: Sized, Self::Item: PartialOrd,

Checks if the elements of this iterator are sorted.

fn is_sorted_by<F>(self, compare: F) -> bool

where Self: Sized, F: FnMut(&Self::Item, &Self::Item) -> bool,

Checks if the elements of this iterator are sorted using the given comparator function.

fn is_sorted_by_key<F, K>(self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> K, K: PartialOrd,

Checks if the elements of this iterator are sorted using the given key extraction function.

impl<B: AsRef<[u8]> + ?Sized> PartialEq<B> for Unescape<'_>

fn eq(&self, other: &B) -> bool

Compares the unescaped output with a byte-slice-like object.

An Unescape iterator is considered equal to a byte slice if it successfully unescapes to produce a sequence of bytes identical to that slice. If the iterator would produce an error, the comparison returns false.

Example

use json_escape::unescape;

let unescaper = unescape(r#"hello\nworld"#);
assert_eq!(unescaper, b"hello\nworld");

// An iterator that produces an error is not equal to any valid slice.
let failing_unescaper = unescape(r#"\k"#);
assert_ne!(failing_unescaper, b"k");

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<B: AsRef<[u8]>> PartialEq<Unescape<'_>> for Result<B, UnescapeError>

fn eq(&self, unescape: &Unescape<'_>) -> bool

Compares the unescaper’s outcome with a Result.

This implementation allows for precise testing of the Unescape iterator by comparing it against either a successful outcome (Ok) or a specific failure (Err).

• If result is Ok(bytes), the comparison is true only if the iterator completes successfully and its concatenated output is identical to bytes.

• If result is Err(error), the comparison is true only if the iterator produces the exact same UnescapeError.

Example

use json_escape::{unescape, UnescapeError, InvalidEscapeError};

// --- Success Case ---
let unescaper = unescape(r#"hello\tworld"#);
// The comparison is against an `Ok` variant.
assert_eq!(Ok("hello\tworld"), unescaper);

// --- Error Case ---
let failing_unescaper = unescape(r#"invalid-\u"#);
// We can assert that the iterator produces a specific error.
assert_eq!(Err::<&str, _>(unexpected_eof), failing_unescaper);

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<Unescape<'a>> for Unescape<'b>

fn eq(&self, other: &Unescape<'a>) -> bool

Compares two Unescape iterators for equality based on their terminal result.

The equality of two Unescape iterators is determined by the final Result that would be obtained if each iterator were fully consumed (e.g., by using try_collect()).

The specific rules are as follows:

1. Error vs. Error: If both iterators terminate with an Err, they are considered equal if and only if their UnescapeErrors are identical. Any bytes successfully unescaped before the error are ignored in this case.
2. Success vs. Success: If both iterators terminate with Ok, they are considered equal if and only if the complete sequence of unescaped bytes is identical for both.
3. Success vs. Error: If one iterator terminates with Ok and the other with Err, they are always not equal.

Example

use json_escape::unescape;

// Case 1: Both iterators produce the same error. They are equal,
// even though their valid prefixes ("a" and "b") are different.
let failing_a = unescape(r#"a\k"#);
let failing_b = unescape(r#"b\k"#);
assert_eq!(failing_a, failing_b);

// Case 2: Both iterators succeed. Equality depends on the byte stream.
let successful_a = unescape(r#"hello\nworld"#);
let successful_b = unescape(r#"hello\nworld"#);
assert_eq!(successful_a, successful_b);

let successful_c = unescape(r#"different"#);
assert_ne!(successful_a, successful_c);

// Case 3: One succeeds and one fails. They are not equal.
let succeeding = unescape(r#"stop"#);
let failing = unescape(r#"stop\k"#);
assert_ne!(succeeding, failing);

// Case 4: Both iterators fail differently. They are not equal.
let failing_a = unescape(r#"data:\k"#);
let failing_b = unescape(r#"data:\"#);
assert_ne!(failing_a, failing_b);

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Read for Unescape<'_>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

Reads all bytes until EOF in this source, placing them into buf.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<'a> TryFrom<Unescape<'a>> for Cow<'a, [u8]>

fn try_from(value: Unescape<'a>) -> Result<Self, Self::Error>

Efficiently collects the unescaped bytes into a Cow<'a, [u8]>.

This implementation will return Cow::Borrowed if the original input contained no escape sequences, avoiding allocation. Otherwise, it returns Cow::Owned.

If any UnescapeError is encountered during iteration, the operation halts and returns that error.

Requires the alloc feature.

type Error = UnescapeError

The type returned in the event of a conversion error.

impl<'a> FusedIterator for Unescape<'a>