Struct bson2::raw::RawDocument [−][src]
#[repr(transparent)]pub struct RawDocument { /* fields omitted */ }
Expand description
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
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::new(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::new(b"\x13\x00\x00\x00\x02hi\x00\x06\x00\x00\x00y'all\x00\x00")?;
assert_eq!(doc.get_str("hi")?, "y'all");
Implementations
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::new(b"\x05\0\0\0\0")?;
Creates a new RawDocument
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::new(data)?;
let doc: RawDocumentBuf = doc_ref.to_raw_document_buf();
Gets a reference to the value corresponding to the given key by iterating until the key is found.
use bson::{doc, oid::ObjectId, raw::{RawDocumentBuf, RawBson}};
let doc = RawDocumentBuf::from_document(&doc! {
"_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());
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, RawDocumentBuf};
use bson::doc;
let doc = RawDocumentBuf::from_document(&doc! {
"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));
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::{doc, raw::{RawDocumentBuf, ValueAccessErrorKind}};
let doc = RawDocumentBuf::from_document(&doc! {
"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));
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::{doc, raw::{ValueAccessErrorKind, RawDocumentBuf}};
let doc = RawDocumentBuf::from_document(&doc! {
"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));
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::{doc, raw::{RawDocumentBuf, ValueAccessErrorKind}};
let doc = RawDocumentBuf::from_document(&doc! {
"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));
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::{
doc,
raw::{ValueAccessErrorKind, RawDocumentBuf, RawBinary},
spec::BinarySubtype,
Binary,
};
let doc = RawDocumentBuf::from_document(&doc! {
"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));
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::{doc, oid::ObjectId, raw::{ValueAccessErrorKind, RawDocumentBuf}};
let doc = RawDocumentBuf::from_document(&doc! {
"_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));
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::{doc, oid::ObjectId, raw::{RawDocumentBuf, ValueAccessErrorKind}};
let doc = RawDocumentBuf::from_document(&doc! {
"_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));
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::{doc, raw::{ValueAccessErrorKind, RawDocumentBuf}, DateTime};
let dt = DateTime::now();
let doc = RawDocumentBuf::from_document(&doc! {
"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));
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::{doc, Regex, raw::{RawDocumentBuf, ValueAccessErrorKind}};
let doc = RawDocumentBuf::from_document(&doc! {
"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));
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::{doc, Timestamp, raw::{RawDocumentBuf, ValueAccessErrorKind}};
let doc = RawDocumentBuf::from_document(&doc! {
"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));
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::{doc, raw::{RawDocumentBuf, ValueAccessErrorKind}};
let doc = RawDocumentBuf::from_document(&doc! {
"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));
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::{doc, raw::{ValueAccessErrorKind, RawDocumentBuf}};
let doc = RawDocumentBuf::from_document(&doc! {
"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));
Return a reference to the contained data as a &[u8]
use bson::{doc, raw::RawDocumentBuf};
let docbuf = RawDocumentBuf::from_document(&doc!{})?;
assert_eq!(docbuf.as_bytes(), b"\x05\x00\x00\x00\x00");
Trait Implementations
Performs the conversion.
Performs the conversion.
Immutably borrows from an owned value. Read more
Deserialize this value from the given Serde deserializer. Read more
Performs the conversion.
This method tests for self
and other
values to be equal, and is used
by ==
. Read more
This method tests for !=
.
type Owned = RawDocumentBuf
type Owned = RawDocumentBuf
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more