Struct Decoder 

pub struct Decoder<'de> { /* private fields */ }

JSON decoder over a unified token stream.

Implementations

impl<'de> Decoder<'de>

pub fn new(input: &'de [u8]) -> Self

Create a decoder from byte input (default config).

Examples found in repository

examples/zero_copy_reuse.rs (line 89)

fn main() -> nextjson::Result<()> {
    // ---- 1. 零拷贝借用 ----
    // payload 用未转义字符串书写：JSON 解码器对未转义字符串返回 Cow::Borrowed，
    // 从而 `Bytes` 能直接借用输入切片（若写成 `[10,20,30,40]` 数组则必然拷贝，
    // 与 serde 的 `&[u8]` 借用语义一致）。
    let input = br#"{"event":"market.tick","payload":"raw-bytes","seq":7}"#;
    let header: Header = nextjson::from_slice(input)?;
    println!(
        "借用解码: event = {:?}, payload = {:?}, seq = {}",
        header.event,
        header.payload.as_bytes(),
        header.seq
    );

    // 指针范围断言：event / payload 必须落在输入切片内（零拷贝的直接证据）。
    let input_start = input.as_ptr() as usize;
    let input_end = input_start + input.len();
    let event_ptr = header.event.as_ptr() as usize;
    let payload_ptr = header.payload.as_bytes().as_ptr() as usize;
    assert!(
        (input_start..input_end).contains(&event_ptr),
        "event 必须借用输入，不能拷贝"
    );
    assert!(
        (input_start..input_end).contains(&payload_ptr),
        "payload 必须借用输入，不能拷贝"
    );
    println!("指针断言通过: event 与 payload 均直接指向输入切片");

    // 二进制格式通过 Value 中继，无法借用——改用拥有型等价物往返，
    // 证明同一数据模型在 CBOR 中原生字节串无损。
    let owned = HeaderOwned {
        event: header.event.to_owned(),
        payload: header.payload.as_bytes().to_vec(),
        seq: header.seq,
    };
    let cbor = nextjson::formats::Cbor.encode(&owned)?;
    let back: HeaderOwned = nextjson::formats::Cbor.decode(&cbor)?;
    assert_eq!(back, owned);
    println!("拥有型等价物经 CBOR 原生字节串往返一致: {} B", cbor.len());

    // ---- 2. 就地解码 + 槽复用 ----
    // 持续解码场景：同一个槽反复用于下一条消息，不重新分配存储。
    let messages = [
        br#"{"event":"a","payload":"x","seq":1}"#.as_slice(),
        br#"{"event":"b","payload":"yy","seq":2}"#.as_slice(),
        br#"{"event":"c","payload":"zzz","seq":3}"#.as_slice(),
    ];

    // 复用同一个 DecodeSlot<Header>，逐条 nextdecode_into。
    let mut slot = DecodeSlot::<Header>::new();
    let mut decoded: Vec<Header> = Vec::new();
    for raw in &messages {
        let mut decoder = Decoder::new(raw);
        Header::nextdecode_into(&mut decoder, &mut slot)?;
        decoder.end()?;
        // take 取出本条，槽回归空，下一条继续复用。
        decoded.push(slot.take().expect("解码成功必须写入槽"));
    }
    assert_eq!(decoded[0].seq, 1);
    assert_eq!(decoded[1].event, "b");
    assert_eq!(decoded[2].payload.as_bytes(), b"zzz");
    println!(
        "槽复用: 3 条消息共用 1 个 DecodeSlot，逐条解码成功: {:?}",
        decoded.iter().map(|h| h.seq).collect::<Vec<_>>()
    );

    // 显式证明复用：一个槽连续解两条，且第二条完成后 is_initialized 恢复。
    let mut slot2 = DecodeSlot::<Header>::new();
    let mut d1 = Decoder::new(messages[0]);
    Header::nextdecode_into(&mut d1, &mut slot2)?;
    d1.end()?;
    let first = slot2.take().unwrap();
    let mut d2 = Decoder::new(messages[1]);
    Header::nextdecode_into(&mut d2, &mut slot2)?;
    d2.end()?;
    let second = slot2.take().unwrap();
    assert_eq!((first.seq, second.seq), (1, 2));
    println!(
        "同一个槽连续承载两条消息: seq {} -> seq {}",
        first.seq, second.seq
    );

    Ok(())
}

pub fn with_config(input: &'de [u8], config: DecodeConfig) -> Self

Create a decoder from byte input (custom config).

pub fn from_tokens(tokens: Vec<Token<'de>>) -> Self

Create a decoder over an in-memory token stream.

pub fn max_depth(&self) -> u32

The maximum nesting depth.

pub fn save(&self) -> Mark

Save the current position (for untagged-enum backtracking).

pub fn restore(&mut self, mark: Mark)

Restore a position saved with save.

pub fn end(&mut self) -> Result<()>

Verify that the input contains no value or token after the decoded value.

Whitespace at the end of byte input is accepted. Top-level helpers call this automatically; direct Decoder users can call it after nextdecode.

Examples found in repository

examples/zero_copy_reuse.rs (line 91)

fn main() -> nextjson::Result<()> {
    // ---- 1. 零拷贝借用 ----
    // payload 用未转义字符串书写：JSON 解码器对未转义字符串返回 Cow::Borrowed，
    // 从而 `Bytes` 能直接借用输入切片（若写成 `[10,20,30,40]` 数组则必然拷贝，
    // 与 serde 的 `&[u8]` 借用语义一致）。
    let input = br#"{"event":"market.tick","payload":"raw-bytes","seq":7}"#;
    let header: Header = nextjson::from_slice(input)?;
    println!(
        "借用解码: event = {:?}, payload = {:?}, seq = {}",
        header.event,
        header.payload.as_bytes(),
        header.seq
    );

    // 指针范围断言：event / payload 必须落在输入切片内（零拷贝的直接证据）。
    let input_start = input.as_ptr() as usize;
    let input_end = input_start + input.len();
    let event_ptr = header.event.as_ptr() as usize;
    let payload_ptr = header.payload.as_bytes().as_ptr() as usize;
    assert!(
        (input_start..input_end).contains(&event_ptr),
        "event 必须借用输入，不能拷贝"
    );
    assert!(
        (input_start..input_end).contains(&payload_ptr),
        "payload 必须借用输入，不能拷贝"
    );
    println!("指针断言通过: event 与 payload 均直接指向输入切片");

    // 二进制格式通过 Value 中继，无法借用——改用拥有型等价物往返，
    // 证明同一数据模型在 CBOR 中原生字节串无损。
    let owned = HeaderOwned {
        event: header.event.to_owned(),
        payload: header.payload.as_bytes().to_vec(),
        seq: header.seq,
    };
    let cbor = nextjson::formats::Cbor.encode(&owned)?;
    let back: HeaderOwned = nextjson::formats::Cbor.decode(&cbor)?;
    assert_eq!(back, owned);
    println!("拥有型等价物经 CBOR 原生字节串往返一致: {} B", cbor.len());

    // ---- 2. 就地解码 + 槽复用 ----
    // 持续解码场景：同一个槽反复用于下一条消息，不重新分配存储。
    let messages = [
        br#"{"event":"a","payload":"x","seq":1}"#.as_slice(),
        br#"{"event":"b","payload":"yy","seq":2}"#.as_slice(),
        br#"{"event":"c","payload":"zzz","seq":3}"#.as_slice(),
    ];

    // 复用同一个 DecodeSlot<Header>，逐条 nextdecode_into。
    let mut slot = DecodeSlot::<Header>::new();
    let mut decoded: Vec<Header> = Vec::new();
    for raw in &messages {
        let mut decoder = Decoder::new(raw);
        Header::nextdecode_into(&mut decoder, &mut slot)?;
        decoder.end()?;
        // take 取出本条，槽回归空，下一条继续复用。
        decoded.push(slot.take().expect("解码成功必须写入槽"));
    }
    assert_eq!(decoded[0].seq, 1);
    assert_eq!(decoded[1].event, "b");
    assert_eq!(decoded[2].payload.as_bytes(), b"zzz");
    println!(
        "槽复用: 3 条消息共用 1 个 DecodeSlot，逐条解码成功: {:?}",
        decoded.iter().map(|h| h.seq).collect::<Vec<_>>()
    );

    // 显式证明复用：一个槽连续解两条，且第二条完成后 is_initialized 恢复。
    let mut slot2 = DecodeSlot::<Header>::new();
    let mut d1 = Decoder::new(messages[0]);
    Header::nextdecode_into(&mut d1, &mut slot2)?;
    d1.end()?;
    let first = slot2.take().unwrap();
    let mut d2 = Decoder::new(messages[1]);
    Header::nextdecode_into(&mut d2, &mut slot2)?;
    d2.end()?;
    let second = slot2.take().unwrap();
    assert_eq!((first.seq, second.seq), (1, 2));
    println!(
        "同一个槽连续承载两条消息: seq {} -> seq {}",
        first.seq, second.seq
    );

    Ok(())
}

pub fn begin_object(&mut self) -> Result<()>

Consume { (with depth check).

pub fn end_object(&mut self) -> Result<()>

Consume }.

pub fn object_key(&mut self) -> Result<Option<Cow<'de, str>>>

Read the next object key; returns None on } (not consumed).

pub fn object_entry_sep(&mut self) -> Result<bool>

Object entry separator: true if more entries follow (， consumed), false at object end (} left for end_object).

pub fn begin_array(&mut self) -> Result<()>

Consume [.

pub fn end_array(&mut self) -> Result<()>

Consume ].

pub fn array_has_more(&mut self) -> Result<bool>

Whether the array has more elements (] not consumed).

