RUST-1198 Support creating bson::DateTime from a given year/month/date/hour/minute/second/millisecond (#361)

Added a builder to support creating a `DateTime` from specified date and time arguments.

Author: sanav33

src/datetime.rs

@@ -1,3 +1,5 @@
+//! BSON DateTime
+
 use std::{
     convert::TryInto,
     error,
@@ -6,6 +8,8 @@ use std::{
     time::{Duration, SystemTime},
 };
 
+pub(crate) mod builder;
+pub use crate::datetime::builder::DateTimeBuilder;
 use time::format_description::well_known::Rfc3339;
 
 #[cfg(feature = "chrono-0_4")]
@@ -41,6 +45,18 @@ use serde_with::{DeserializeAs, SerializeAs};
 /// # }
 /// ```
 ///
+/// You may also construct this type from a given `year`, `month`, `day`, and optionally,
+/// an `hour`, `minute`, `second` and `millisecond`, which default to 0 if not explicitly set.
+///
+/// ```
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// let dt = bson::DateTime::builder().year(1998).month(2).day(12).minute(1).millisecond(23).build()?;
+/// let expected = bson::DateTime::parse_rfc3339_str("1998-02-12T00:01:00.023Z")?;
+/// assert_eq!(dt, expected);
+/// # Ok(())
+/// # }
+/// ```
+///
 /// This type differs from [`chrono::DateTime`] in that it serializes to and deserializes from a
 /// BSON datetime rather than an RFC 3339 formatted string. Additionally, in non-BSON formats, it
 /// will serialize to and deserialize from that format's equivalent of the
@@ -131,6 +147,15 @@ impl crate::DateTime {
         Self::from_millis(dt.timestamp_millis())
     }
 
+    /// Returns a builder used to construct a [`DateTime`] from a given year, month,
+    /// day, and optionally, an hour, minute, second and millisecond, which default to
+    /// 0 if not explicitly set.
+    ///
+    /// Note: You cannot call `build()` before setting at least the year, month and day.
+    pub fn builder() -> DateTimeBuilder {
+        DateTimeBuilder::default()
+    }
+
     /// Convert this [`DateTime`] to a [`chrono::DateTime<Utc>`].
     ///
     /// Note: Not every BSON datetime can be represented as a [`chrono::DateTime`]. For such dates,

src/datetime/builder.rs

@@ -0,0 +1,187 @@
+use super::*;
+use std::convert::TryFrom;
+use time::Date;
+
+/// Builder for constructing a BSON [`DateTime`]
+pub struct DateTimeBuilder<Y = NoYear, M = NoMonth, D = NoDay> {
+    pub(crate) year: Y,
+    pub(crate) month: M,
+    pub(crate) day: D,
+
+    pub(crate) hour: Option<u8>,
+    pub(crate) minute: Option<u8>,
+    pub(crate) second: Option<u8>,
+    pub(crate) millisecond: Option<u16>,
+}
+
+impl Default for DateTimeBuilder {
+    fn default() -> Self {
+        Self {
+            year: NoYear,
+            month: NoMonth,
+            day: NoDay,
+            hour: None,
+            minute: None,
+            second: None,
+            millisecond: None,
+        }
+    }
+}
+
+pub struct Year(i32);
+pub struct NoYear;
+
+pub struct Month(u8);
+pub struct NoMonth;
+
+pub struct Day(u8);
+pub struct NoDay;
+
+impl<M, D> DateTimeBuilder<NoYear, M, D> {
+    /// Sets the year for the builder instance. Years between ±9999 inclusive are valid.
+    /// If the specified value is out of range, calling the `build()` method will return
+    /// an error.
+    ///
+    /// Note: This is a required method. You will not be able to call `build()` before calling
+    /// this method.
+    pub fn year(self, y: i32) -> DateTimeBuilder<Year, M, D> {
+        let Self {
+            year: _,
+            month,
+            day,
+            hour,
+            minute,
+            second,
+            millisecond,
+        } = self;
+        DateTimeBuilder {
+            year: Year(y),
+            month,
+            day,
+            hour,
+            minute,
+            second,
+            millisecond,
+        }
+    }
+}
+
+impl<Y, D> DateTimeBuilder<Y, NoMonth, D> {
+    /// Sets the month for the builder instance. Maps months as 1-January to 12-December.
+    /// If the specified value is out of range, calling the `build()` method will return
+    /// an error.
+    ///
+    /// Note: This is a required method. You will not be able to call `build()` before calling
+    /// this method.
+    pub fn month(self, m: u8) -> DateTimeBuilder<Y, Month, D> {
+        let Self {
+            year,
+            month: _,
+            day,
+            hour,
+            minute,
+            second,
+            millisecond,
+        } = self;
+        DateTimeBuilder {
+            year,
+            month: Month(m),
+            day,
+            hour,
+            minute,
+            second,
+            millisecond,
+        }
+    }
+}
+
+impl<Y, M> DateTimeBuilder<Y, M, NoDay> {
+    /// Sets the day for the builder instance. Values in the range `1..=31` are valid.
+    /// If the specified value does not exist for the provided month/year or is out of range,
+    /// calling the `build()` method will return an error.
+    ///
+    /// Note: This is a required method. You will not be able to call `build()` before calling
+    /// this method.
+    pub fn day(self, d: u8) -> DateTimeBuilder<Y, M, Day> {
+        let Self {
+            year,
+            month,
+            day: _,
+            hour,
+            minute,
+            second,
+            millisecond,
+        } = self;
+        DateTimeBuilder {
+            year,
+            month,
+            day: Day(d),
+            hour,
+            minute,
+            second,
+            millisecond,
+        }
+    }
+}
+
+impl<Y, M, D> DateTimeBuilder<Y, M, D> {
+    /// Sets the hour (24-hour format) for the builder instance. Values must be in the range
+    /// `0..=23`. If the specified value is out of range, calling the `build()` method will
+    /// return an error.
+    ///
+    /// Note: This is an optional method. The hour will default to 0 if not explicitly set.
+    pub fn hour(mut self, hour: u8) -> DateTimeBuilder<Y, M, D> {
+        self.hour = Some(hour);
+        self
+    }
+
+    /// Sets the minute for the builder instance. Values must be in the range `0..=59`.
+    /// If the specified value is out of range, calling the `build()` method will return an error.
+    ///
+    /// Note: This is an optional method. The minute will default to 0 if not explicitly set.
+    pub fn minute(mut self, minute: u8) -> DateTimeBuilder<Y, M, D> {
+        self.minute = Some(minute);
+        self
+    }
+
+    /// Sets the second for the builder instance. Values must be in range `0..=59`.
+    /// If the specified value is out of range, calling the `build()` method will return an error.
+    ///
+    /// Note: This is an optional method. The second will default to 0 if not explicitly set.
+    pub fn second(mut self, second: u8) -> DateTimeBuilder<Y, M, D> {
+        self.second = Some(second);
+        self
+    }
+
+    /// Sets the millisecond for the builder instance. Values must be in the range `0..=999`.
+    /// If the specified value is out of range, calling the `build()` method will return an error.
+    ///
+    /// Note: This is an optional method. The millisecond will default to 0 if not explicitly set.
+    pub fn millisecond(mut self, millisecond: u16) -> DateTimeBuilder<Y, M, D> {
+        self.millisecond = Some(millisecond);
+        self
+    }
+}
+
+impl DateTimeBuilder<Year, Month, Day> {
+    /// Convert a builder with a specified year, month, day, and optionally, an hour, minute, second
+    /// and millisecond to a [`DateTime`].
+    ///
+    /// Note: You cannot call `build()` before setting at least the year, month and day.
+    pub fn build(self) -> Result<DateTime> {
+        let err = |e: time::error::ComponentRange| Error::InvalidTimestamp {
+            message: e.to_string(),
+        };
+        let month = time::Month::try_from(self.month.0).map_err(err)?;
+        let dt = Date::from_calendar_date(self.year.0, month, self.day.0)
+            .map_err(err)?
+            .with_hms_milli(
+                self.hour.unwrap_or(0),
+                self.minute.unwrap_or(0),
+                self.second.unwrap_or(0),
+                self.millisecond.unwrap_or(0),
+            )
+            .map_err(err)?;
+        Ok(DateTime::from_time_private(dt.assume_utc()))
+    }
+}

src/tests/modules/bson.rs

@@ -16,6 +16,7 @@ use crate::{
     Regex,
     Timestamp,
 };
+
 use serde_json::{json, Value};
 
 #[test]
@@ -363,6 +364,46 @@ fn from_external_datetime() {
     }
 }
 
+#[test]
+fn from_datetime_builder() {
+    {
+        let dt = DateTime::builder()
+            .year(2022)
+            .month(9)
+            .day(15)
+            .minute(2)
+            .millisecond(1)
+            .build();
+        assert!(dt.is_ok());
+        assert_eq!(
+            DateTime::from_time_0_3(time::macros::datetime!(2022 - 09 - 15 00:02:00.001 UTC)),
+            dt.unwrap()
+        );
+    }
+
+    {
+        let dt = DateTime::builder()
+            .year(2022)
+            .month(18)
+            .day(15)
+            .minute(2)
+            .millisecond(1)
+            .build();
+        assert!(dt.is_err());
+    }
+
+    {
+        let dt = DateTime::builder()
+            .year(2022)
+            .day(15)
+            .month(18)
+            .minute(83)
+            .millisecond(1)
+            .build();
+        assert!(dt.is_err());
+    }
+}
+
 #[test]
 fn system_time() {
     let _guard = LOCK.run_concurrently();