Module qm_mongodb::bson::raw

source ·
Expand description

An API for interacting with raw BSON bytes.

This module provides two document types, RawDocumentBuf and RawDocument (akin to std::string::String and str), for working with raw BSON documents. These types differ from the regular crate::Document type in that their storage is BSON bytes rather than a hash-map like Rust type. In certain circumstances, these types can be leveraged for increased performance.

This module also provides a RawBson type for modeling any borrowed BSON element and a RawArray type for modeling a borrowed slice of a document containing a BSON array element.

A RawDocumentBuf can be created from a Vec<u8> containing raw BSON data. A RawDocument can be created from anything that can be borrowed as a &[u8]. Both types can access elements via methods similar to those available on the crate::Document type. Note that RawDocument::get (which RawDocument calls through to via its Deref implementation) returns a Result, since the bytes contained in the document are not fully validated until trying to access the contained data.

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

// See http://bsonspec.org/spec.html for details on the binary encoding of BSON.
let doc = RawDocumentBuf::from_bytes(b"\x13\x00\x00\x00\x02hi\x00\x06\x00\x00\x00y'all\x00\x00".to_vec())?;
let elem = doc.get("hi")?.unwrap();

assert_eq!(
  elem.as_str(),
  Some("y'all"),
);

§crate::Document interop

A RawDocument can be created from a crate::Document. Internally, this serializes the crate::Document to a Vec<u8>, and then includes those bytes in the RawDocument.

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

let document = doc! {
   "goodbye": {
       "cruel": "world"
   }
};

let raw = RawDocumentBuf::from_document(&document)?;
let value = raw
    .get_document("goodbye")?
    .get_str("cruel")?;

assert_eq!(
    value,
    "world",
);

§Reference type (RawDocument)

A BSON document can also be accessed with the RawDocument type, which is an unsized type that represents the BSON payload as a [u8]. This allows accessing nested documents without reallocation. RawDocument must always be accessed via a pointer type, similar to [T] and str.

The below example constructs a bson document in a stack-based array, and extracts a &str from it, performing no heap allocation.

use bson::raw::RawDocument;

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

§Iteration

RawDocument implements IntoIterator, which can also be accessed via RawDocumentBuf::iter.

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

let original_doc = doc! {
    "crate": "bson",
    "year": "2021",
};

let doc = RawDocumentBuf::from_document(&original_doc)?;
let mut doc_iter = doc.iter();

let (key, value): (&str, RawBsonRef) = doc_iter.next().unwrap()?;
assert_eq!(key, "crate");
assert_eq!(value.as_str(), Some("bson"));

let (key, value): (&str, RawBsonRef) = doc_iter.next().unwrap()?;
assert_eq!(key, "year");
assert_eq!(value.as_str(), Some("2021"));

Structs§

Enums§

Type Aliases§