pub fn array_entry_sep(&mut self) -> Result<bool>

Array entry separator: true if more elements follow (， consumed), false at array end (] left for end_array).

pub fn unit(&mut self) -> Result<()>

Consume null.

pub fn bool(&mut self) -> Result<bool>

Read a boolean.

pub fn number(&mut self) -> Result<Number>

Read a number.

pub fn string(&mut self) -> Result<Cow<'de, str>>

Read a string (may borrow input).

pub fn char(&mut self) -> Result<char>

Read a single character (must be a one-character string).

pub fn skip_value(&mut self) -> Result<()>

Skip any one value (recursive, depth-limited).

Byte inputs dispatch on the source byte directly (no Token is materialized); replayed token streams use the token path.

Trait Implementations

impl<'de> FormatDecoder<'de> for Decoder<'de>

type Error = Error

The error type produced by this format’s methods.

fn begin_object(&mut self) -> Result<(), Self::Error>

Consume { (with depth check).

fn end_object(&mut self) -> Result<(), Self::Error>

Consume }.

fn object_key(&mut self) -> Result<Option<Cow<'de, str>>, Self::Error>

Read the next object key; returns None on } (not consumed).

fn object_entry_sep(&mut self) -> Result<bool, Self::Error>

Object entry separator: true if more entries follow, false at end.

