std/encoding/json

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/encoding/json"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias	Package	Source file
`bytes`	`core/bytes`	value.dodo
`float_decimal`	`std/float_decimal`	encoder.dodo
`io`	`std/io`	api.dodo, encoder.dodo, value.dodo
`mem`	`core/mem`	api.dodo, encoder.dodo, value.dodo
`num`	`core/num`	encoder.dodo, keys.dodo
`ptr`	`core/ptr`	encoder.dodo
`text`	`std/text`	encoder.dodo, value.dodo

`decode`

Function · Source

User-defined codecs have encode_json(encoder) and static decode_json(value). @derive(Json) generates these same ordinarily checked methods.

pub fn decode<T>(input: &[u8]) -> T!Error from(input)

`decode_str`

Function · Source

pub fn decode_str<T>(input: &str) -> T!Error from(input)

`from_value`

Function · Source

pub fn from_value<T>(value: Value) -> T!Error from(value)

`encode`

Function · Source

pub fn encode<T, W>(value: &T, sink: &mut W) -> usize!Error

`encode_pretty`

Function · Source

pub fn encode_pretty<T, W>(value: &T, sink: &mut W) -> usize!Error

`to_slice`

Function · Source

pub fn to_slice<T>(value: &T, destination: &mut[u8]) -> usize!Error

`to_slice_pretty`

Function · Source

pub fn to_slice_pretty<T>(value: &T, destination: &mut[u8]) -> usize!Error

`validate`

Function · Source

pub fn validate(input: &[u8]) -> void!Error

`parse_reader`

Function · Source

Read one complete document to EOF into explicit caller-owned storage. When full, std/io probes and consumes one byte to distinguish exact fit from exhaustion. Returned views borrow storage, never the reader.

pub fn parse_reader<R>(reader: &mut R, storage: &mut[u8]) -> Value!Error from(storage)

`decode_reader`

Function · Source

pub fn decode_reader<T, R>(reader: &mut R, storage: &mut[u8]) -> T!Error from(storage)

`compact`

Function · Source

Transform a validated document without interpreting numeric lexemes.

pub fn compact<W>(input: &[u8], sink: &mut W) -> usize!Error

`pretty`

Function · Source

pub fn pretty<W>(input: &[u8], sink: &mut W) -> usize!Error

`Encoder`

Struct · Source

A checked streaming JSON writer. The sink follows std/io’s writer contract. Errors latch: after partial output, further calls cannot report success.

pub struct Encoder<W> {
    // Private implementation fields omitted.
}

`Encoder.new`

Function · Source

pub fn new(sink: &mut W) -> Encoder<W> from(sink)

`Encoder.pretty`

Function · Source

pub fn pretty(sink: &mut W) -> Encoder<W> from(sink)

`Encoder.written`

Function · Source

pub fn written(&self) -> usize

`Encoder.begin_object`

Function · Source

pub fn begin_object(&mut self) -> void!Error

`Encoder.begin_array`

Function · Source

pub fn begin_array(&mut self) -> void!Error

`Encoder.end_object`

Function · Source

pub fn end_object(&mut self) -> void!Error

`Encoder.end_array`

Function · Source

pub fn end_array(&mut self) -> void!Error

`Encoder.key`

Function · Source

pub fn key(&mut self, name: &str) -> void!Error

`Encoder.null`

Function · Source

pub fn null(&mut self) -> void!Error

`Encoder.boolean`

Function · Source

pub fn boolean(&mut self, value: bool) -> void!Error

`Encoder.unsigned`

Function · Source

pub fn unsigned(&mut self, value: u64) -> void!Error

`Encoder.signed`

Function · Source

pub fn signed(&mut self, value: i64) -> void!Error

`Encoder.floating`

Function · Source

pub fn floating(&mut self, value: f64) -> void!Error

`Encoder.string`

Function · Source

pub fn string(&mut self, value: &str) -> void!Error

`Encoder.json_string`

Function · Source

pub fn json_string(&mut self, value: &String) -> void!Error

`Encoder.value`

Function · Source

pub fn value(&mut self, value: &Value) -> void!Error

`Encoder.raw`

Function · Source

Raw insertion is validated as one complete JSON value before writing.

pub fn raw(&mut self, data: &[u8]) -> void!Error

`Encoder.finish`

Function · Source

pub fn finish(&mut self) -> usize!Error

`KEY_INDEX_WORDS`

Constant · Source

Scratch words per simultaneously live object member for parse_indexed.

pub const KEY_INDEX_WORDS: usize = 5

`Field`

Struct · Source

Ownership-preserving projection for derived decoders. Taking a Value by value transfers its input borrow, rather than borrowing a stack-local view. Both returned views retain exactly that original input dependency.

