Module bson::raw

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

Error

An error that occurs when attempting to parse raw BSON bytes.

Iter

An iterator over the document’s entries.

RawArray

A slice of a BSON document containing a BSON array value (akin to std::str). This can be retrieved from a RawDocument via RawDocument::get.

RawArrayBuf

An owned BSON array value (akin to std::path::PathBuf), backed by a buffer of raw BSON bytes. This type can be used to construct owned array values, which can be used to append to RawDocumentBuf or as a field in a Deserialize struct.

RawArrayIter

An iterator over borrowed raw BSON array values.

RawBinaryRef

A BSON binary value referencing raw bytes stored elsewhere.

RawDbPointerRef

A BSON DB pointer value referencing raw bytes stored elesewhere.

RawDocument

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, or arrays.

RawDocumentBuf

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.

RawJavaScriptCodeWithScope

A BSON “code with scope” value backed by owned raw BSON.

RawJavaScriptCodeWithScopeRef

A BSON “code with scope” value referencing raw bytes stored elsewhere.

RawRegexRef

A BSON regex referencing raw bytes stored elsewhere.

ValueAccessError

Error to indicate that either a value was empty or it contained an unexpected type, for use with the direct getters (e.g. crate::RawDocument::get_str).