Reference

std/json/pointer

std/json/src/pointer.trb

JsonPointer (RFC 6901): the address of one value inside a JSON document, as a typed value, and JsonValue.get, which follows it. JSON Patch addresses every operation by a pointer, and a $ref with a fragment is one.

type JsonPointer

type JsonPointer with Show, Equals, Hash

The address of one value in a JSON document: a list of reference tokens, each the name of a member or the index of an array item, read from left to right. The empty list is the root, the whole document.

Two spellings are one pointer. The string form (RFC 6901 section 3) is /foo/0, with ~0 for a ~ and ~1 for a / inside a token; the URI fragment form (section 6) is the same text percent-encoded, to sit behind a #.

Examples

match JsonPointer.parse("/foo/0") {
  Ok(pointer) => {
    print pointer.tokens()
    print pointer.child("bar")
  }
  Fail(problem) => print problem
}

Related

fn root

static fn root(): Self

The root, which names the whole document: its string form is the empty text.

fn parse

static fn parse(text: String): Result<Self, JsonPointerError>

Reads the string form: empty text is the root, anything else starts with / and holds one token per /, where ~0 stands for ~ and ~1 for /.

Errors

A JsonPointerError for text that is neither empty nor starts with /, and for a ~ that is not followed by 0 or 1.

fn parseFragment

static fn parseFragment(text: String): Result<Self, JsonPointerError>

Reads the URI fragment form (RFC 6901 section 6), the text behind the # of a URI: every percent escape is decoded as UTF-8 and the result is read as the string form.

Errors

A JsonPointerError for a % that is not followed by two hexadecimal digits, for escapes that are not UTF-8, and for everything JsonPointer.parse refuses.

fn text

fn text(): String

The string form: /foo/0, with ~ written ~0 and / written ~1 inside a token, and "" for the root.

fn fragment

fn fragment(): String

The URI fragment form: the string form with every byte a fragment cannot hold percent-encoded, without the #.

fn tokens

fn tokens(): List<String>

The reference tokens, unescaped, from the root down; the root has none.

fn child

fn child(token: String): Self

The pointer to the member or item token of the value this one names.

fn parent

fn parent(): Self?

The pointer one level up, and None for the root.

fn last

fn last(): String?

The last token, which is the name or index inside the parent, and None for the root.

fn show

fn show(): String

The string form, as JsonPointer.text.

type JsonPointerProblem

type JsonPointerProblem with Show, Equals, Hash

Why a JsonPointerError was raised.

case Syntax

case Syntax

The text is not a pointer: it neither is empty nor starts with /, or a ~ is not followed by 0 or 1.

case Fragment

case Fragment

The fragment form holds a % without two hexadecimal digits, or escapes that are not UTF-8.

case MissingMember

case MissingMember

The object has no member with that name.

case IndexOutOfRange

case IndexOutOfRange

The array has no item at that index.

case NotAnIndex

case NotAnIndex

The token is applied to an array and is not an index: it has a sign, a leading zero or a character that is no digit.

case EndOfArray

case EndOfArray

The token -, the position after the last item: there is no value there to read.

case NotAContainer

case NotAContainer

The token is applied to a string, a number, a boolean or null, which have no members and no items.

fn show

fn show(): String

The problem as a short phrase.

type JsonPointerError

type JsonPointerError with Show, Equals, Error

What went wrong reading a pointer or following it through a document: the pointer's text, the kind and the detail.

field pointer

pointer: String

The pointer the failure belongs to, as it was written (or, for a pointer that was followed, its string form).

field problem

problem: JsonPointerProblem

What kind of failure this is.

field message

message: String

The failure in words, without the pointer.

fn show

fn show(): String

pointer "/foo/9": no item at index 9.

extend JsonValue

extend JsonValue

Adds get to a document, to read the value a pointer names.

fn get

fn get(pointer: JsonPointer): Result<JsonValue, JsonPointerError>

The value pointer names in this document. A token on an object is a member name; on an array it is a decimal index without a sign or a leading zero.

Errors

A JsonPointerError for a member the object does not have, an index the array does not reach, a token that is no index, the token - (the position after the last item, which holds no value), and a token on a string, number, boolean or null. It names the pointer.