Struct jupiter::ig::docs::Element

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

Provides a node or leaf within the information graph.

Note that this is mainly a pointer into a Doc therefore it can be copied quite cheaply.

Implementations

impl<'a> Element<'a>

Represents a node or leaf of the information graph.

This could be either an inner object, a list, an int, a bool or a string. Note that the element itself is just a pointer into the graph and can therefore be copied. However, its lifetime depends of the Doc it references.

pub fn query(self, query: impl AsRef<str>) -> Element<'a>

Executes an ad-hoc query on this element.

See Doc::compile for a description of the query syntax.

Note that a query can be executed on any element but will only ever yield a non empty result if it is executed on an object.

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 result = doc.root().query("Foo.Bar");

assert_eq!(result.as_int().unwrap(), 42)

pub fn is_empty(&self) -> bool

Determines if this element is empty.

Such elements are e.g. returned if a query doesn’t match or if an out of range index is used when accessing a list.

Example

let doc = Doc::empty();

assert_eq!(doc.root().is_empty(), true);
assert_eq!(doc.root().query("unknown").is_empty(), true);
assert_eq!(doc.root().at(100).is_empty(), true);

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

Returns the string represented by this element.

Note that this will only return a string if the underlying data is one. No other element will be converted into a string, as this is handled by `to_string’.

Example

let builder = DocBuilder::new();
let mut list_builder = builder.list();
list_builder.append_string("Foo");
let doc = builder.build_list(list_builder);

assert_eq!(doc.root().at(0).as_str().unwrap(), "Foo");

pub fn to_str(&self) -> Cow<'_, str>

Returns a string representation of all scalar values.

Returns a string for string, int or bool values. Everything else is represented as “”. Note that Element implements Debug which will also render a representation for lists and objects, but its representation is only for debugging purposes and should not being relied up on.

Example

let builder = DocBuilder::new();
let mut list_builder = builder.list();
list_builder.append_string("Foo");
list_builder.append_bool(true);
list_builder.append_int(42);
let doc = builder.build_list(list_builder);

assert_eq!(doc.root().at(0).to_str().as_ref(), "Foo");
assert_eq!(doc.root().at(1).to_str().as_ref(), "true");
assert_eq!(doc.root().at(2).to_str().as_ref(), "42");

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

Returns the int value represented by this element.

Example

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

let value = doc.root().at(0).as_int().unwrap();

assert_eq!(value, 42);

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

Returns the bool value represented by this element.

Note that this actually represents a tri-state logic by returning an Option<bool>. This helps to distinguish missing values from false. If this isn’t necessarry, as_bool() can be used which treats both cases as false.

Example

let builder = DocBuilder::new();
let mut list_builder = builder.list();
list_builder.append_bool(true);
list_builder.append_bool(false);
list_builder.append_string("true");
list_builder.append_int(1);
let doc = builder.build_list(list_builder);

assert_eq!(doc.root().at(0).try_as_bool().unwrap(), true);
assert_eq!(doc.root().at(1).try_as_bool().unwrap(), false);
assert_eq!(doc.root().at(2).try_as_bool().is_none(), true);
assert_eq!(doc.root().at(3).try_as_bool().is_none(), true);
assert_eq!(doc.root().at(4).try_as_bool().is_none(), true);

pub fn as_bool(&self) -> bool

Returns true if this element wraps an actual bool true or false in all other cases.

Note that try_as_bool() can be used if false needs to be distinguished from missing or non-boolean elements.

Example

let builder = DocBuilder::new();
let mut list_builder = builder.list();
list_builder.append_bool(true);
list_builder.append_bool(false);
list_builder.append_string("true");
list_builder.append_int(1);
let doc = builder.build_list(list_builder);

assert_eq!(doc.root().at(0).as_bool(), true);
assert_eq!(doc.root().at(1).as_bool(), false);
assert_eq!(doc.root().at(2).as_bool(), false);
assert_eq!(doc.root().at(3).as_bool(), false);
assert_eq!(doc.root().at(4).as_bool(), false);

pub fn is_list(&self) -> bool

Determines if this element is a list.

Example

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

assert_eq!(doc.root().is_list(), true);
assert_eq!(doc.root().at(1).is_list(), false);

pub fn is_object(&self) -> bool

Determines if this element is an object.

Example

let builder = DocBuilder::new();
let mut obj_builder = builder.obj();
obj_builder.put_int("test", 1);
let doc = builder.build_object(obj_builder);

assert_eq!(doc.root().is_object(), true);
assert_eq!(doc.root().query("test").is_object(), false);

pub fn len(&self) -> usize

Returns the number of elements in the underlying list or number of entries in the underlying map.

If this element is neither a list nor a map, 0 is returned.

Example

let builder = DocBuilder::new();
let mut list_builder = builder.list();
let mut obj_builder = builder.obj();
obj_builder.put_int("Foo", 42);
list_builder.append_object(obj_builder);
let doc = builder.build_list(list_builder);

assert_eq!(doc.root().len(), 1);
assert_eq!(doc.root().at(0).len(), 1);

assert_eq!(doc.root().at(0).query("Foo").len(), 0);
assert_eq!(doc.root().at(1).len(), 0);

pub fn at(&self, index: usize) -> Element<'a>

Returns the n-th element of the underlying list.

If the underlying element isn’t a list or if the given index is outside of the range of the list, an empty element is returned.

Example

let builder = DocBuilder::new();
let mut list_builder = builder.list();
list_builder.append_string("Foo");
let doc = builder.build_list(list_builder);

assert_eq!(doc.root().at(0).as_str().unwrap(), "Foo");
assert_eq!(doc.root().at(1).is_empty(), true);
assert_eq!(doc.root().at(0).at(1).is_empty(), true);

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

Returns an iterator for all elements of the underlying list.

If the list is empty or if the underlying element isn’t a list, an empty iterator will be returned.

Example

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

assert_eq!(doc.root().iter().map(|e| format!("{}", e.to_str())).join(", "), "1, 2, 3");

assert_eq!(Doc::empty().root().iter().next().is_none(), true);

pub fn entries(self) -> EntryIter<'a>

Returns an iterator over all entries of the underlying map.

If the underlying element isn’t a map, an empty iterator is returned.

Example

let builder = DocBuilder::new();
let mut obj_builder = builder.obj();
obj_builder.put_int("Foo", 42);
obj_builder.put_int("Bar", 24);
let doc = builder.build_object(obj_builder);

let entry_string = doc
                    .root()
                    .entries()
                    .map(|(k, v)| format!("{}: {}", k, v.to_str()))
                    .join(", ");
assert_eq!(entry_string, "Foo: 42, Bar: 24");

Trait Implementations

impl<'a> Clone for Element<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Element<'_>

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

Formats the value using the given formatter.

impl<'a> Copy for Element<'a>