Struct Value 

pub struct Value<'a> { /* private fields */ }

A value, borrowed from the bytes it is stored in.

The slice starts at the value’s header and may run past its end, which is what makes a child free: it is the parent’s slice from the child’s offset, with no length to compute. Use Value::encoded_len when the exact end matters, which is when the value is being copied somewhere else.

Implementations

impl<'a> Value<'a>

pub fn path(&self, path: &str) -> Result<Option<Value<'a>>>

The value at path, if there is one there.

Ok(None) is a path that is well formed and names nothing, which is a normal answer and not a failure. Err is a path that does not parse.

pub fn path_bytes(&self, path: &[u8]) -> Result<Option<Value<'a>>>

Value::path over bytes, for the RESP side where a path arrives as a bulk string.

pub fn step(&self, step: Step<'_>) -> Option<Value<'a>>

One step down from here.

impl<'a> Value<'a>

pub fn new(bytes: &'a [u8]) -> Option<Value<'a>>

A value over bytes, if the header at the front is one this version understands and its payload is there.

This is a header check and not a walk. It is what a read does, because a read touches one path and checking the whole document to answer one field would cost more than the read. Value::validate is the walk, for the caller that is about to trust the whole thing.

pub fn kind(&self) -> Kind

What this value is.

pub fn is_null(&self) -> bool

Whether this is null.

pub fn as_bool(&self) -> Option<bool>

The boolean this holds, if it holds one.

pub fn as_int(&self) -> Option<i64>

The integer this holds, if it holds one.

The payload is as narrow as the number allows, so a document full of small numbers costs five bytes each rather than twelve, and reading one back is a sign extending load of one, two, four or eight bytes.

pub fn as_float(&self) -> Option<f64>

The float this holds, if it holds one.

pub fn as_text(&self) -> Option<&'a str>

The string this holds, if it holds one and it is UTF-8.

pub fn text_bytes(&self) -> Option<&'a [u8]>

The string this holds as it is stored, without the UTF-8 check.

A string written through this crate is UTF-8 by construction, so the check only ever catches a damaged file. A caller that is going to hand the bytes straight back out over RESP does not need it.

pub fn len(&self) -> usize

How many elements a container holds. Zero for anything else.

pub fn is_empty(&self) -> bool

Whether this is a container with nothing in it.

A scalar is not empty, it is not a container, so this is false for one.

pub fn is_interned(&self) -> bool

Whether this object’s keys are ids from a collection’s intern table rather than bytes stored with the document.

Nothing else about reading changes, except that a lookup is by id and getting a key’s name back needs the table.

pub fn at(&self, i: usize) -> Option<Value<'a>>

The value of element i, counting in the container’s own order.

For an array that is the order the elements were written in. For an object it is key order, which is not the order the document was written in, and it is the order Value::members walks.

pub fn key_at(&self, i: usize) -> Option<&'a [u8]>

The key of member i of an object, if the object stores its keys as bytes.

pub fn key_id_at(&self, i: usize) -> Option<u16>

The intern table id of member i of an object, if the object stores its keys as ids.

pub fn get(&self, key: &[u8]) -> Option<Value<'a>>

The value stored under key, by binary search over the entry table.

Keys are ordered by length and then by bytes, so the search compares a length before it compares anything else and most steps never touch the key region at all. This is the lookup G15 is about: for a document whose keys are interned it is not even this, it is Value::get_id.

pub fn find(&self, key: &[u8]) -> Option<usize>

The index of key among this object’s members.

pub fn get_id(&self, id: u16) -> Option<Value<'a>>

The value stored under intern table id id.

pub fn find_id(&self, id: u16) -> Option<usize>

The index of intern table id id among this object’s members.

pub fn iter(&self) -> Elems<'a>

Every element of a container, in the container’s own order.

pub fn members(&self) -> Members<'a>

Every member of an object, key first, in key order.

An interned object yields nothing here, because the names are not in the document. Walk it with Value::key_id_at and Value::at.

pub fn encoded_len(&self) -> Option<usize>

How many bytes this value occupies, header included.

A container works this out from its last element, which recurses down the right hand edge of the document and so costs one step per level rather than one per element. That is the price of not spending four bytes a container on a length nothing else needs.

pub fn offset_in(&self, root: &Value<'_>) -> Option<usize>

Where this value begins inside root, in bytes.

A child is its parent’s slice from the child’s offset, so the offset is still there to be read back off the slice itself and nothing has to be carried alongside it. This is how a write identifies the places a path matched: Path::select answers values, and a value plus the document it came out of is an offset, which is what edit takes.

None if this value did not come out of root.

pub fn as_bytes(&self) -> Option<&'a [u8]>

This value’s bytes and nothing after them.

pub fn validate(&self) -> bool

Walk the whole value and check that every part of it is there.

This is what a caller runs over bytes it did not write: a record read back from a file that failed its checksum in an interesting way, or a document handed in over a socket. Everything it checks, the accessors also check one at a time, so a document that fails here still cannot make a read panic. It is O(the document).

impl Value<'_>

pub fn to_json(&self) -> Result<Vec<u8>>

This value as JSON text, on one line.

pub fn write_json(&self, out: &mut Vec<u8>) -> Result<()>

This value as JSON text, appended to a buffer the caller owns.

The reply path has one of those per connection, so a JSON.GET over a thousand keys is one buffer rather than a thousand.

pub fn write_json_with(&self, f: &Format<'_>, out: &mut Vec<u8>) -> Result<()>

The same, laid out the way f asks for.

pub fn write_json_at( &self, f: &Format<'_>, out: &mut Vec<u8>, depth: usize, ) -> Result<()>

The same again, as if this value were already depth levels down.

JSON.GET wraps what a JSONPath matched in an array and wraps several paths in an object keyed by the paths, and it lays those wrappers out too, so the values inside them start one or two levels in rather than at the margin. The wrapper is built by the caller, which is the only thing that knows how deep it went.

Trait Implementations

impl<'a> Clone for Value<'a>

fn clone(&self) -> Value<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for Value<'a>

impl Debug for Value<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.