[−][src]Crate rawbson
A rawbson document can be created from a Vec<u8>
containing raw BSON data, and elements
accessed via methods similar to those in the bson-rust
crate. Note that rawbson returns a Result<Option
use rawbson::{ DocBuf, elem, }; // \x13\x00\x00\x00 // total document size // \x02 // 0x02 = type String // hi\x00 // field name // \x06\x00\x00\x00y'all\x00 // field value // \x00 // document terminating NUL let doc = DocBuf::new(b"\x13\x00\x00\x00\x02hi\x00\x06\x00\x00\x00y'all\x00\x00".to_vec())?; let elem: Option<elem::Element> = doc.get("hi")?; assert_eq!( elem.unwrap().as_str()?, "y'all", );
bson-rust interop
This crate is designed to interoperate smoothly with the bson crate.
A DocBuf
can be created from a bson::document::Document
. Internally, this
serializes the Document
to a Vec<u8>
, and then includes those bytes in the DocBuf
.
use bson::doc; use rawbson::{ DocBuf, }; let document = doc!{"goodbye": {"cruel": "world"}}; let raw = DocBuf::from_document(&document); let value: Option<&str> = raw.get_document("goodbye")? .map(|doc| doc.get_str("cruel")) .transpose()? .flatten(); assert_eq!( value, Some("world"), );
Reference types
A BSON document can also be accessed with the Doc
reference type,
which is an unsized type that represents the BSON payload as a [u8]
.
This allows accessing nested documents without reallocation. Doc
must always be accessed via a pointer type, similarly to [T]
and str
.
This type will coexist with the now deprecated DocRef type for at least one minor release.
The below example constructs a bson document in a stack-based array, and extracts a &str from it, performing no heap allocation.
use rawbson::Doc; let bytes = b"\x13\x00\x00\x00\x02hi\x00\x06\x00\x00\x00y'all\x00\x00"; assert_eq!(Doc::new(bytes)?.get_str("hi")?, Some("y'all"));
Iteration
Doc
implements IntoIterator
, which can also
be accessed via DocBuf::iter
.
use bson::doc; use rawbson::{DocBuf, elem::Element}; let doc = DocBuf::from_document(&doc! {"crate": "rawbson", "license": "MIT"}); let mut dociter = doc.iter(); let (key, value): (&str, Element) = dociter.next().unwrap()?; assert_eq!(key, "crate"); assert_eq!(value.as_str()?, "rawbson"); let (key, value): (&str, Element) = dociter.next().unwrap()?; assert_eq!(key, "license"); assert_eq!(value.as_str()?, "MIT");
serde support
There is also serde deserialization support.
Serde serialization support is not yet provided. For now, use
bson::to_document
instead, and then serialize it out using
bson::Document::to_writer
or DocBuf::from_document
.
use serde::Deserialize; use bson::{doc, Document, oid::ObjectId, DateTime}; use rawbson::{DocBuf, de::from_docbuf}; #[derive(Deserialize)] #[serde(rename_all="camelCase")] struct User { #[serde(rename = "_id")] id: ObjectId, first_name: String, last_name: String, birthdate: Option<chrono::DateTime<chrono::Utc>>, #[serde(flatten)] extra: Document, } let doc = DocBuf::from_document(&doc!{ "_id": ObjectId::with_string("543254325432543254325432")?, "firstName": "John", "lastName": "Doe", "birthdate": null, "luckyNumbers": [3, 60, 2147483647], "nickname": "Red", }); let user: User = from_docbuf(&doc)?; assert_eq!(user.id.to_hex(), "543254325432543254325432"); assert_eq!(user.first_name, "John"); assert_eq!(user.last_name, "Doe"); assert_eq!(user.extra.get_str("nickname")?, "Red"); assert!(user.birthdate.is_none());
Modules
de | |
elem |
Structs
Array | |
ArrayIter | |
Doc | A BSON document, referencing raw binary data stored elsewhere. This can be created from
a DocBuf or any type that contains valid BSON data, and can be referenced as a |
DocBuf | A BSON document, stored as raw binary data on the heap. This can be created from
a |
DocIter |
Enums
RawError | Error to indicate that either a value was empty or it contained an unexpected type, for use with the direct getters. |
Type Definitions
ArrayRef | |
DocRef | |
RawResult |