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
- An error that occurs when attempting to parse raw BSON bytes.
- An iterator over the document’s entries.
- A slice of a BSON document containing a BSON array value (akin to
std::str
). This can be retrieved from aRawDocument
viaRawDocument::get
. - 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 toRawDocumentBuf
or as a field in aDeserialize
struct. - An iterator over borrowed raw BSON array values.
- A BSON binary value referencing raw bytes stored elsewhere.
- A BSON DB pointer value referencing raw bytes stored elesewhere.
- A slice of a BSON document (akin to
std::str
). This can be created from aRawDocumentBuf
or any type that contains valid BSON data, including static binary literals,Vec<u8>
, or arrays. - An owned BSON document (akin to
std::path::PathBuf
), backed by a buffer of raw BSON bytes. This can be created from aVec<u8>
or acrate::Document
. - A BSON “code with scope” value backed by owned raw BSON.
- A BSON “code with scope” value referencing raw bytes stored elsewhere.
- A BSON regex referencing raw bytes stored elsewhere.
- 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
).
Enums
- The different categories of errors that can be returned when reading from raw BSON.
- A BSON value backed by owned raw BSON bytes.
- A BSON value referencing raw bytes stored elsewhere.
- The type of error encountered when using a direct getter (e.g.
crate::RawDocument::get_str
).