diff --git a/.evergreen/check-rustdoc.sh b/.evergreen/check-rustdoc.sh new file mode 100755 index 00000000..8667cf23 --- /dev/null +++ b/.evergreen/check-rustdoc.sh @@ -0,0 +1,6 @@ +#!/bin/sh + +set -o errexit + +. ~/.cargo/env +cargo +nightly rustdoc -p bson --all-features -- --cfg docsrs -D warnings diff --git a/.evergreen/config.yml b/.evergreen/config.yml index aa8d34bf..ae1f161b 100644 --- a/.evergreen/config.yml +++ b/.evergreen/config.yml @@ -112,6 +112,16 @@ functions: ${PREPARE_SHELL} .evergreen/check-clippy.sh + "check rustdoc": + - command: shell.exec + type: test + params: + shell: bash + working_dir: "src" + script: | + ${PREPARE_SHELL} + .evergreen/check-rustdoc.sh + "init test-results": - command: shell.exec params: @@ -148,6 +158,10 @@ tasks: commands: - func: "check clippy" + - name: "check-rustdoc" + commands: + - func: "check rustdoc" + axes: - id: "extra-rust-versions" values: @@ -185,3 +199,4 @@ buildvariants: tasks: - name: "check-clippy" - name: "check-rustfmt" + - name: "check-rustdoc" diff --git a/Cargo.toml b/Cargo.toml index eedc8619..ffb6eb18 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -58,3 +58,8 @@ assert_matches = "1.2" serde_bytes = "0.11" pretty_assertions = "0.6.1" chrono = { version = "0.4", features = ["serde"] } +uuid = { version = "0.8.1", features = ["serde", "v4"] } + +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] \ No newline at end of file diff --git a/README.md b/README.md index 686831f8..01e7eb9a 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,24 @@ -# bson-rs +# bson [![crates.io](https://img.shields.io/crates/v/bson.svg)](https://crates.io/crates/bson) +[![docs.rs](https://docs.rs/mongodb/badge.svg)](https://docs.rs/bson) [![crates.io](https://img.shields.io/crates/l/bson.svg)](https://crates.io/crates/bson) Encoding and decoding support for BSON in Rust ## Index +- [Installation](#installation) + - [Requirements](#requirements) + - [Importing](#importing) + - [Feature flags](#feature-flags) +- [Useful links](#useful-links) - [Overview of BSON Format](#overview-of-bson-format) - [Usage](#usage) - [BSON Values](#bson-values) - [BSON Documents](#bson-documents) - [Modeling BSON with strongly typed data structures](#modeling-bson-with-strongly-typed-data-structures) + - [Working with datetimes](#working-with-datetimes) + - [Working with UUIDs](#working-with-uuids) - [Contributing](#contributing) - [Running the Tests](#running-the-tests) - [Continuous Integration](#continuous-integration) @@ -20,17 +28,28 @@ Encoding and decoding support for BSON in Rust - [Serde Documentation](https://serde.rs/) ## Installation -This crate works with Cargo and can be found on -[crates.io](https://crates.io/crates/bson) with a `Cargo.toml` like: +### Requirements +- Rust 1.48+ + +### Importing +This crate is available on [crates.io](https://crates.io/crates/bson). To use it in your application, simply add it to your project's `Cargo.toml`. ```toml [dependencies] bson = "2.0.0-beta.3" ``` -This crate requires Rust 1.48+. +Note that if you are using `bson` through the `mongodb` crate, you do not need to specify it in your +`Cargo.toml`, since the `mongodb` crate already re-exports it. + +#### Feature Flags + +| Feature | Description | Extra dependencies | Default | +|:-------------|:-----------------------------------------------------------------------------------------------|:-------------------|:--------| +| `chrono-0_4` | Enable support for v0.4 of the [`chrono`](docs.rs/chrono/0.4) crate in the public API. | n/a | no | +| `uuid-0_8` | Enable support for v0.8 of the [`uuid`](docs.rs/uuid/0.8) crate in the public API. | `uuid` 0.8 | no | -## Overview of BSON Format +## Overview of the BSON Format BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the embedding of documents and arrays within other documents @@ -186,6 +205,82 @@ separate the "business logic" that operates over the data from the (de)serializa translates the data to/from its serialized form. This can lead to more clear and concise code that is also less error prone. +### Working with datetimes + +The BSON format includes a datetime type, which is modeled in this crate by the +[`bson::DateTime`](https://docs.rs/bson/2.0.0-beta.3/bson/struct.DateTime.html) struct, and the +`Serialize` and `Deserialize` implementations for this struct produce and parse BSON datetimes when +serializing to or deserializing from BSON. The popular crate [`chrono`](https://docs.rs/chrono) also +provides a `DateTime` type, but its `Serialize` and `Deserialize` implementations operate on strings +instead, so when using it with BSON, the BSON datetime type is not used. To work around this, the +`chrono-0_4` feature flag can be enabled. This flag exposes a number of convenient conversions +between `bson::DateTime` and `chrono::DateTime`, including the +[`chrono_datetime_as_bson_datetime`](https://docs.rs/bson/2.0.0-beta.3/bson/serde_helpers/chrono_datetime_as_bson_datetime/index.html) +serde helper, which can be used to (de)serialize `chrono::DateTime`s to/from BSON datetimes, and the +`From` implementation for `Bson`, which allows `chrono::DateTime` values to be +used in the `doc!` and `bson!` macros. + +e.g. +``` rust +use serde::{Serialize, Deserialize}; + +#[derive(Serialize, Deserialize)] +struct Foo { + // serializes as a BSON datetime. + date_time: bson::DateTime, + + // serializes as an RFC 3339 / ISO-8601 string. + chrono_datetime: chrono::DateTime, + + // serializes as a BSON datetime. + // this requires the "chrono-0_4" feature flag + #[serde(with = "bson::serde_helpers::chrono_datetime_as_bson_datetime")] + chrono_as_bson: chrono::DateTime, +} + +// this automatic conversion also requires the "chrono-0_4" feature flag +let query = doc! { + "created_at": chrono::Utc::now(), +}; +``` + +### Working with UUIDs + +The BSON format does not contain a dedicated UUID type, though it does have a "binary" type which +has UUID subtypes. Accordingly, this crate provides a +[`Binary`](https://docs.rs/bson/latest/bson/struct.Binary.html) struct which models this binary type +and serializes to and deserializes from it. The popular [`uuid`](https://docs.rs/uuid) crate does +provide a UUID type (`Uuid`), though its `Serialize` and `Deserialize` implementations operate on +strings, so when using it with BSON, the BSON binary type will not be used. To facilitate the +conversion between `Uuid` values and BSON binary values, the `uuid-0_8` feature flag can be +enabled. This flag exposes a number of convenient conversions from `Uuid`, including the +[`uuid_as_binary`](https://docs.rs/bson/2.0.0-beta.3/bson/serde_helpers/uuid_as_binary/index.html) +serde helper, which can be used to (de)serialize `Uuid`s to/from BSON binaries with the UUID +subtype, and the `From` implementation for `Bson`, which allows `Uuid` values to be used in +the `doc!` and `bson!` macros. + +e.g. + +``` rust +use serde::{Serialize, Deserialize}; + +#[derive(Serialize, Deserialize)] +struct Foo { + // serializes as a String. + uuid: Uuid, + + // serializes as a BSON binary with subtype 4. + // this requires the "uuid-0_8" feature flag + #[serde(with = "bson::serde_helpers::uuid_as_binary")] + uuid_as_bson: uuid::Uuid, +} + +// this automatic conversion also requires the "uuid-0_8" feature flag +let query = doc! { + "uuid": uuid::Uuid::new_v4(), +}; +``` + ## Minimum supported Rust version (MSRV) The MSRV for this crate is currently 1.48.0. This will be rarely be increased, and if it ever is, diff --git a/rustfmt.toml b/rustfmt.toml index ca924c9a..ff7209cf 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -7,3 +7,4 @@ use_try_shorthand = true wrap_comments = true imports_layout = "HorizontalVertical" imports_granularity = "Crate" +ignore = ["src/lib.rs"] \ No newline at end of file diff --git a/src/bson.rs b/src/bson.rs index 6d78809a..5acfbf1f 100644 --- a/src/bson.rs +++ b/src/bson.rs @@ -321,12 +321,21 @@ impl From for Bson { } #[cfg(feature = "chrono-0_4")] +#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))] impl From> for Bson { fn from(a: chrono::DateTime) -> Bson { Bson::DateTime(crate::DateTime::from(a)) } } +#[cfg(feature = "uuid-0_8")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] +impl From for Bson { + fn from(uuid: uuid::Uuid) -> Self { + Bson::Binary(uuid.into()) + } +} + impl From for Bson { fn from(dt: crate::DateTime) -> Self { Bson::DateTime(dt) @@ -1045,6 +1054,17 @@ impl Binary { } } +#[cfg(feature = "uuid-0_8")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] +impl From for Binary { + fn from(uuid: uuid::Uuid) -> Self { + Binary { + subtype: BinarySubtype::Uuid, + bytes: uuid.as_bytes().to_vec(), + } + } +} + /// Represents a DBPointer. (Deprecated) #[derive(Debug, Clone, PartialEq)] pub struct DbPointer { diff --git a/src/datetime.rs b/src/datetime.rs index 3e8c5a8c..c2b20508 100644 --- a/src/datetime.rs +++ b/src/datetime.rs @@ -30,7 +30,7 @@ use chrono::{LocalResult, TimeZone, Utc}; /// will serialize to and deserialize from that format's equivalent of the /// [extended JSON representation](https://docs.mongodb.com/manual/reference/mongodb-extended-json/) of a datetime. /// To serialize a [`chrono::DateTime`] as a BSON datetime, you can use -/// [`serde_helpers::chrono_datetime_as_bson_datetime`]. +/// [`crate::serde_helpers::chrono_datetime_as_bson_datetime`]. /// /// ```rust /// # #[cfg(feature = "chrono-0_4")] @@ -81,6 +81,7 @@ impl crate::DateTime { /// Convert the given `chrono::DateTime` into a `bson::DateTime`, truncating it to millisecond /// precision. #[cfg(feature = "chrono-0_4")] + #[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))] pub fn from_chrono(dt: chrono::DateTime) -> Self { Self::from_millis(dt.timestamp_millis()) } @@ -119,11 +120,12 @@ impl crate::DateTime { /// assert_eq!(chrono_big, chrono::MAX_DATETIME) /// ``` #[cfg(feature = "chrono-0_4")] + #[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))] pub fn to_chrono(self) -> chrono::DateTime { self.to_chrono_private() } - /// Convert the given [`std::SystemTime`] to a [`DateTime`]. + /// Convert the given [`std::time::SystemTime`] to a [`DateTime`]. /// /// If the provided time is too far in the future or too far in the past to be represented /// by a BSON datetime, either [`DateTime::MAX`] or [`DateTime::MIN`] will be @@ -149,7 +151,7 @@ impl crate::DateTime { } } - /// Convert this [`DateTime`] to a [`std::SystemTime`]. + /// Convert this [`DateTime`] to a [`std::time::SystemTime`]. pub fn to_system_time(self) -> SystemTime { if self.0 >= 0 { SystemTime::UNIX_EPOCH + Duration::from_millis(self.0 as u64) @@ -204,6 +206,7 @@ impl From for SystemTime { } #[cfg(feature = "chrono-0_4")] +#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))] impl From for chrono::DateTime { fn from(bson_dt: DateTime) -> Self { bson_dt.to_chrono() @@ -211,6 +214,7 @@ impl From for chrono::DateTime { } #[cfg(feature = "chrono-0_4")] +#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))] impl From> for crate::DateTime { fn from(x: chrono::DateTime) -> Self { Self::from_chrono(x) diff --git a/src/de/error.rs b/src/de/error.rs index 4aae0ec0..7aee0680 100644 --- a/src/de/error.rs +++ b/src/de/error.rs @@ -30,7 +30,7 @@ pub enum Error { EndOfStream, /// A general error encountered during deserialization. - /// See: https://docs.serde.rs/serde/de/trait.Error.html + /// See: #[non_exhaustive] DeserializationError { /// A message describing the error. diff --git a/src/de/mod.rs b/src/de/mod.rs index fccfcef7..4e710499 100644 --- a/src/de/mod.rs +++ b/src/de/mod.rs @@ -423,7 +423,7 @@ where /// sequences with the Unicode replacement character. /// /// This is mainly useful when reading raw BSON returned from a MongoDB server, which -/// in rare cases can contain invalidly truncated strings (https://jira.mongodb.org/browse/SERVER-24007). +/// in rare cases can contain invalidly truncated strings (). /// For most use cases, [`crate::from_reader`] can be used instead. pub fn from_reader_utf8_lossy(reader: R) -> Result where @@ -447,7 +447,7 @@ where /// sequences with the Unicode replacement character. /// /// This is mainly useful when reading raw BSON returned from a MongoDB server, which -/// in rare cases can contain invalidly truncated strings (https://jira.mongodb.org/browse/SERVER-24007). +/// in rare cases can contain invalidly truncated strings (). /// For most use cases, [`crate::from_slice`] can be used instead. pub fn from_slice_utf8_lossy<'de, T>(bytes: &'de [u8]) -> Result where diff --git a/src/document.rs b/src/document.rs index d2cb1e0f..db5ac198 100644 --- a/src/document.rs +++ b/src/document.rs @@ -607,7 +607,7 @@ impl Document { /// stream. /// /// This is mainly useful when reading raw BSON returned from a MongoDB server, which - /// in rare cases can contain invalidly truncated strings (https://jira.mongodb.org/browse/SERVER-24007). + /// in rare cases can contain invalidly truncated strings (). /// For most use cases, `Document::from_reader` can be used instead. pub fn from_reader_utf8_lossy(mut reader: R) -> crate::de::Result { Self::decode(&mut reader, true) diff --git a/src/extjson/de.rs b/src/extjson/de.rs index b5c3eea4..90fc07df 100644 --- a/src/extjson/de.rs +++ b/src/extjson/de.rs @@ -35,7 +35,7 @@ pub enum Error { InvalidObjectId(oid::Error), /// A general error encountered during deserialization. - /// See: https://docs.serde.rs/serde/de/trait.Error.html + /// See: DeserializationError { message: String }, } diff --git a/src/lib.rs b/src/lib.rs index 397ac56d..78ae4e51 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -41,6 +41,29 @@ //! //! For more information about BSON itself, see [bsonspec.org](http://bsonspec.org). //! +//! ## Installation +//! ### Requirements +//! - Rust 1.48+ +//! +//! ### Importing +//! This crate is available on [crates.io](https://crates.io/crates/bson). To use it in your application, +//! simply add it to your project's `Cargo.toml`. +//! +//! ```toml +//! [dependencies] +//! bson = "2.0.0-beta.3" +//! ``` +//! +//! Note that if you are using `bson` through the `mongodb` crate, you do not need to specify it in +//! your `Cargo.toml`, since the `mongodb` crate already re-exports it. +//! +//! #### Feature Flags +//! +//! | Feature | Description | Extra dependencies | Default | +//! |:-------------|:-----------------------------------------------------------------------------------------------|:-------------------|:--------| +//! | `chrono-0_4` | Enable support for v0.4 of the [`chrono`](docs.rs/chrono/0.4) crate in the public API. | n/a | no | +//! | `uuid-0_8` | Enable support for v0.8 of the [`uuid`](docs.rs/uuid/0.8) crate in the public API. | `uuid` 0.8 | no | +//! //! ## BSON values //! //! Many different types can be represented as a BSON value, including 32-bit and 64-bit signed @@ -54,7 +77,8 @@ //! [`bson!`](macro.bson.html) macro: //! //! ```rust -//! # use bson::{bson, Bson}; +//! use bson::{bson, Bson}; +//! //! let string = Bson::String("hello world".to_string()); //! let int = Bson::Int32(5); //! let array = Bson::Array(vec![Bson::Int32(5), Bson::Boolean(false)]); @@ -77,7 +101,8 @@ //! //! e.g.: //! ```rust -//! # use bson::{bson, Bson}; +//! use bson::{bson, Bson}; +//! //! let value = Bson::Int32(5); //! let int = value.as_i32(); // Some(5) //! let bool = value.as_bool(); // None @@ -98,8 +123,9 @@ //! [`Document`](document/struct.Document.html)s can be created directly either from a byte //! reader containing BSON data or via the `doc!` macro: //! ```rust -//! # use bson::{doc, Document}; -//! # use std::io::Read; +//! use bson::{doc, Document}; +//! use std::io::Read; +//! //! let mut bytes = hex::decode("0C0000001069000100000000").unwrap(); //! let doc = Document::from_reader(&mut bytes.as_slice()).unwrap(); // { "i": 1 } //! @@ -118,7 +144,8 @@ //! access: //! //! ```rust -//! # use bson::doc; +//! use bson::doc; +//! //! let doc = doc! { //! "string": "string", //! "bool": true, @@ -145,8 +172,9 @@ //! //! e.g.: //! ```rust -//! # use serde::{Deserialize, Serialize}; -//! # use bson::{bson, Bson}; +//! use serde::{Deserialize, Serialize}; +//! use bson::{bson, Bson}; +//! //! #[derive(Serialize, Deserialize)] //! struct Person { //! name: String, @@ -182,6 +210,90 @@ //! translates the data to/from its serialized form. This can lead to more clear and concise code //! that is also less error prone. //! +//! ## Working with datetimes +//! +//! The BSON format includes a datetime type, which is modeled in this crate by the +//! [`DateTime`] struct, and the +//! `Serialize` and `Deserialize` implementations for this struct produce and parse BSON datetimes +//! when serializing to or deserializing from BSON. The popular crate [`chrono`](docs.rs/chrono) +//! also provides a `DateTime` type, but its `Serialize` and `Deserialize` implementations operate +//! on strings instead, so when using it with BSON, the BSON datetime type is not used. To work +//! around this, the `chrono-0_4` feature flag can be enabled. This flag exposes a number of +//! convenient conversions between `bson::DateTime` and `chrono::DateTime`, including the +//! [`serde_helpers::chrono_datetime_as_bson_datetime`] +//! serde helper, which can be used to (de)serialize `chrono::DateTime`s to/from BSON datetimes, and +//! the `From` implementation for [`Bson`], which allows `chrono::DateTime` values +//! to be used in the `doc!` and `bson!` macros. +//! +//! e.g. +//! ``` rust +//! # #[cfg(feature = "chrono-0_4")] +//! # { +//! use serde::{Serialize, Deserialize}; +//! use bson::doc; +//! +//! #[derive(Serialize, Deserialize)] +//! struct Foo { +//! // serializes as a BSON datetime. +//! date_time: bson::DateTime, +//! +//! // serializes as an RFC 3339 / ISO-8601 string. +//! chrono_datetime: chrono::DateTime, +//! +//! // serializes as a BSON datetime. +//! // this requires the "chrono-0_4" feature flag +//! #[serde(with = "bson::serde_helpers::chrono_datetime_as_bson_datetime")] +//! chrono_as_bson: chrono::DateTime, +//! } +//! +//! // this automatic conversion also requires the "chrono-0_4" feature flag +//! let query = doc! { +//! "created_at": chrono::Utc::now(), +//! }; +//! # } +//! ``` +//! +//! ## Working with UUIDs +//! +//! The BSON format does not contain a dedicated UUID type, though it does have a "binary" type +//! which has UUID subtypes. Accordingly, this crate provides a +//! [`Binary`] struct which models this binary type and +//! serializes to and deserializes from it. The popular `uuid` crate does provide a UUID type +//! (`Uuid`), though its `Serialize` and `Deserialize` implementations operate on strings, so when +//! using it with BSON, the BSON binary type will not be used. To facilitate the conversion between +//! `Uuid` values and BSON binary values, the `uuid-0_8` feature flag can be enabled. This flag +//! exposes a number of convenient conversions from `Uuid`, including the +//! [`serde_helpers::uuid_as_binary`] +//! serde helper, which can be used to (de)serialize `Uuid`s to/from BSON binaries with the UUID +//! subtype, and the `From` implementation for `Bson`, which allows `Uuid` values to be used +//! in the `doc!` and `bson!` macros. +//! +//! e.g. +//! +//! ``` rust +//! # #[cfg(feature = "chrono-0_4")] +//! # { +//! use serde::{Serialize, Deserialize}; +//! use bson::doc; +//! +//! #[derive(Serialize, Deserialize)] +//! struct Foo { +//! // serializes as a String. +//! uuid: uuid::Uuid, +//! +//! // serializes as a BSON binary with subtype 4. +//! // this requires the "uuid-0_8" feature flag +//! #[serde(with = "bson::serde_helpers::uuid_as_binary")] +//! uuid_as_bson: uuid::Uuid, +//! } +//! +//! // this automatic conversion also requires the "uuid-0_8" feature flag +//! let query = doc! { +//! "uuid": uuid::Uuid::new_v4(), +//! }; +//! # } +//! ``` +//! //! ## Minimum supported Rust version (MSRV) //! //! The MSRV for this crate is currently 1.48.0. This will be rarely be increased, and if it ever is, @@ -189,7 +301,9 @@ #![allow(clippy::cognitive_complexity)] #![doc(html_root_url = "https://docs.rs/bson/2.0.0-beta.3")] +#![cfg_attr(docsrs, feature(doc_cfg))] +#[doc(inline)] pub use self::{ bson::{Array, Binary, Bson, DbPointer, Document, JavaScriptCodeWithScope, Regex, Timestamp}, datetime::DateTime, diff --git a/src/ser/error.rs b/src/ser/error.rs index 9677e93e..62d3d7b1 100644 --- a/src/ser/error.rs +++ b/src/ser/error.rs @@ -15,7 +15,7 @@ pub enum Error { InvalidDocumentKey(Bson), /// A general error that occurred during serialization. - /// See: https://docs.rs/serde/1.0.110/serde/ser/trait.Error.html#tymethod.custom + /// See: #[non_exhaustive] SerializationError { /// A message describing the error. diff --git a/src/serde_helpers.rs b/src/serde_helpers.rs index 3a6a49f0..f3894c91 100644 --- a/src/serde_helpers.rs +++ b/src/serde_helpers.rs @@ -6,50 +6,62 @@ use serde::{ser, Serialize, Serializer}; use crate::oid::ObjectId; +#[doc(inline)] pub use bson_datetime_as_rfc3339_string::{ deserialize as deserialize_bson_datetime_from_rfc3339_string, serialize as serialize_bson_datetime_as_rfc3339_string, }; #[cfg(feature = "chrono-0_4")] +#[doc(inline)] pub use chrono_datetime_as_bson_datetime::{ deserialize as deserialize_chrono_datetime_from_bson_datetime, serialize as serialize_chrono_datetime_as_bson_datetime, }; +#[doc(inline)] pub use hex_string_as_object_id::{ deserialize as deserialize_hex_string_from_object_id, serialize as serialize_hex_string_as_object_id, }; +#[doc(inline)] pub use rfc3339_string_as_bson_datetime::{ deserialize as deserialize_rfc3339_string_from_bson_datetime, serialize as serialize_rfc3339_string_as_bson_datetime, }; +#[doc(inline)] pub use timestamp_as_u32::{ deserialize as deserialize_timestamp_from_u32, serialize as serialize_timestamp_as_u32, }; +#[doc(inline)] pub use u32_as_f64::{deserialize as deserialize_u32_from_f64, serialize as serialize_u32_as_f64}; +#[doc(inline)] pub use u32_as_timestamp::{ deserialize as deserialize_u32_from_timestamp, serialize as serialize_u32_as_timestamp, }; +#[doc(inline)] pub use u64_as_f64::{deserialize as deserialize_u64_from_f64, serialize as serialize_u64_as_f64}; #[cfg(feature = "uuid-0_8")] +#[doc(inline)] pub use uuid_as_binary::{ deserialize as deserialize_uuid_from_binary, serialize as serialize_uuid_as_binary, }; #[cfg(feature = "uuid-0_8")] +#[doc(inline)] pub use uuid_as_c_sharp_legacy_binary::{ deserialize as deserialize_uuid_from_c_sharp_legacy_binary, serialize as serialize_uuid_as_c_sharp_legacy_binary, }; #[cfg(feature = "uuid-0_8")] +#[doc(inline)] pub use uuid_as_java_legacy_binary::{ deserialize as deserialize_uuid_from_java_legacy_binary, serialize as serialize_uuid_as_java_legacy_binary, }; #[cfg(feature = "uuid-0_8")] +#[doc(inline)] pub use uuid_as_python_legacy_binary::{ deserialize as deserialize_uuid_from_python_legacy_binary, serialize as serialize_uuid_as_python_legacy_binary, @@ -189,6 +201,7 @@ pub mod u64_as_f64 { /// # } /// ``` #[cfg(feature = "chrono-0_4")] +#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))] pub mod chrono_datetime_as_bson_datetime { use crate::DateTime; use chrono::Utc; @@ -196,6 +209,7 @@ pub mod chrono_datetime_as_bson_datetime { use std::result::Result; /// Deserializes a [`chrono::DateTime`] from a [`crate::DateTime`]. + #[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))] pub fn deserialize<'de, D>(deserializer: D) -> Result, D::Error> where D: Deserializer<'de>, @@ -205,6 +219,7 @@ pub mod chrono_datetime_as_bson_datetime { } /// Serializes a [`chrono::DateTime`] as a [`crate::DateTime`]. + #[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))] pub fn serialize( val: &chrono::DateTime, serializer: S, @@ -338,6 +353,7 @@ pub mod hex_string_as_object_id { /// } /// ``` #[cfg(feature = "uuid-0_8")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub mod uuid_as_binary { use crate::{spec::BinarySubtype, Binary}; use serde::{de, Deserialize, Deserializer, Serialize, Serializer}; @@ -345,15 +361,14 @@ pub mod uuid_as_binary { use uuid::Uuid; /// Serializes a Uuid as a Binary. + #[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub fn serialize(val: &Uuid, serializer: S) -> Result { - let binary = Binary { - subtype: BinarySubtype::Uuid, - bytes: val.as_bytes().to_vec(), - }; + let binary: Binary = (*val).into(); binary.serialize(serializer) } /// Deserializes a Uuid from a Binary. + #[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub fn deserialize<'de, D>(deserializer: D) -> Result where D: Deserializer<'de>, @@ -395,6 +410,7 @@ pub mod uuid_as_binary { /// } /// ``` #[cfg(feature = "uuid-0_8")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub mod uuid_as_java_legacy_binary { use crate::{spec::BinarySubtype, Binary}; use serde::{de, Deserialize, Deserializer, Serialize, Serializer}; @@ -402,6 +418,7 @@ pub mod uuid_as_java_legacy_binary { use uuid::Uuid; /// Serializes a Uuid as a Binary in a Java Legacy UUID format. + #[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub fn serialize(val: &Uuid, serializer: S) -> Result { let mut bytes = val.as_bytes().to_vec(); bytes[0..8].reverse(); @@ -414,6 +431,7 @@ pub mod uuid_as_java_legacy_binary { } /// Deserializes a Uuid from a Binary in a Java Legacy UUID format. + #[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub fn deserialize<'de, D>(deserializer: D) -> Result where D: Deserializer<'de>, @@ -451,6 +469,7 @@ pub mod uuid_as_java_legacy_binary { /// } /// ``` #[cfg(feature = "uuid-0_8")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub mod uuid_as_python_legacy_binary { use crate::{spec::BinarySubtype, Binary}; use serde::{de, Deserialize, Deserializer, Serialize, Serializer}; @@ -458,6 +477,7 @@ pub mod uuid_as_python_legacy_binary { use uuid::Uuid; /// Serializes a Uuid as a Binary in a Python Legacy UUID format. + #[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub fn serialize(val: &Uuid, serializer: S) -> Result { let binary = Binary { subtype: BinarySubtype::UuidOld, @@ -467,6 +487,7 @@ pub mod uuid_as_python_legacy_binary { } /// Deserializes a Uuid from a Binary in a Python Legacy UUID format. + #[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub fn deserialize<'de, D>(deserializer: D) -> Result where D: Deserializer<'de>, @@ -502,6 +523,7 @@ pub mod uuid_as_python_legacy_binary { /// } /// ``` #[cfg(feature = "uuid-0_8")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub mod uuid_as_c_sharp_legacy_binary { use crate::{spec::BinarySubtype, Binary}; use serde::{de, Deserialize, Deserializer, Serialize, Serializer}; @@ -509,6 +531,7 @@ pub mod uuid_as_c_sharp_legacy_binary { use uuid::Uuid; /// Serializes a Uuid as a Binary in a C# Legacy UUID format. + #[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub fn serialize(val: &Uuid, serializer: S) -> Result { let mut bytes = val.as_bytes().to_vec(); bytes[0..4].reverse(); @@ -522,6 +545,7 @@ pub mod uuid_as_c_sharp_legacy_binary { } /// Deserializes a Uuid from a Binary in a C# Legacy UUID format. + #[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))] pub fn deserialize<'de, D>(deserializer: D) -> Result where D: Deserializer<'de>,