fn begin_array(&mut self) -> Result<(), Self::Error>

Consume [ (with depth check).

fn end_array(&mut self) -> Result<(), Self::Error>

Consume ].

fn array_has_more(&mut self) -> Result<bool, Self::Error>

Whether the array has more elements (] not consumed).

fn array_entry_sep(&mut self) -> Result<bool, Self::Error>

Array entry separator: true if more elements follow, false at end.

fn unit(&mut self) -> Result<(), Self::Error>

Consume null.

fn bool(&mut self) -> Result<bool, Self::Error>

Read a boolean.

fn number(&mut self) -> Result<Number, Self::Error>

Read a number.

fn string(&mut self) -> Result<Cow<'de, str>, Self::Error>

Read a string (may borrow the source).

fn char(&mut self) -> Result<char, Self::Error>

Read a single character (a one-scalar string).

fn skip_value(&mut self) -> Result<(), Self::Error>

Skip any one value.

fn option_tag(&mut self) -> Result<OptionTag, Self::Error>

Report whether the next value is Option::None or Option::Some.

fn peek_token(&mut self) -> Result<Token<'de>, Self::Error>

Peek the next token without consuming it (container-flatten support).

fn next_token(&mut self) -> Result<Token<'de>, Self::Error>

Consume and return the next token.

fn save(&self) -> Mark

Save the current position (for untagged-enum backtracking).

fn restore(&mut self, mark: Mark)

Restore a position saved with save.

fn set_expecting(&mut self, expecting: &'static str) -> Option<&'static str>

Set the human-readable description of the type currently being decoded, so container-level type-mismatch errors (begin_object / begin_array hitting the wrong token) can name the expected type instead of a bare structural token like '{'.

fn array_len_hint(&self) -> Option<usize>

A conservative upper bound for the remaining elements in the current array, when the wire format carries a length prefix.

fn object_len_hint(&self) -> Option<usize>

A conservative upper bound for the remaining entries in the current object, subject to the same resource-safety rule as array_len_hint.

fn i8(&mut self) -> Result<i8, Self::Error>

Read a $t (default: read a number and convert).

fn i16(&mut self) -> Result<i16, Self::Error>

Read a $t (default: read a number and convert).

fn i32(&mut self) -> Result<i32, Self::Error>

Read a $t (default: read a number and convert).

fn i64(&mut self) -> Result<i64, Self::Error>

Read a $t (default: read a number and convert).

fn i128(&mut self) -> Result<i128, Self::Error>

Read a $t (default: read a number and convert).

fn isize(&mut self) -> Result<isize, Self::Error>

Read a $t (default: read a number and convert).

fn u8(&mut self) -> Result<u8, Self::Error>

Read a $t (default: read a number and convert).

fn u16(&mut self) -> Result<u16, Self::Error>

Read a $t (default: read a number and convert).

fn u32(&mut self) -> Result<u32, Self::Error>

Read a $t (default: read a number and convert).

fn u64(&mut self) -> Result<u64, Self::Error>

Read a $t (default: read a number and convert).

fn u128(&mut self) -> Result<u128, Self::Error>

Read a $t (default: read a number and convert).

fn usize(&mut self) -> Result<usize, Self::Error>

Read a $t (default: read a number and convert).

fn bytes(&mut self) -> Result<Cow<'de, [u8]>, Self::Error>

Read a byte sequence (may borrow the source).

fn map_key<K: for<'a> NsonDeserialize<'a>>( &mut self, ) -> Result<Option<K>, Self::Error>

Read the next map key.

fn is_human_readable(&self) -> bool

Whether this format produces human-readable output.