Struct bson::raw::RawDocumentBuf

pub struct RawDocumentBuf { /* private fields */ }

An owned BSON document (akin to std::path::PathBuf), backed by a buffer of raw BSON bytes. This can be created from a Vec<u8> or a crate::Document.

Accessing elements within a RawDocumentBuf is similar to element access in crate::Document, but because the contents are parsed during iteration instead of at creation time, format errors can happen at any time during use.

Iterating over a RawDocumentBuf yields either an error or a key-value pair that borrows from the original document without making any additional allocations.

use bson::raw::RawDocumentBuf;

let doc = RawDocumentBuf::from_bytes(b"\x13\x00\x00\x00\x02hi\x00\x06\x00\x00\x00y'all\x00\x00".to_vec())?;
let mut iter = doc.iter();
let (key, value) = iter.next().unwrap()?;
assert_eq!(key, "hi");
assert_eq!(value.as_str(), Some("y'all"));
assert!(iter.next().is_none());

This type implements Deref to RawDocument, meaning that all methods on RawDocument are available on RawDocumentBuf values as well. This includes RawDocument::get or any of the type-specific getters, such as RawDocument::get_object_id or RawDocument::get_str. Note that accessing elements is an O(N) operation, as it requires iterating through the document from the beginning to find the requested key.

use bson::raw::RawDocumentBuf;

let doc = RawDocumentBuf::from_bytes(b"\x13\x00\x00\x00\x02hi\x00\x06\x00\x00\x00y'all\x00\x00".to_vec())?;
assert_eq!(doc.get_str("hi")?, "y'all");

Implementations

impl RawDocumentBuf

pub fn new() -> RawDocumentBuf

Creates a new, empty RawDocumentBuf.

pub fn from_bytes(data: Vec<u8>) -> Result<RawDocumentBuf>

Constructs a new RawDocumentBuf, validating only the following invariants:

• data is at least five bytes long (the minimum for a valid BSON document)
• the initial four bytes of data accurately represent the length of the bytes as required by the BSON spec.
• the last byte of data is a 0

Note that the internal structure of the bytes representing the BSON elements is not validated at all by this method. If the bytes do not conform to the BSON spec, then method calls on the RawDocument will return Errors where appropriate.

let doc = RawDocumentBuf::from_bytes(b"\x05\0\0\0\0".to_vec())?;

pub fn from_document(doc: &Document) -> Result<RawDocumentBuf>

Create a RawDocumentBuf from a Document.

use bson::{doc, oid::ObjectId, raw::RawDocumentBuf};

let document = doc! {
    "_id": ObjectId::new(),
    "name": "Herman Melville",
    "title": "Moby-Dick",
};
let doc = RawDocumentBuf::from_document(&document)?;

pub fn iter(&self) -> Iter<'_>

Gets an iterator over the elements in the RawDocumentBuf, which yields Result<(&str, RawBson<'_>)>.

use bson::{doc, raw::RawDocumentBuf};

let doc = RawDocumentBuf::from_document(&doc! { "ferris": true })?;

for element in doc.iter() {
    let (key, value) = element?;
    assert_eq!(key, "ferris");
    assert_eq!(value.as_bool(), Some(true));
}

Note:

There is no owning iterator for RawDocumentBuf. If you need ownership over elements that might need to allocate, you must explicitly convert them to owned types yourself.

pub fn iter_elements(&self) -> RawIter<'_>

Gets an iterator over the elements in the RawDocumentBuf, which yields Result<RawElement<'_>> values. These hold a reference to the underlying document but do not explicitly resolve the values.

This iterator, which underpins the implementation of the default iterator, produces RawElement objects that hold a view onto the document but do not parse out or construct values until the .value() or .try_into() methods are called.

Note:

There is no owning iterator for RawDocumentBuf. If you need ownership over elements that might need to allocate, you must explicitly convert them to owned types yourself.

pub fn into_bytes(self) -> Vec<u8>

Return the contained data as a Vec<u8>

use bson::{doc, raw::RawDocumentBuf};

let doc = RawDocumentBuf::from_document(&doc!{})?;
assert_eq!(doc.into_bytes(), b"\x05\x00\x00\x00\x00".to_vec());

pub fn append(&mut self, key: impl AsRef<str>, value: impl Into<RawBson>)

Append a key value pair to the end of the document without checking to see if the key already exists.

It is a user error to append the same key more than once to the same document, and it may result in errors when communicating with MongoDB.

If the provided key contains an interior null byte, this method will panic.

use bson::{doc, raw::RawDocumentBuf};

let mut doc = RawDocumentBuf::new();
doc.append("a string", "some string");
doc.append("an integer", 12_i32);

let mut subdoc = RawDocumentBuf::new();
subdoc.append("a key", true);
doc.append("a document", subdoc);

let expected = doc! {
    "a string": "some string",
    "an integer": 12_i32,
    "a document": { "a key": true },
};

assert_eq!(doc.to_document()?, expected);

pub fn append_ref<'a>( &mut self, key: impl AsRef<str>, value: impl Into<RawBsonRef<'a>> )

