Struct Document 

pub struct Document { /* private fields */ }

An ordered collection of named fields — the record a store holds.

A document maps String keys to Values and preserves the order in which fields were first inserted. Lookups are a linear scan, which is the fastest strategy for the small field counts typical of documents: it keeps the keys contiguous in memory and avoids the hashing and pointer-chasing overhead a map would add at this size.

Examples

use bison_db::Document;

let mut user = Document::new();
user.set("name", "ada").set("born", 1815_i64);

assert_eq!(user.len(), 2);
assert_eq!(user.get("name").and_then(|v| v.as_str()), Some("ada"));

Implementations

impl Document

pub const fn new() -> Self

Creates an empty document.

Examples

use bison_db::Document;
let doc = Document::new();
assert!(doc.is_empty());

pub fn with_capacity(capacity: usize) -> Self

Creates an empty document with room for capacity fields before it needs to reallocate.

Use this when the field count is known up front to avoid intermediate growth allocations.

Examples

use bison_db::Document;
let doc = Document::with_capacity(4);
assert!(doc.is_empty());

pub fn set<K, V>(&mut self, key: K, value: V) -> &mut Self

where K: Into<String>, V: Into<Value>,

Sets key to value, returning &mut self so calls can be chained.

If key is already present its value is replaced in place, preserving the field’s original position. Otherwise the field is appended.

Examples

use bison_db::Document;
let mut doc = Document::new();
doc.set("a", 1_i64).set("b", 2_i64).set("a", 3_i64);
// "a" keeps its leading position but takes the new value.
assert_eq!(doc.keys().collect::<Vec<_>>(), ["a", "b"]);
assert_eq!(doc.get("a").and_then(|v| v.as_int()), Some(3));

pub fn get(&self, key: &str) -> Option<&Value>

Returns a reference to the value for key, or None if absent.

Examples

use bison_db::Document;
let mut doc = Document::new();
doc.set("k", "v");
assert_eq!(doc.get("k").and_then(|v| v.as_str()), Some("v"));
assert!(doc.get("missing").is_none());

pub fn get_mut(&mut self, key: &str) -> Option<&mut Value>

Returns a mutable reference to the value for key, or None if absent.

Examples

use bison_db::{Document, Value};
let mut doc = Document::new();
doc.set("n", 1_i64);
if let Some(Value::Int(n)) = doc.get_mut("n") {
    *n += 41;
}
assert_eq!(doc.get("n").and_then(|v| v.as_int()), Some(42));

pub fn contains_key(&self, key: &str) -> bool

Returns true if key is present.

Examples

use bison_db::Document;
let mut doc = Document::new();
doc.set("k", 1_i64);
assert!(doc.contains_key("k"));
assert!(!doc.contains_key("other"));

pub fn remove(&mut self, key: &str) -> Option<Value>

Removes key, returning its value if it was present.

Remaining fields keep their relative order.

Examples

use bison_db::Document;
let mut doc = Document::new();
doc.set("a", 1_i64).set("b", 2_i64);
assert_eq!(doc.remove("a").and_then(|v| v.as_int()), Some(1));
assert!(!doc.contains_key("a"));
assert_eq!(doc.keys().collect::<Vec<_>>(), ["b"]);

pub fn len(&self) -> usize

Returns the number of fields.

Examples

use bison_db::Document;
let mut doc = Document::new();
doc.set("a", 1_i64);
assert_eq!(doc.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the document has no fields.

Examples

use bison_db::Document;
assert!(Document::new().is_empty());

pub fn clear(&mut self)

Removes all fields, keeping the allocated capacity for reuse.

Examples

use bison_db::Document;
let mut doc = Document::new();
doc.set("a", 1_i64);
doc.clear();
assert!(doc.is_empty());

pub fn iter(&self) -> impl Iterator<Item = (&str, &Value)>

Returns an iterator over the fields as (&str, &Value) pairs, in order.

Examples

use bison_db::Document;
let mut doc = Document::new();
doc.set("a", 1_i64).set("b", 2_i64);
let collected: Vec<_> = doc.iter().map(|(k, _)| k).collect();
assert_eq!(collected, ["a", "b"]);

pub fn keys(&self) -> impl Iterator<Item = &str>

Returns an iterator over the field keys, in order.

Examples

use bison_db::Document;
let mut doc = Document::new();
doc.set("x", 1_i64);
assert_eq!(doc.keys().collect::<Vec<_>>(), ["x"]);

pub fn values(&self) -> impl Iterator<Item = &Value>

Returns an iterator over the field values, in order.

Examples

use bison_db::Document;
let mut doc = Document::new();
doc.set("x", 9_i64);
assert_eq!(doc.values().filter_map(|v| v.as_int()).sum::<i64>(), 9);

Trait Implementations

impl Clone for Document

fn clone(&self) -> Document

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Document

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

Formats the value using the given formatter.

impl Default for Document

fn default() -> Document

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Document

Available on crate feature serde only.

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl From<Document> for Value

fn from(v: Document) -> Self

Converts to this type from the input type.

impl<K, V> FromIterator<(K, V)> for Document

where K: Into<String>, V: Into<Value>,

fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self

Builds a document from key/value pairs. Later duplicates overwrite earlier ones, matching Document::set.

Examples

use bison_db::{Document, Value};
let doc: Document = [("a", 1_i64), ("b", 2_i64)].into_iter().collect();
assert_eq!(doc.len(), 2);

impl<'a> IntoIterator for &'a Document

type Item = (&'a str, &'a Value)

The type of the elements being iterated over.

type IntoIter = Map<Iter<'a, (String, Value)>, fn(&'a (String, Value)) -> (&'a str, &'a Value)>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Document

fn eq(&self, other: &Document) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Document

Available on crate feature serde only.

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Document