Struct bson::raw::RawDocument

pub struct RawDocument { /* private fields */ }

A slice of a BSON document (akin to std::str). This can be created from a RawDocumentBuf or any type that contains valid BSON data, including static binary literals, Vec<u8>, or arrays.

This is an unsized type, meaning that it must always be used behind a pointer like &. For an owned version of this type, see RawDocumentBuf.

Accessing elements within a RawDocument 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 RawDocument yields either an error or a key-value pair that borrows from the original document without making any additional allocations.

use bson::raw::RawDocument;

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

Individual elements can be accessed using 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::RawDocument;

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

Implementations

impl RawDocument

pub fn from_bytes<D: AsRef<[u8]> + ?Sized>(data: &D) -> Result<&RawDocument>

Constructs a new RawDocument, 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.

use bson::raw::RawDocument;

let doc = RawDocument::from_bytes(b"\x05\0\0\0\0")?;

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 RawDocument

fn as_ref(&self) -> &RawDocument

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

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 Debug for RawDocument

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

Formats the value using the given formatter.

impl<'de: 'a, 'a> Deserialize<'de> for &'a RawDocument

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 RawDocument> for Cow<'a, RawDocument>

fn from(rdr: &'a RawDocument) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl<'a> IntoIterator for &'a RawDocument

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 RawDocument

fn eq(&self, other: &RawDocument) -> 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<'a> Serialize for &'a RawDocument

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl ToOwned for RawDocument

type Owned = RawDocumentBuf

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl TryFrom<&RawDocument> for Document

type Error = Error

The type returned in the event of a conversion error.

fn try_from(rawdoc: &RawDocument) -> Result<Document>

Performs the conversion.

impl StructuralPartialEq for RawDocument