pub struct Field {
    pub rest: Value
    pub value: Value
}

`OptionalField`

Struct · Source

pub struct OptionalField {
    pub rest: Value
    pub value: Option<Value>
}

`ObjectCursor`

Struct · Source

Consuming object traversal transfers the source borrow to each field and the remaining cursor. Retained fields never borrow the cursor itself.

pub struct ObjectCursor {
    // Private implementation fields omitted.
}

`ObjectCursor.new`

Function · Source

pub fn new(source: Value) -> ObjectCursor!Error from(source)

`ObjectCursor.has_next`

Function · Source

pub fn has_next(&self) -> bool

`ObjectCursor.position`

Function · Source

pub fn position(&self) -> usize

`ObjectCursor.take`

Function · Source

pub fn take(self) -> ObjectField!Error from(self)

`ObjectField`

Struct · Source

pub struct ObjectField {
    pub rest: ObjectCursor
    pub key: String
    pub hash: u32
    pub value: Value
}

`ArrayCursor`

Struct · Source

A consuming cursor lets decoded children retain the original input borrow while subsequent elements are extracted. Each take scans only the next value.

pub struct ArrayCursor {
    // Private implementation fields omitted.
}

`ArrayCursor.new`

Function · Source

pub fn new(source: Value) -> ArrayCursor!Error from(source)

`ArrayCursor.take`

Function · Source

pub fn take(self) -> ArrayElement!Error from(self)

`ArrayCursor.finish`

Function · Source

pub fn finish(self) -> void!Error

`ArrayElement`

Struct · Source

pub struct ArrayElement {
    pub rest: ArrayCursor
    pub value: Value
}

`take_field`

Function · Source

pub fn take_field(source: Value, name: &str) -> Field!Error from(source)

`take_optional_field`

Function · Source

pub fn take_optional_field(source: Value, name: &str) -> OptionalField!Error from(source)

`take_element`

Function · Source

pub fn take_element(source: Value, index: usize) -> Field!Error from(source)

`MAX_DEPTH`

Constant · Source

pub const MAX_DEPTH: usize = 128

`Kind`

Enum · Source

pub enum Kind {
    Null, Bool, Number, String, Array, Object
}

`ErrorKind`

Enum · Source

pub enum ErrorKind {
    Syntax, TypeMismatch, MissingField, DuplicateField, UnknownField,
    NumberRange, BufferFull, Io, Depth, TrailingData, EscapedString
}

`Error`

Struct · Source

pub struct Error {
    pub kind: ErrorKind
    pub position: usize
}

`Error.clone`

Function · Source

pub fn clone(&self) -> Error

`Error.format`

Function · Source

pub fn format<F>(&self, output: &mut F) -> void!io.Error

`failure`

Function · Source

pub fn failure(kind: ErrorKind, position: usize) -> Error

`Value`

Struct · Source

An immutable view of one completely validated JSON value. Number spellings are retained exactly and conversion is explicit, so parsing never loses bits.

pub struct Value {
    // Private implementation fields omitted.
}

`Value.kind`

Function · Source

pub fn kind(&self) -> Kind

`Value.position`

Function · Source

pub fn position(&self) -> usize

`Value.raw`

Function · Source

pub fn raw(&self) -> &[u8] from(self)

`Value.is_null`

Function · Source

pub fn is_null(&self) -> bool

`Value.pointer`

Function · Source

RFC 6901 JSON Pointer, not the URI-fragment representation. Syntax errors point into path; lookup/type errors point into the JSON source document.

pub fn pointer(&self, path: &str) -> Value!Error from(self)

`Value.decode_json`

Function · Source

pub fn decode_json(value: Value) -> Value!Error from(value)

`Value.encode_json`

Function · Source

pub fn encode_json<W>(&self, encoder: &mut Encoder<W>) -> void!Error

`Value.require_object`

Function · Source

pub fn require_object(&self) -> void!Error

`Value.check_fields`

Function · Source

pub fn check_fields(&self, keys: &[&str], deny_unknown: bool) -> void!Error

`Value.len`

Function · Source

pub fn len(&self) -> usize!Error

`Value.as_bool`

Function · Source

pub fn as_bool(&self) -> bool!Error

`Value.as_i64`

Function · Source

pub fn as_i64(&self) -> i64!Error

`Value.as_u64`

Function · Source

pub fn as_u64(&self) -> u64!Error

`Value.as_f64`

Function · Source

pub fn as_f64(&self) -> f64!Error

`Value.as_string`

Function · Source

pub fn as_string(&self) -> String!Error from(self)

