silk.json.reader.

When to use#

Use JsonReader to read a large or streamed JSON document from a ByteDuplex transport, such as an HTTP body. When the whole document is in memory, use silk.json.scanner.JsonScanner.

Details#

Each call to JsonReader.next returns one checked token. The raw bytes of a string, number, or literal are copied into a scratch buffer that the caller gives. The reader does not keep a reference to the input or the scratch buffer between calls. It does not allocate.

Errors#

• JsonError if the input is not valid JSON, or with reason TokenTooLarge if a token does not fit in the scratch buffer.

• BufferError if the input fails.

Gotchas#

After an error, the reader cannot continue. Drop each token before the next call, because the token borrows the scratch buffer.

Import as JsonReader with import silk.json.reader { JsonReader }.

Public declarations: 2.

JsonReadToken#

pub struct JsonReadToken<'scratch>

One token and its raw bytes in the scratch buffer.

Details#

For a string, raw includes the quotes and the escapes. For punctuation and the end of input, raw is empty.

Field token#

pub token: JsonToken

The token. Its offsets are from the start of the document.

Field raw#

pub raw: &'scratch [u8]

The source bytes of a string, number, or literal token.

JsonReader#

pub struct JsonReader

The state of one JSON document read from a BufferedInput, for documents that do not fit in one slice.

When to use#

Use it to read a large or streamed JSON document from a ByteDuplex transport, such as an HTTP body. When the whole document is in memory, use silk.json.scanner.JsonScanner.

Details#

Each call to JsonReader.next returns one checked token and copies its raw bytes into a scratch buffer that the caller gives. The reader does not keep a reference to the input or the scratch buffer between calls, and does not allocate. It keeps the position in the document between calls. After the document ends, each call returns EndOfInput.

Implementation JsonReader#

impl JsonReader

Associated function make#

pub fn make() -> JsonReader

Returns a reader at the start of a document. It does not allocate.

Method next#

pub effect fn next<'scratch>(
    self: &mut JsonReader,
    input: &mut BufferedInput,
    scratch: &'scratch mut [u8],
    deadline: Option<Instant>,
  ) -> JsonReadToken<'scratch>
  ! JsonError | BufferError
  ? &mut ByteDuplex | &mut MonotonicClock

Reads the next token from input and copies its raw bytes into scratch.

Details#

The token borrows only scratch. A number at the end of the buffered bytes waits for the next byte, which stays in input. Whitespace does not use scratch space. deadline applies to each read.

Errors#

• JsonError if the input is not valid JSON.

• JsonError with reason TokenTooLarge if the token does not fit in scratch. offset is the first byte of the token and available is the scratch size.

• BufferError if the input fails, or BufferError.Terminal after an earlier error.

Gotchas#

After an error, the reader cannot continue. Drop each token before the next call, because the token borrows scratch.

Category: Data formats.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.