Make datetime.rs structs and fields public #431 (#439)

* Make datetime.rs structs and fields public #431

* Make {Date, Time, Offset} public #431 #439

* rustfmt: alphabetize pub use declaration

* Add docs for Datetime, Date, Time, Offset

* Correct doc for Offset, make others consistent

Co-authored-by: David James <[email protected]>

src/datetime.rs

@@ -21,11 +21,74 @@ use serde::{de, ser};
 /// Also note though that while this type implements `Serialize` and
 /// `Deserialize` it's only recommended to use this type with the TOML format,
 /// otherwise encoded in other formats it may look a little odd.
+///
+/// Depending on how the option values are used, this struct will correspond
+/// with one of the following four datetimes from the [TOML v1.0.0 spec]:
+///
+/// | `date`    | `time`    | `offset`  | TOML type          |
+/// | --------- | --------- | --------- | ------------------ |
+/// | `Some(_)` | `Some(_)` | `Some(_)` | [Offset Date-Time] |
+/// | `Some(_)` | `Some(_)` | `None`    | [Local Date-Time]  |
+/// | `Some(_)` | `None`    | `None`    | [Local Date]       |
+/// | `None`    | `Some(_)` | `None`    | [Local Time]       |
+///
+/// **1. Offset Date-Time**: If all the optional values are used, `Datetime`
+/// corresponds to an [Offset Date-Time]. From the TOML v1.0.0 spec:
+///
+/// > To unambiguously represent a specific instant in time, you may use an
+/// > RFC 3339 formatted date-time with offset.
+/// >
+/// > ```toml
+/// > odt1 = 1979-05-27T07:32:00Z
+/// > odt2 = 1979-05-27T00:32:00-07:00
+/// > odt3 = 1979-05-27T00:32:00.999999-07:00
+/// > ```
+/// >
+/// > For the sake of readability, you may replace the T delimiter between date
+/// > and time with a space character (as permitted by RFC 3339 section 5.6).
+/// >
+/// > ```toml
+/// > odt4 = 1979-05-27 07:32:00Z
+/// > ```
+///
+/// **2. Local Date-Time**: If `date` and `time` are given but `offset` is
+/// `None`, `Datetime` corresponds to a [Local Date-Time]. From the spec:
+///
+/// > If you omit the offset from an RFC 3339 formatted date-time, it will
+/// > represent the given date-time without any relation to an offset or
+/// > timezone. It cannot be converted to an instant in time without additional
+/// > information. Conversion to an instant, if required, is implementation-
+/// > specific.
+/// >
+/// > ```toml
+/// > ldt1 = 1979-05-27T07:32:00
+/// > ldt2 = 1979-05-27T00:32:00.999999
+/// > ```
+///
+/// **3. Local Date**: If only `date` is given, `Datetime` corresponds to a
+/// [Local Date]; see the docs for [`Date`].
+///
+/// **4. Local Time**: If only `time` is given, `Datetime` corresponds to a
+/// [Local Time]; see the docs for [`Time`].
+///
+/// [TOML v1.0.0 spec]: https://toml.io/en/v1.0.0
+/// [Offset Date-Time]: https://toml.io/en/v1.0.0#offset-date-time
+/// [Local Date-Time]: https://toml.io/en/v1.0.0#local-date-time
+/// [Local Date]: https://toml.io/en/v1.0.0#local-date
+/// [Local Time]: https://toml.io/en/v1.0.0#local-time
 #[derive(PartialEq, Clone)]
 pub struct Datetime {
-    date: Option<Date>,
-    time: Option<Time>,
-    offset: Option<Offset>,
+    /// Optional date.
+    /// Required for: *Offset Date-Time*, *Local Date-Time*, *Local Date*.
+    pub date: Option<Date>,
+
+    /// Optional time.
+    /// Required for: *Offset Date-Time*, *Local Date-Time*, *Local Time*.
+    pub time: Option<Time>,
+
+    /// Optional offset.
+    /// Required for: *Offset Date-Time*.
+    pub offset: Option<Offset>,
 }
 
 /// Error returned from parsing a `Datetime` in the `FromStr` implementation.