`Value.into_raw`

Function · Source

Consuming conversions preserve the input borrow without tying the result to a temporary Value wrapper. Codecs use these when returning structures.

pub fn into_raw(self) -> &[u8] from(self)

`Value.into_string`

Function · Source

pub fn into_string(self) -> String!Error from(self)

`Value.into_str`

Function · Source

pub fn into_str(self) -> &str!Error from(self)

`Value.as_str`

Function · Source

pub fn as_str(&self) -> &str!Error from(self)

`Value.get`

Function · Source

pub fn get(&self, key: &str) -> Option<Value> from(self)

`Value.require`

Function · Source

pub fn require(&self, key: &str) -> Value!Error from(self)

`Value.at`

Function · Source

pub fn at(&self, index: usize) -> Option<Value> from(self)

`Value.array`

Function · Source

pub fn array(&self) -> Array!Error from(self)

`Value.object`

Function · Source

pub fn object(&self) -> Object!Error from(self)

`String`

Struct · Source

JSON string content, without surrounding quotes. This view stores escapes without allocation; equality compares decoded content and decode uses storage supplied by the caller. Unescaped content is already valid UTF-8, so byte comparison and copying suffice. from_str represents decoded UTF-8 content.

pub struct String {
    // Private implementation fields omitted.
}

`String.from_str`

Function · Source

pub fn from_str(value: &str) -> String from(value)

`String.decode_json`

Function · Source

pub fn decode_json(value: Value) -> String!Error from(value)

`String.encode_json`

Function · Source

pub fn encode_json<W>(&self, encoder: &mut Encoder<W>) -> void!Error

`String.raw`

Function · Source

pub fn raw(&self) -> &[u8] from(self)

`String.is_escaped`

Function · Source

pub fn is_escaped(&self) -> bool

`String.into_str`

Function · Source

pub fn into_str(self) -> &str!Error from(self)

`String.as_str`

Function · Source

pub fn as_str(&self) -> &str!Error from(self)

`String.equals`

Function · Source

pub fn equals(&self, other: &str) -> bool

`String.equal`

Function · Source

pub fn equal(&self, other: &String) -> bool

`String.decoded_len`

Function · Source

pub fn decoded_len(&self) -> usize

`String.decode`

Function · Source

Capacity is checked before any writes. Returned text borrows destination, so the source JSON can be released as soon as decoding completes.

pub fn decode(&self, destination: &mut[u8]) -> &str!Error from(destination)

`Array`

Struct · Source

pub struct Array {
    // Private implementation fields omitted.
}

`Array.next`

Function · Source

pub fn next(&mut self) -> Option<Value> from(self)

`Entry`

Struct · Source

pub struct Entry {
    pub key: String
    pub value: Value
}

`Object`

Struct · Source

pub struct Object {
    // Private implementation fields omitted.
}

`Object.next`

Function · Source

pub fn next(&mut self) -> Option<Entry> from(self)

`parse`

Function · Source

Strict RFC 8259 document: exactly one value, valid Unicode scalar strings, no duplicate object names after escape decoding, and at most 128 containers. No allocator or operating-system services are required. Duplicate detection uses quadratic time in each object’s member count and constant extra memory.

pub fn parse(input: &[u8]) -> Value!Error from(input)

`parse_str`

Function · Source

pub fn parse_str(input: &str) -> Value!Error from(input)

`parse_indexed`

Function · Source

Strict parsing with a caller-owned key index. One live object member needs KEY_INDEX_WORDS scratch words; completed objects release their entries. Scratch is reset on every call, including after failures. Insufficient space returns BufferFull at the new key’s opening quote. The result borrows only input, so scratch can be reused immediately while the Value remains live.

pub fn parse_indexed(input: &[u8], scratch: &mut[usize]) -> Value!Error from(input)

`parse_str_indexed`

Function · Source

pub fn parse_str_indexed(input: &str, scratch: &mut[usize]) -> Value!Error from(input)

`Decoder`

Struct · Source

A cursor over whitespace-separated JSON documents, including NDJSON. This borrows an existing input buffer; it does not buffer an external reader. A failed document does not advance the cursor, and subsequent calls return the same error. Values borrow the decoder and prevent advancing while live.

pub struct Decoder {
    // Private implementation fields omitted.
}

`Decoder.new`

Function · Source

pub fn new(input: &[u8]) -> Decoder from(input)

`Decoder.from_str`

Function · Source

pub fn from_str(input: &str) -> Decoder from(input)

`Decoder.position`

Function · Source

pub fn position(&self) -> usize

`Decoder.next`

Function · Source

pub fn next(&mut self) -> Option<Value>!Error from(self)