Struct jupiter::ig::docs::Doc

pub struct Doc { /* private fields */ }

Provides the root node of an information graph.

This essentially bundles the SymbolTable and the root node of the graph.

Note that a Doc cannot be modified once it has been built which permits to use a very efficient memory layout and also permits to cache queries, lookup indices and query results as provided by Table.

Implementations

impl Doc

pub fn empty() -> Self

Creates an entirely empty doc which can be used as a fallback or placeholder.

pub fn new(symbols: SymbolTable, root: Node) -> Self

Creates a new document by combining the given SymbolTable and Node.

Note that this is mainly an internal API as DocBuilder should be used to generate new docs.

pub fn root(&self) -> Element<'_>

Returns the root node of this doc which is either a list or a map.

Example

let builder = DocBuilder::new();
let mut list_builder = builder.list();
list_builder.append_int(1);
let doc = builder.build_list(list_builder);

let root = doc.root();

assert_eq!(root.len(), 1)

pub fn compile(&self, query: impl AsRef<str>) -> Query

Compiles the given query.

A query is composed of a chain of keys separated by “.”. For nested objects, we apply one key after another to obtain the resulting target element.

Note that “.” represents an identity query which returns the element itself.

Example

let builder = DocBuilder::new();
let mut object_builder = builder.obj();
let mut inner_builder = builder.obj();
inner_builder.put_int("Bar", 42).unwrap();
object_builder.put_object("Foo", inner_builder).unwrap();
let doc = builder.build_object(object_builder);

let query = doc.compile("Foo.Bar");
assert_eq!(query.execute(doc.root()).as_int().unwrap(), 42);

let query = doc.compile(".");
assert!(query.execute(doc.root()).is_object());

Performance

Compiling queries is rather fast, therefore ad-hoc queries can be executed using Element::query. Pre-compiled queries are only feasible if a query is known to be executed several times (e.g. when iterating over a list of objects and executing the same query each time).

Also note that if we encounter an unknown symbol here, we know that the query cannot be fulfilled and therefore return an empty query here which always yields and empty result without any actual work being done.

pub fn symbols_mut(&mut self) -> &mut SymbolTable

Provides mutable access on the underlying symbol table.

pub fn symbols(&self) -> &SymbolTable

Provides readonly access on the symbol table.

pub fn allocated_size(&self) -> usize

Estimates the size (in bytes) occupied by this doc.

This accounts for both, the SymbolTable and the actual information graph. Note that this is an approximation as not all data structures reveal their true size.

Example

let builder = DocBuilder::new();
let mut object_builder = builder.obj();
let mut inner_builder = builder.obj();
inner_builder.put_int("Bar", 42).unwrap();
object_builder.put_object("Foo", inner_builder).unwrap();
let doc = builder.build_object(object_builder);

println!("{}", doc.allocated_size());