From 8699a444d512caef6411dd7f493a7fda3d6cc144 Mon Sep 17 00:00:00 2001 From: Jonas Bushart Date: Tue, 3 May 2022 21:25:52 +0000 Subject: [PATCH] Add documentation for time * Add a simple module documentation, similar to the chrono one. * Describe the new feature flag. * Update the documentations for the Timestamp* and Duration* types, both where they are defined and in the transformations list. * Add new transformations for the well-known Rfc2822 and Rfc3339 types. --- serde_with/src/guide/feature_flags.md | 8 +++++ .../src/guide/serde_as_transformations.md | 29 +++++++++++++++++++ serde_with/src/lib.rs | 22 ++++++++++++-- serde_with/src/time_0_3.rs | 6 ++++ 4 files changed, 62 insertions(+), 3 deletions(-) diff --git a/serde_with/src/guide/feature_flags.md b/serde_with/src/guide/feature_flags.md index 6b5a8d84..9e80177a 100644 --- a/serde_with/src/guide/feature_flags.md +++ b/serde_with/src/guide/feature_flags.md @@ -10,6 +10,7 @@ Each entry will explain the feature in more detail. 5. [`indexmap`](#indexmap) 6. [`json`](#json) 7. [`macros`](#macros) +8. [`time_0_3`](#time_0_3) ## `base64` @@ -52,3 +53,10 @@ The `macros` features enables all helper macros and derives. It is enabled by default, since the macros provide a usability benefit, especially for `serde_as`. This pulls in `serde_with_macros` as a dependency. + +## `time_0_3` + +The `time_0_3` enables integration of `time` v0.3 specific conversions. +This includes support for the timestamp and duration types. + +This pulls in `time` v0.3 as a dependency. diff --git a/serde_with/src/guide/serde_as_transformations.md b/serde_with/src/guide/serde_as_transformations.md index fd8b4a1c..0d85515e 100644 --- a/serde_with/src/guide/serde_as_transformations.md +++ b/serde_with/src/guide/serde_as_transformations.md @@ -23,6 +23,7 @@ This page lists the transformations implemented in this crate and supported by ` 19. [Timestamps as seconds since UNIX epoch](#timestamps-as-seconds-since-unix-epoch) 20. [Value into JSON String](#value-into-json-string) 21. [`Vec` of tuples to `Maps`](#vec-of-tuples-to-maps) +22. [Well-known time formats for `OffsetDateTime`](#well-known-time-formats-for-offsetdatetime) ## Base64 encode bytes @@ -212,6 +213,8 @@ value: Duration, The same conversions are also implemented for [`chrono::Duration`] with the `chrono` feature. +The same conversions are also implemented for [`time::Duration`] with the `time_0_3` feature. + ## Hex encode bytes [`Hex`] @@ -405,6 +408,8 @@ value: SystemTime, The same conversions are also implemented for [`chrono::DateTime`], [`chrono::DateTime`], and [`chrono::NaiveDateTime`] with the `chrono` feature. +The conversions are availble for [`time::OffsetDateTime`] and [`time::PrimitiveDateTime`] with the `time_0_3` feature enabled. + ## Value into JSON String Some JSON APIs are weird and return a JSON encoded string in a JSON response @@ -446,6 +451,25 @@ This includes `BinaryHeap<(K, V)>`, `BTreeSet<(K, V)>`, `HashSet<(K, V)>`, `Link The [inverse operation](#maps-to-vec-of-tuples) is also available. +## Well-known time formats for `OffsetDateTime` + +[`time::OffsetDateTime`] can be serialized in string format in different well-known formats. +Two formats are supported, [`time::format_description::well_known::Rfc2822`] and [`time::format_description::well_known::Rfc3339`]. + +```ignore +// Rust +#[serde_as(as = "time::format_description::well_known::Rfc2822")] +rfc_2822: OffsetDateTime, +#[serde_as(as = "time::format_description::well_known::Rfc3339")] +rfc_3339: OffsetDateTime, + +// JSON +"rfc_2822": "Fri, 21 Nov 1997 09:55:06 -0600", +"rfc_3339": "1997-11-21T09:55:06-06:00", +``` + +These conversions are availble with the `time_0_3` feature flag. + [`Base64`]: crate::base64::Base64 [`Bytes`]: crate::Bytes [`chrono::DateTime`]: chrono_crate::DateTime @@ -464,6 +488,11 @@ The [inverse operation](#maps-to-vec-of-tuples) is also available. [`NoneAsEmptyString`]: crate::NoneAsEmptyString [`OneOrMany`]: crate::OneOrMany [`PickFirst`]: crate::PickFirst +[`time::Duration`]: time_0_3::Duration +[`time::format_description::well_known::Rfc2822`]: time_0_3::format_description::well_known::Rfc2822 +[`time::format_description::well_known::Rfc3339`]: time_0_3::format_description::well_known::Rfc3339 +[`time::OffsetDateTime`]: time_0_3::OffsetDateTime +[`time::PrimitiveDateTime`]: time_0_3::PrimitiveDateTime [`TimestampSeconds`]: crate::TimestampSeconds [`TimestampSecondsWithFrac`]: crate::TimestampSecondsWithFrac [`TryFromInto`]: crate::TryFromInto diff --git a/serde_with/src/lib.rs b/serde_with/src/lib.rs index f93ab586..6ef712df 100644 --- a/serde_with/src/lib.rs +++ b/serde_with/src/lib.rs @@ -264,9 +264,6 @@ pub mod base64; #[cfg(feature = "chrono")] #[cfg_attr(docsrs, doc(cfg(feature = "chrono")))] pub mod chrono; -#[cfg(feature = "time_0_3")] -#[cfg_attr(docsrs, doc(cfg(feature = "time_0_3")))] -pub mod time_0_3; mod content; pub mod de; mod duplicate_key_impls; @@ -282,6 +279,9 @@ pub mod json; pub mod rust; pub mod ser; mod serde_conv; +#[cfg(feature = "time_0_3")] +#[cfg_attr(docsrs, doc(cfg(feature = "time_0_3")))] +pub mod time_0_3; mod utils; #[doc(hidden)] pub mod with_prefix; @@ -749,6 +749,7 @@ pub struct BytesOrString; /// For example, deserializing `DurationSeconds` will discard any subsecond precision during deserialization from `f64` and will parse a `String` as an integer number. /// /// This type also supports [`chrono::Duration`] with the `chrono`-[feature flag]. +/// This type also supports [`time::Duration`][::time_0_3::Duration] with the `time_0_3`-[feature flag]. /// /// | Duration Type | Converter | Available `FORMAT`s | /// | --------------------- | ------------------------- | ---------------------- | @@ -756,6 +757,8 @@ pub struct BytesOrString; /// | `std::time::Duration` | `DurationSecondsWithFrac` | `f64`, `String` | /// | `chrono::Duration` | `DurationSeconds` | `i64`, `f64`, `String` | /// | `chrono::Duration` | `DurationSecondsWithFrac` | `f64`, `String` | +/// | `time::Duration` | `DurationSeconds` | `i64`, `f64`, `String` | +/// | `time::Duration` | `DurationSecondsWithFrac` | `f64`, `String` | /// /// # Examples /// @@ -889,6 +892,7 @@ pub struct DurationSeconds< /// For example, deserializing `DurationSeconds` will discard any subsecond precision during deserialization from `f64` and will parse a `String` as an integer number. /// /// This type also supports [`chrono::Duration`] with the `chrono`-[feature flag]. +/// This type also supports [`time::Duration`][::time_0_3::Duration] with the `time_0_3`-[feature flag]. /// /// | Duration Type | Converter | Available `FORMAT`s | /// | --------------------- | ------------------------- | ---------------------- | @@ -896,6 +900,8 @@ pub struct DurationSeconds< /// | `std::time::Duration` | `DurationSecondsWithFrac` | `f64`, `String` | /// | `chrono::Duration` | `DurationSeconds` | `i64`, `f64`, `String` | /// | `chrono::Duration` | `DurationSecondsWithFrac` | `f64`, `String` | +/// | `time::Duration` | `DurationSeconds` | `i64`, `f64`, `String` | +/// | `time::Duration` | `DurationSecondsWithFrac` | `f64`, `String` | /// /// # Examples /// @@ -1069,6 +1075,7 @@ pub struct DurationNanoSecondsWithFrac< /// For example, deserializing `TimestampSeconds` will discard any subsecond precision during deserialization from `f64` and will parse a `String` as an integer number. /// /// This type also supports [`chrono::DateTime`][DateTime] with the `chrono`-[feature flag]. +/// This type also supports [`time::OffsetDateTime`][::time_0_3::OffsetDateTime] and [`time::PrimitiveDateTime`][::time_0_3::PrimitiveDateTime] with the `time_0_3`-[feature flag]. /// /// | Timestamp Type | Converter | Available `FORMAT`s | /// | ------------------------- | -------------------------- | ---------------------- | @@ -1078,6 +1085,10 @@ pub struct DurationNanoSecondsWithFrac< /// | `chrono::DateTime` | `TimestampSecondsWithFrac` | `f64`, `String` | /// | `chrono::DateTime` | `TimestampSeconds` | `i64`, `f64`, `String` | /// | `chrono::DateTime` | `TimestampSecondsWithFrac` | `f64`, `String` | +/// | `time::OffsetDateTime` | `TimestampSeconds` | `i64`, `f64`, `String` | +/// | `time::OffsetDateTime` | `TimestampSecondsWithFrac` | `f64`, `String` | +/// | `time::PrimitiveDateTime` | `TimestampSeconds` | `i64`, `f64`, `String` | +/// | `time::PrimitiveDateTime` | `TimestampSecondsWithFrac` | `f64`, `String` | /// /// # Examples /// @@ -1212,6 +1223,7 @@ pub struct TimestampSeconds< /// For example, deserializing `TimestampSeconds` will discard any subsecond precision during deserialization from `f64` and will parse a `String` as an integer number. /// /// This type also supports [`chrono::DateTime`][DateTime] and [`chrono::NaiveDateTime`][NaiveDateTime] with the `chrono`-[feature flag]. +/// This type also supports [`time::OffsetDateTime`][::time_0_3::OffsetDateTime] and [`time::PrimitiveDateTime`][::time_0_3::PrimitiveDateTime] with the `time_0_3`-[feature flag]. /// /// | Timestamp Type | Converter | Available `FORMAT`s | /// | ------------------------- | -------------------------- | ---------------------- | @@ -1223,6 +1235,10 @@ pub struct TimestampSeconds< /// | `chrono::DateTime` | `TimestampSecondsWithFrac` | `f64`, `String` | /// | `chrono::NaiveDateTime` | `TimestampSeconds` | `i64`, `f64`, `String` | /// | `chrono::NaiveDateTime` | `TimestampSecondsWithFrac` | `f64`, `String` | +/// | `time::OffsetDateTime` | `TimestampSeconds` | `i64`, `f64`, `String` | +/// | `time::OffsetDateTime` | `TimestampSecondsWithFrac` | `f64`, `String` | +/// | `time::PrimitiveDateTime` | `TimestampSeconds` | `i64`, `f64`, `String` | +/// | `time::PrimitiveDateTime` | `TimestampSecondsWithFrac` | `f64`, `String` | /// /// # Examples /// diff --git a/serde_with/src/time_0_3.rs b/serde_with/src/time_0_3.rs index be4d74ab..b1c44ce7 100644 --- a/serde_with/src/time_0_3.rs +++ b/serde_with/src/time_0_3.rs @@ -1,3 +1,9 @@ +//! De/Serialization of [time v0.3][time] types +//! +//! This modules is only available if using the `time_0_3` feature of the crate. +//! +//! [time]: https://docs.rs/time/0.3/ + use crate::de::DeserializeAs; use crate::formats::{Flexible, Format, Strict, Strictness}; use crate::ser::SerializeAs;