v0.4.0

JsonEventReader structv0.1.0

Source
Reads a document as events, pulling bytes as it needs them.
pub struct JsonEventReader {
    // private fields
}

Constructors

JsonEventReader

pub func JsonEventReader(
    allocator: Allocator,
    source: Reader,
    limits: JsonLimits
) -> JsonEventReader

A reader over source under limits. Terminates the program when its first buffer cannot be allocated, as every owning buffer does.

NameTypeDescription
allocatorAllocatorwhere the storage comes from
sourceReaderthe text to read
limitsJsonLimitsthe bounds the parse refuses to exceed

Returns: a reader positioned before the first event

Source

Methods

Text

pub func Text(&self) -> char8[..]

The text of the event just reported, valid until the next call to Next. For a name, a string or a number. The view points into the reader's buffer, which the next call may refill or grow, so a caller that keeps the text copies it first. Escapes are left as written — resolving them would mean allocating, and a caller skipping past a field should not pay for its contents.

Returns: the current event's text, borrowed from the reader until its next event

Source

TextIsEscaped

pub func TextIsEscaped(&self) -> bool

Whether that text holds escapes a caller must resolve.

Returns: whether the text still holds escape sequences a caller must decode

Source

Depth

pub func Depth(&self) -> uint

How deeply nested the reader currently is.

Returns: how many arrays and objects are currently open

Source

Release

pub func Release(&var self)

Gives the buffer back.

Source

Next

pub func Next(&var self) -> JsonEvent? throws JsonReadError

The next event, or none at the end of the document. Separators are checked and consumed: a caller sees values and structure, not commas and colons, which is the level a streaming reader is useful at. A document that is not JSON throws Malformed with the case and offset the tree parser would report, and a source that fails throws Source with the source's own error; after either, every later call throws the same error again.

Returns: the next event, or none once the top-level value and any whitespace after it have been read

Source

Destructor

func ~JsonEventReader(&var self)

Releases the buffer.

Source

JsonEvent

pub enum JsonEvent: int32 {
    ObjectStart = 1,
    ObjectEnd = 2,
    ArrayStart = 3,
    ArrayEnd = 4,
    Name = 5,
    Text = 6,
    Number = 7,
    True = 8,
    False = 9,
    Null = 10
}

What just happened in the document. The end of the document is none from Next, and a failure is thrown.

Source

Cases

NameValueDescription
ObjectStart1An object opened.
ObjectEnd2An object closed.
ArrayStart3An array opened.
ArrayEnd4An array closed.
Name5A member name; its text is available until the next event.
Text6A string value; its text is available until the next event.
Number7A number; its text is available until the next event.
True8true.
False9false.
Null10null.

JsonReadError

pub variant JsonReadError {
    Malformed(JsonParseError),
    Source(IoError, uint)
}

Why a JsonEventReader stopped before the end of the document.

Source

Cases

NameDescription
Malformed(JsonParseError)The document is not JSON. The failure is positioned at the byte of the document the reader stopped on, with the same cases and offsets the tree parser reports for the same text.
Source(IoError, uint)The source failed with something other than its end, after this many bytes of the document were read.