update docs for 2.0, add From<Uuid> impl for Binary/Bson

Author: patrickfreed

Cargo.toml

@@ -61,3 +61,7 @@ assert_matches = "1.2"
 serde_bytes = "0.11"
 pretty_assertions = "0.6.1"
 chrono = { version = "0.4", features = ["serde"] }
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

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,29 @@ 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 |
+|:-------------|:-----------------------------------------------------------------------------------------------|:-------------------|:--------|
+| `u2i`        | Attempt to serialize unsigned integer types found in `Serialize` structs to signed BSON types. | n/a                | yes     |
+| `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 +206,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<chrono::DateTime>` 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<chrono::Utc>,
+
+    // 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<chrono::Utc>,
+}
+
+// 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_bson_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<Uuid>` 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(),
+};
+```
+
 ## Contributing
 
 We encourage and would happily accept contributions in the form of GitHub pull requests. Before opening one, be sure to run the tests locally; check out the [testing section](#running-the-tests) for information on how to do that. Once you open a pull request, your branch will be run against the same testing matrix that we use for our [continuous integration](#continuous-integration) system, so it is usually sufficient to only run the integration tests locally against a standalone. Remember to always run the linter tests before opening a pull request.

src/bson.rs

@@ -321,12 +321,21 @@ impl From<oid::ObjectId> for Bson {
 }
 
 #[cfg(feature = "chrono-0_4")]
+#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))]
 impl<T: chrono::TimeZone> From<chrono::DateTime<T>> for Bson {
     fn from(a: chrono::DateTime<T>) -> Bson {
         Bson::DateTime(crate::DateTime::from(a))
     }
 }
 
+#[cfg(feature = "uuid-0_8")]
+#[cfg_attr(docsrs, doc(cfg(feature = "uuid-0_8")))]
+impl From<uuid::Uuid> for Bson {
+    fn from(uuid: uuid::Uuid) -> Self {
+        Bson::Binary(uuid.into())
+    }
+}
+
 impl From<crate::DateTime> 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<uuid::Uuid> 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 {

src/datetime.rs

@@ -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<T: chrono::TimeZone>(dt: chrono::DateTime<T>) -> Self {
         Self::from_millis(dt.timestamp_millis())
     }
@@ -119,6 +120,7 @@ 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<Utc> {
         self.to_chrono_private()
     }
@@ -204,13 +206,15 @@ impl From<crate::DateTime> for SystemTime {
 }
 
 #[cfg(feature = "chrono-0_4")]
+#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))]
 impl From<crate::DateTime> for chrono::DateTime<Utc> {
     fn from(bson_dt: DateTime) -> Self {
         bson_dt.to_chrono()
     }
 }
 
 #[cfg(feature = "chrono-0_4")]
+#[cfg_attr(docsrs, doc(cfg(feature = "chrono-0_4")))]
 impl<T: chrono::TimeZone> From<chrono::DateTime<T>> for crate::DateTime {
     fn from(x: chrono::DateTime<T>) -> Self {
         Self::from_chrono(x)

src/lib.rs

@@ -41,6 +41,34 @@
 //!
 //! 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 | |:-------------|:
+//! -----------------------------------------------------------------------------------------------|:
+//! -------------------|:--------| | `u2i`        | Attempt to serialize unsigned integer types
+//! found in `Serialize` structs to signed BSON types. | n/a                | yes     |
+//! | `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
@@ -181,10 +209,94 @@
 //! separate the "business logic" that operates over the data from the (de)serialization logic that
 //! 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`] 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<chrono::DateTime>` 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};
+//!
+//! #[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<chrono::Utc>,
+//!
+//!     // 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<chrono::Utc>,
+//! }
+//!
+//! // 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_bson_binary`]
+//! serde helper, which can be used to (de)serialize `Uuid`s to/from BSON binaries with the UUID
+//! subtype, and the `From<Uuid>` 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};
+//!
+//! #[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(),
+//! };
+//! # }
+//! ```
 
 #![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,