DateTime: API review feedback (#938)

Author: antkmsft

sdk/core/azure-core/inc/azure/core/datetime.hpp

@@ -8,7 +8,7 @@
 
 #pragma once
 
-#include <stdexcept>
+#include <chrono>
 #include <string>
 
 namespace Azure { namespace Core {
@@ -17,28 +17,25 @@ namespace Azure { namespace Core {
    */
   class DateTime {
   public:
-    /// A type that represents tick spans.
-    typedef uint64_t IntervalType;
-
-  private:
-    //  Number of seconds between 01-01-1970 and 01-01-1601.
-    static constexpr IntervalType WindowsToPosixOffsetSeconds = 11644473600LL;
+    /**
+     * @brief Units of measurement the difference between instances of @DateTime.
+     */
+    // 1 == 100 ns (1 / 10,000,000 of a second, 7 fractional digits).
+    typedef std::chrono::duration<int64_t, std::ratio<1, 10000000>> Duration;
 
-  public:
     /**
-     * @brief Defines the format applied to the fraction part from any @DateFormat
-     *
+     * @brief Defines the format applied to the fraction part of any @DateTime.
      */
     enum class TimeFractionFormat
     {
-      /// Decimals are not included when there are no decimals in the source Datetime and any zeros
-      /// from the right are also removed.
+      /// Include only meaningful fractional time digits, up to and excluding trailing zeroes.
       DropTrailingZeros,
 
-      /// Decimals are included for any Datetime.
+      /// Include all the fractional time digits up to maximum precision, even if the entire value
+      /// is zero.
       AllDigits,
 
-      /// Decimals are removed for any Datetime.
+      /// Drop all the fractional time digits.
       Truncate
     };
 
@@ -50,170 +47,193 @@ namespace Azure { namespace Core {
       /// RFC 1123.
       Rfc1123,
 
-      /// ISO 8601.
-      Iso8601,
+      /// RFC 3339.
+      Rfc3339,
     };
 
     /**
      * @brief Get the current UTC time.
      */
-    static DateTime UtcNow();
-
-    /// An invalid UTC timestamp value.
-    static constexpr IntervalType UtcTimestampInvalid = static_cast<IntervalType>(-1);
-
-    /**
-     * @brief Get seconds since Unix/POSIX time epoch at `01-01-1970 00:00:00`.
-     * If time is before epoch, @UtcTimestampInvalid is returned.
-     */
-    static IntervalType UtcTimestamp()
-    {
-      auto const seconds = UtcNow().ToInterval() / WindowsToPosixOffsetSeconds;
-      return (seconds >= WindowsToPosixOffsetSeconds) ? (seconds - WindowsToPosixOffsetSeconds)
-                                                      : UtcTimestampInvalid;
-    }
+    static DateTime Now();
 
     /**
-     * @brief Construct an uninitialized (!@IsInitialized()) instance of @DateTime.
+     * @brief Construct an instance of @DateTime.
+     *
+     * @param year Year.
+     * @param month Month.
+     * @param day Day.
+     * @param hour Hour.
+     * @param minute Minute.
+     * @param second Seconds.
+     *
+     * @throw std::invalid_argument If any parameter is invalid.
      */
-    DateTime() : m_interval(0) {}
+    explicit DateTime(
+        int16_t year,
+        int8_t month = 1,
+        int8_t day = 1,
+        int8_t hour = 0,
+        int8_t minute = 0,
+        int8_t second = 0);
 
     /**
      * @brief Create @DateTime from a string representing time in UTC in the specified format.
      *
-     * @param timeString A string with the date and time.
-     * @param format A format to which /p timeString adheres to.
+     * @param dateTime A string with the date and time.
+     * @param format A format to which \p dateTime string adheres to.
      *
-     * @return @DateTime that was constructed from the \p timeString; Uninitialized
-     * (!@IsInitialized()) @DateTime if parsing \p timeString was not successful.
+     * @return @DateTime that was constructed from the \p dateTime string.
      *
-     * @throw DateTimeException If \p format is not recognized.
+     * @throw std::invalid_argument If \p format is not recognized, or if parsing error.
      */
-    static DateTime FromString(
-        std::string const& timeString,
-        DateFormat format = DateFormat::Rfc1123);
+    static DateTime Parse(std::string const& dateTime, DateFormat format);
 
   private:
     /**
      * @brief Get a string representation of the @DateTime.
      *
      * @param format The representation format to use.
      * @param fractionFormat The format for the fraction part of the Datetime. Only supported by
-     * ISO8601
+     * RFC 3339.
      *
-     * @throw DateTimeException If year exceeds 9999, or if \p format is not recognized.
+     * @throw std::length_error If year exceeds 9999, or if \p format is not recognized.
      */
-    std::string ToString(DateFormat format, TimeFractionFormat fractionFormat) const;
+    std::string GetString(DateFormat format, TimeFractionFormat fractionFormat) const;
 
   public:
     /**
      * @brief Get a string representation of the @DateTime.
      *
      * @param format The representation format to use.
      *
-     * @throw DateTimeException If year exceeds 9999, or if \p format is not recognized.
+     * @throw std::length_error If year exceeds 9999, or if \p format is not recognized.
      */
-    std::string ToString(DateFormat format = DateFormat::Rfc1123) const
+    std::string GetString(DateFormat format) const
     {
-      return ToString(format, TimeFractionFormat::DropTrailingZeros);
+      return GetString(format, TimeFractionFormat::DropTrailingZeros);
     };
 
     /**
-     * @brief Get a string representation of the @DateTime formated with ISO8601.
+     * @brief Get a string representation of the @DateTime formatted with RFC 3339.
      *
-     * @param fractionFormat The format that is applied to the fraction part from the ISO8601 date.
+     * @param fractionFormat The format that is applied to the fraction part from the RFC 3339 date.
      *
-     * @throw DateTimeException If year exceeds 9999, or if \p fractionFormat is not recognized.
+     * @throw std::length_error If year exceeds 9999.
+     * @throw std::invalid_argument If \p format is not recognized.
      */
-    std::string ToIso8601String(TimeFractionFormat fractionFormat) const
+    std::string GetRfc3339String(TimeFractionFormat fractionFormat) const
     {
-      return ToString(DateFormat::Iso8601, fractionFormat);
+      return GetString(DateFormat::Rfc3339, fractionFormat);
     };
 
-    /// Get the integral time value.
-    IntervalType ToInterval() const { return m_interval; }
-
-    /// Subtract an interval from @DateTime.
-    DateTime operator-(IntervalType value) const { return DateTime(m_interval - value); }
+    /**
+     * @brief Add \p duration to this @DateTime.
+     * @param duration @Duration to add.
+     * @return Reference to this @DateTime.
+     */
+    DateTime& operator+=(Duration const& duration)
+    {
+      m_since1601 += duration;
+      return *this;
+    }
 
-    /// Add an interval to @DateTime.
-    DateTime operator+(IntervalType value) const { return DateTime(m_interval + value); }
+    /**
+     * @brief Subtract \p duration from this @DateTime.
+     * @param duration @Duration to subtract from this @DateTime.
+     * @return Reference to this @DateTime.
+     */
+    DateTime& operator-=(Duration const& duration)
+    {
+      m_since1601 -= duration;
+      return *this;
+    }
 
-    /// Compare two instances of @DateTime for equality.
-    bool operator==(DateTime dt) const { return m_interval == dt.m_interval; }
+    /**
+     * @brief Subtract @Duration from @DateTime.
+     * @param duration @Duration to subtract from this @DateTime.
+     * @return New DateTime representing subtraction result.
+     */
+    DateTime operator-(Duration const& duration) const { return DateTime(m_since1601 - duration); }
 
-    /// Compare two instances of @DateTime for inequality.
-    bool operator!=(const DateTime& dt) const { return !(*this == dt); }
+    /**
+     * @brief Add @Duration to @DateTime.
+     * @param duration @Duration to add to this @DateTime.
+     * @return New DateTime representing addition result.
+     */
+    DateTime operator+(Duration const& duration) const { return DateTime(m_since1601 + duration); }
 
-    /// Compare the chronological order of two @DateTime instances.
-    bool operator>(const DateTime& dt) const { return this->m_interval > dt.m_interval; }
+    /**
+     * @brief Get @Duration between two instances of @DateTime.
+     * @param other @DateTime to subtract from this @DateTime.
+     * @return @Duration between this @DateTime and the \p other.
+     */
+    Duration operator-(DateTime const& other) const { return m_since1601 - other.m_since1601; }
 
-    /// Compare the chronological order of two @DateTime instances.
-    bool operator<(const DateTime& dt) const { return this->m_interval < dt.m_interval; }
+    /**
+     * @brief Compare with \p other @DateTime for equality.
+     * @param other Other @DateTime to compare with.
+     * @return `true` if @DateTime instances are equal, `false` otherwise.
+     */
+    constexpr bool operator==(DateTime const& other) const
+    {
+      return m_since1601 == other.m_since1601;
+    }
 
-    /// Compare the chronological order of two @DateTime instances.
-    bool operator>=(const DateTime& dt) const { return this->m_interval >= dt.m_interval; }
+    /**
+     * @brief Compare with \p other @DateTime for inequality.
+     * @param other Other @DateTime to compare with.
+     * @return `true` if @DateTime instances are not equal, `false` otherwise.
+     */
+    constexpr bool operator!=(const DateTime& other) const { return !(*this == other); }
 
-    /// Compare the chronological order of two @DateTime instances.
-    bool operator<=(const DateTime& dt) const { return this->m_interval <= dt.m_interval; }
+    /**
+     * @brief Check if \p other @DateTime precedes this @DateTime chronologically.
+     * @param other @DateTime to compare with.
+     * @return `true` if the \p other @DateTime precedes this, `false` otherwise.
+     */
+    constexpr bool operator>(const DateTime& other) const { return !(*this <= other); }
 
-    /// Create an interval from milliseconds.
-    static IntervalType FromMilliseconds(unsigned int milliseconds)
+    /**
+     * @brief Check if \p other @DateTime is chronologically after this @DateTime.
+     * @param other @DateTime to compare with.
+     * @return `true` if the \p other @DateTime is chonologically after this @DateTime, `false`
+     * otherwise.
+     */
+    constexpr bool operator<(const DateTime& other) const
     {
-      return milliseconds * TicksPerMillisecond;
+      return this->m_since1601 < other.m_since1601;
     }
 
-    /// Create an interval from seconds.
-    static IntervalType FromSeconds(unsigned int seconds) { return seconds * TicksPerSecond; }
-
-    /// Create an interval from minutes.
-    static IntervalType FromMinutes(unsigned int minutes) { return minutes * TicksPerMinute; }
-
-    /// Create an interval from hours.
-    static IntervalType FromHours(unsigned int hours) { return hours * TicksPerHour; }
+    /**
+     * @brief Check if \p other @DateTime precedes this @DateTime chronologically, or is equal to
+     * it.
+     * @param other @DateTime to compare with.
+     * @return `true` if the \p other @DateTime precedes or is equal to this @DateTime, `false`
+     * otherwise.
+     */
+    constexpr bool operator>=(const DateTime& other) const { return !(*this < other); }
 
-    /// Create an interval from days.
-    static IntervalType FromDays(unsigned int days) { return days * TicksPerDay; }
+    /**
+     * @brief Check if \p other @DateTime is chronologically after or equal to this @DateTime.
+     * @param other @DateTime to compare with.
+     * @return `true` if the \p other @DateTime is chonologically after or equal to this @DateTime,
+     * `false` otherwise.
+     */
+    constexpr bool operator<=(const DateTime& other) const
+    {
+      return (*this == other) || (*this < other);
+    }
 
-    /// Checks whether this instance of @DateTime is initialized.
-    bool IsInitialized() const { return m_interval != 0; }
+    /**
+     * @brief Get this @DateTime representation as a @Duration from the start of the
+     * implementation-defined epoch.
+     * @return @Duration since the start of the implementation-defined epoch.
+     */
+    constexpr explicit operator Duration() const { return m_since1601; }
 
   private:
-    friend IntervalType operator-(DateTime t1, DateTime t2);
-
-    static constexpr IntervalType TicksPerMillisecond = static_cast<IntervalType>(10000);
-    static constexpr IntervalType TicksPerSecond = 1000 * TicksPerMillisecond;
-    static constexpr IntervalType TicksPerMinute = 60 * TicksPerSecond;
-    static constexpr IntervalType TicksPerHour = 60 * TicksPerMinute;
-    static constexpr IntervalType TicksPerDay = 24 * TicksPerHour;
-
     // Private constructor. Use static methods to create an instance.
-    DateTime(IntervalType interval) : m_interval(interval) {}
-
-    // Storing as hundreds of nanoseconds 10e-7, i.e. 1 here equals 100ns.
-    IntervalType m_interval;
-  };
-
-  inline DateTime::IntervalType operator-(DateTime t1, DateTime t2)
-  {
-    auto diff = (t1.m_interval - t2.m_interval);
-
-    // Round it down to seconds
-    diff /= DateTime::TicksPerSecond;
-
-    return static_cast<DateTime::IntervalType>(diff);
-  }
-
-  /**
-   * @brief An exception that gets thrown when @DateTime error occurs.
-   */
-  class DateTimeException : public std::runtime_error {
-  public:
-    /**
-     * @brief Construct with message string.
-     *
-     * @param msg Message string.
-     */
-    explicit DateTimeException(std::string const& msg) : std::runtime_error(msg) {}
+    explicit DateTime(Duration const& since1601) : m_since1601(since1601) {}
+    Duration m_since1601;
   };
 }} // namespace Azure::Core