Append a key value pair to the end of the document without checking to see if the key already exists.

It is a user error to append the same key more than once to the same document, and it may result in errors when communicating with MongoDB.

If the provided key contains an interior null byte, this method will panic.

pub fn to_document(&self) -> Result<Document>

Convert this RawDocumentBuf to a Document, returning an error if invalid BSON is encountered.

Methods from Deref<Target = RawDocument>

pub fn to_raw_document_buf(&self) -> RawDocumentBuf

Creates a new RawDocumentBuf with an owned copy of the BSON bytes.

use bson::raw::{RawDocument, RawDocumentBuf, Error};

let data = b"\x05\0\0\0\0";
let doc_ref = RawDocument::from_bytes(data)?;
let doc: RawDocumentBuf = doc_ref.to_raw_document_buf();

pub fn get(&self, key: impl AsRef<str>) -> Result<Option<RawBsonRef<'_>>>

Gets a reference to the value corresponding to the given key by iterating until the key is found.

use bson::{rawdoc, oid::ObjectId};

let doc = rawdoc! {
    "_id": ObjectId::new(),
    "f64": 2.5,
};

let element = doc.get("f64")?.expect("finding key f64");
assert_eq!(element.as_f64(), Some(2.5));
assert!(doc.get("unknown")?.is_none());

pub fn iter(&self) -> Iter<'_>