@@ -43,25 +106,81 @@ pub struct DatetimeParseError {
 pub const FIELD: &str = "$__toml_private_datetime";
 pub const NAME: &str = "$__toml_private_Datetime";
 
+/// A parsed TOML date value
+///
+/// May be part of a [`Datetime`]. Alone, `Date` corresponds to a [Local Date].
+/// From the TOML v1.0.0 spec:
+///
+/// > If you include only the date portion of an RFC 3339 formatted date-time,
+/// > it will represent that entire day without any relation to an offset or
+/// > timezone.
+/// >
+/// > ```toml
+/// > ld1 = 1979-05-27
+/// > ```
+///
+/// [Local Date]: https://toml.io/en/v1.0.0#local-date
 #[derive(PartialEq, Clone)]
-struct Date {
-    year: u16,
-    month: u8,
-    day: u8,
+pub struct Date {
+    /// Year: four digits
+    pub year: u16,
+    /// Month: 1 to 12
+    pub month: u8,
+    /// Day: 1 to {28, 29, 30, 31} (based on month/year)
+    pub day: u8,
 }
 
+/// A parsed TOML time value
+///
+/// May be part of a [`Datetime`]. Alone, `Time` corresponds to a [Local Time].
+/// From the TOML v1.0.0 spec:
+///
+/// > If you include only the time portion of an RFC 3339 formatted date-time,
+/// > it will represent that time of day without any relation to a specific
+/// > day or any offset or timezone.
+/// >
+/// > ```toml
+/// > lt1 = 07:32:00
+/// > lt2 = 00:32:00.999999
+/// > ```
+/// >
+/// > Millisecond precision is required. Further precision of fractional
+/// > seconds is implementation-specific. If the value contains greater
+/// > precision than the implementation can support, the additional precision
+/// > must be truncated, not rounded.
+///
+/// [Local Time]: https://toml.io/en/v1.0.0#local-time
 #[derive(PartialEq, Clone)]
-struct Time {
-    hour: u8,
-    minute: u8,
-    second: u8,
-    nanosecond: u32,
+pub struct Time {
+    /// Hour: 0 to 23
+    pub hour: u8,
+    /// Minute: 0 to 59
+    pub minute: u8,
+    /// Second: 0 to {58, 59, 60} (based on leap second rules)
+    pub second: u8,
+    /// Nanosecond: 0 to 999_999_999
+    pub nanosecond: u32,
 }
 
+/// A parsed TOML time offset
+///
 #[derive(PartialEq, Clone)]
-enum Offset {
+pub enum Offset {
+    /// > A suffix which, when applied to a time, denotes a UTC offset of 00:00;
+    /// > often spoken "Zulu" from the ICAO phonetic alphabet representation of
+    /// > the letter "Z". --- [RFC 3339 section 2]
+    ///
+    /// [RFC 3339 section 2]: https://datatracker.ietf.org/doc/html/rfc3339#section-2
     Z,
-    Custom { hours: i8, minutes: u8 },
+
+    /// Offset between local time and UTC
+    Custom {
+        /// Hours: -12 to +12
+        hours: i8,
+
+        /// Minutes: 0 to 59
+        minutes: u8,
+    },
 }
 
 impl fmt::Debug for Datetime {

src/value.rs

@@ -13,7 +13,7 @@ use serde::de::IntoDeserializer;
 use serde::ser;
 
 use crate::datetime::{self, DatetimeFromString};
-pub use crate::datetime::{Datetime, DatetimeParseError};
+pub use crate::datetime::{Date, Datetime, DatetimeParseError, Offset, Time};
 
 pub use crate::map::{Entry, Map};