Gets an iterator over the elements in the RawDocument that yields Result<(&str, RawBson<'_>)>.

pub fn iter_elements(&self) -> RawIter<'_>

Gets an iterator over the elements in the RawDocument, which yields Result<RawElement<'_>> values. These hold a reference to the underlying document but do not explicitly resolve the values.

This iterator, which underpins the implementation of the default iterator, produces RawElement objects that hold a view onto the document but do not parse out or construct values until the .value() or .try_into() methods are called.

pub fn get_f64(&self, key: impl AsRef<str>) -> ValueAccessResult<f64>

Gets a reference to the BSON double value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a double.

use bson::raw::ValueAccessErrorKind;
use bson::rawdoc;

let doc = rawdoc! {
    "bool": true,
    "f64": 2.5,
};

assert_eq!(doc.get_f64("f64")?, 2.5);
assert!(matches!(doc.get_f64("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_f64("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_str(&self, key: impl AsRef<str>) -> ValueAccessResult<&str>

Gets a reference to the string value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a string.

use bson::{rawdoc, raw::ValueAccessErrorKind};

let doc = rawdoc! {
    "string": "hello",
    "bool": true,
};

assert_eq!(doc.get_str("string")?, "hello");
assert!(matches!(doc.get_str("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_str("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_document( &self, key: impl AsRef<str> ) -> ValueAccessResult<&RawDocument>

Gets a reference to the document value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a document.

use bson::{rawdoc, raw::ValueAccessErrorKind};

let doc = rawdoc! {
    "doc": { "key": "value"},
    "bool": true,
};

assert_eq!(doc.get_document("doc")?.get_str("key")?, "value");
assert!(matches!(doc.get_document("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_document("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_array(&self, key: impl AsRef<str>) -> ValueAccessResult<&RawArray>

Gets a reference to the array value corresponding to a given key or returns an error if the key corresponds to a value which isn’t an array.

use bson::{rawdoc, raw::ValueAccessErrorKind};

let doc = rawdoc! {
    "array": [true, 3],
    "bool": true,
};

let mut arr_iter = doc.get_array("array")?.into_iter();
let _: bool = arr_iter.next().unwrap()?.as_bool().unwrap();
let _: i32 = arr_iter.next().unwrap()?.as_i32().unwrap();

assert!(arr_iter.next().is_none());
assert!(doc.get_array("bool").is_err());
assert!(matches!(doc.get_array("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_binary( &self, key: impl AsRef<str> ) -> ValueAccessResult<RawBinaryRef<'_>>

Gets a reference to the BSON binary value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a binary value.

use bson::{
    rawdoc,
    raw::ValueAccessErrorKind,
    spec::BinarySubtype,
    Binary,
};

let doc = rawdoc! {
    "binary": Binary { subtype: BinarySubtype::Generic, bytes: vec![1, 2, 3] },
    "bool": true,
};

assert_eq!(&doc.get_binary("binary")?.bytes, &[1, 2, 3]);
assert!(matches!(doc.get_binary("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_binary("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_object_id(&self, key: impl AsRef<str>) -> ValueAccessResult<ObjectId>

Gets a reference to the ObjectId value corresponding to a given key or returns an error if the key corresponds to a value which isn’t an ObjectId.

use bson::{rawdoc, oid::ObjectId, raw::ValueAccessErrorKind};

let doc = rawdoc! {
    "_id": ObjectId::new(),
    "bool": true,
};

let oid = doc.get_object_id("_id")?;
assert!(matches!(doc.get_object_id("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_object_id("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_bool(&self, key: impl AsRef<str>) -> ValueAccessResult<bool>

Gets a reference to the boolean value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a boolean.

use bson::{rawdoc, oid::ObjectId, raw::ValueAccessErrorKind};

let doc = rawdoc! {
    "_id": ObjectId::new(),
    "bool": true,
};

assert!(doc.get_bool("bool")?);
assert!(matches!(doc.get_bool("_id").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_bool("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_datetime(&self, key: impl AsRef<str>) -> ValueAccessResult<DateTime>

Gets a reference to the BSON DateTime value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a DateTime.

use bson::{rawdoc, raw::ValueAccessErrorKind, DateTime};

let dt = DateTime::now();
let doc = rawdoc! {
    "created_at": dt,
    "bool": true,
};

assert_eq!(doc.get_datetime("created_at")?, dt);
assert!(matches!(doc.get_datetime("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_datetime("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_regex( &self, key: impl AsRef<str> ) -> ValueAccessResult<RawRegexRef<'_>>

Gets a reference to the BSON regex value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a regex.

use bson::{rawdoc, Regex, raw::ValueAccessErrorKind};

let doc = rawdoc! {
    "regex": Regex {
        pattern: r"end\s*$".into(),
        options: "i".into(),
    },
    "bool": true,
};

assert_eq!(doc.get_regex("regex")?.pattern, r"end\s*$");
assert_eq!(doc.get_regex("regex")?.options, "i");
assert!(matches!(doc.get_regex("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_regex("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_timestamp( &self, key: impl AsRef<str> ) -> ValueAccessResult<Timestamp>

Gets a reference to the BSON timestamp value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a timestamp.

use bson::{rawdoc, Timestamp, raw::ValueAccessErrorKind};

let doc = rawdoc! {
    "bool": true,
    "ts": Timestamp { time: 649876543, increment: 9 },
};

let timestamp = doc.get_timestamp("ts")?;

assert_eq!(timestamp.time, 649876543);
assert_eq!(timestamp.increment, 9);
assert!(matches!(doc.get_timestamp("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_timestamp("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_i32(&self, key: impl AsRef<str>) -> ValueAccessResult<i32>

Gets a reference to the BSON int32 value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a 32-bit integer.

use bson::{rawdoc, raw::ValueAccessErrorKind};

let doc = rawdoc! {
    "bool": true,
    "i32": 1_000_000,
};

assert_eq!(doc.get_i32("i32")?, 1_000_000);
assert!(matches!(doc.get_i32("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { ..}));
assert!(matches!(doc.get_i32("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn get_i64(&self, key: impl AsRef<str>) -> ValueAccessResult<i64>

Gets a reference to the BSON int64 value corresponding to a given key or returns an error if the key corresponds to a value which isn’t a 64-bit integer.

use bson::{rawdoc, raw::ValueAccessErrorKind};

let doc = rawdoc! {
    "bool": true,
    "i64": 9223372036854775807_i64,
};

assert_eq!(doc.get_i64("i64")?, 9223372036854775807);
assert!(matches!(doc.get_i64("bool").unwrap_err().kind, ValueAccessErrorKind::UnexpectedType { .. }));
assert!(matches!(doc.get_i64("unknown").unwrap_err().kind, ValueAccessErrorKind::NotPresent));

pub fn as_bytes(&self) -> &[u8]

Return a reference to the contained data as a &[u8]

use bson::rawdoc;
let docbuf = rawdoc! {};
assert_eq!(docbuf.as_bytes(), b"\x05\x00\x00\x00\x00");

pub fn is_empty(&self) -> bool

Returns whether this document contains any elements or not.

Trait Implementations

impl AsRef<RawDocument> for RawDocumentBuf

fn as_ref(&self) -> &RawDocument

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<RawDocument> for RawDocumentBuf

fn borrow(&self) -> &RawDocument

Immutably borrows from an owned value.

impl Clone for RawDocumentBuf

fn clone(&self) -> RawDocumentBuf

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for RawDocumentBuf

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

Formats the value using the given formatter.

impl Default for RawDocumentBuf

fn default() -> Self

Returns the “default value” for a type.

impl Deref for RawDocumentBuf

type Target = RawDocument

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'de> Deserialize<'de> for RawDocumentBuf

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'a> From<&'a RawDocumentBuf> for Cow<'a, RawDocument>

fn from(rd: &'a RawDocumentBuf) -> Self

Converts to this type from the input type.

impl<'a> From<&'a RawDocumentBuf> for RawBsonRef<'a>

fn from(d: &'a RawDocumentBuf) -> Self

Converts to this type from the input type.

impl<'a> From<RawDocumentBuf> for Cow<'a, RawDocument>

fn from(rd: RawDocumentBuf) -> Self

Converts to this type from the input type.

impl From<RawDocumentBuf> for RawBson

fn from(d: RawDocumentBuf) -> Self

Converts to this type from the input type.

impl<S: AsRef<str>, T: Into<RawBson>> FromIterator<(S, T)> for RawDocumentBuf

fn from_iter<I: IntoIterator<Item = (S, T)>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> IntoIterator for &'a RawDocumentBuf

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

type Item = Result<(&'a str, RawBsonRef<'a>), Error>

The type of the elements being iterated over.

fn into_iter(self) -> Iter<'a>

Creates an iterator from a value.

impl PartialEq for RawDocumentBuf

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl Serialize for RawDocumentBuf

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&Document> for RawDocumentBuf

type Error = Error

The type returned in the event of a conversion error.

fn try_from(doc: &Document) -> Result<RawDocumentBuf>

Performs the conversion.

impl TryFrom<RawDocumentBuf> for Document

type Error = Error

The type returned in the event of a conversion error.

fn try_from(raw: RawDocumentBuf) -> Result<Document>

Performs the conversion.

impl StructuralPartialEq for RawDocumentBuf