From ccd6b9de25d6ca0406372f25a5f135ce836e2a8d Mon Sep 17 00:00:00 2001
From: Bradley White <14679271+devbww@users.noreply.github.com>
Date: Wed, 24 Apr 2024 23:09:23 -0400
Subject: [PATCH 1/4] feat(spanner): add a representation for the Spanner
 INTERVAL

Add a C++ type, `spanner::Interval`, to model the Spanner
`INTERVAL`: the difference between two date/time values.

Basic operations and string conversions are provided. Extra
operations involving `Date` and `Timestamp` values are
upcoming.

Integration of `Interval` with `spanner::Value` awaits the
publication of the `google.spanner.v1.TypeCode::INTERVAL`
enum value.
---
 google/cloud/spanner/CMakeLists.txt           |   3 +
 .../spanner/google_cloud_cpp_spanner.bzl      |   2 +
 google/cloud/spanner/interval.cc              | 367 ++++++++++++++++++
 google/cloud/spanner/interval.h               | 136 +++++++
 google/cloud/spanner/interval_test.cc         | 205 ++++++++++
 .../spanner/spanner_client_unit_tests.bzl     |   1 +
 6 files changed, 714 insertions(+)
 create mode 100644 google/cloud/spanner/interval.cc
 create mode 100644 google/cloud/spanner/interval.h
 create mode 100644 google/cloud/spanner/interval_test.cc

diff --git a/google/cloud/spanner/CMakeLists.txt b/google/cloud/spanner/CMakeLists.txt
index 728b78a125bf0..3f6ca16b31184 100644
--- a/google/cloud/spanner/CMakeLists.txt
+++ b/google/cloud/spanner/CMakeLists.txt
@@ -171,6 +171,8 @@ add_library(
     internal/transaction_impl.cc
     internal/transaction_impl.h
     internal/tuple_utils.h
+    interval.cc
+    interval.h
     json.h
     keys.cc
     keys.h
@@ -481,6 +483,7 @@ function (spanner_client_define_tests)
         internal/status_utils_test.cc
         internal/transaction_impl_test.cc
         internal/tuple_utils_test.cc
+        interval_test.cc
         json_test.cc
         keys_test.cc
         mutations_test.cc
diff --git a/google/cloud/spanner/google_cloud_cpp_spanner.bzl b/google/cloud/spanner/google_cloud_cpp_spanner.bzl
index f80303ed18afd..6e6e882317f5e 100644
--- a/google/cloud/spanner/google_cloud_cpp_spanner.bzl
+++ b/google/cloud/spanner/google_cloud_cpp_spanner.bzl
@@ -93,6 +93,7 @@ google_cloud_cpp_spanner_hdrs = [
     "internal/status_utils.h",
     "internal/transaction_impl.h",
     "internal/tuple_utils.h",
+    "interval.h",
     "json.h",
     "keys.h",
     "mutations.h",
@@ -183,6 +184,7 @@ google_cloud_cpp_spanner_srcs = [
     "internal/spanner_tracing_stub.cc",
     "internal/status_utils.cc",
     "internal/transaction_impl.cc",
+    "interval.cc",
     "keys.cc",
     "mutations.cc",
     "numeric.cc",
diff --git a/google/cloud/spanner/interval.cc b/google/cloud/spanner/interval.cc
new file mode 100644
index 0000000000000..8626a187e8642
--- /dev/null
+++ b/google/cloud/spanner/interval.cc
@@ -0,0 +1,367 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "google/cloud/spanner/interval.h"
+#include "google/cloud/internal/absl_str_cat_quiet.h"
+#include "google/cloud/internal/make_status.h"
+#include "absl/strings/ascii.h"
+#include "absl/strings/match.h"
+#include "absl/strings/numbers.h"
+#include "absl/strings/string_view.h"
+#include "absl/strings/strip.h"
+#include <cmath>
+#include <cstdint>
+#include <functional>
+#include <iomanip>
+#include <ostream>
+#include <sstream>
+#include <string>
+#include <utility>
+
+namespace google {
+namespace cloud {
+namespace spanner {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+namespace {
+
+// Interval factories for quantity units.
+struct {
+  absl::string_view name;
+  std::function<Interval(std::int32_t)> factory;
+} const kUnitFactories[] = {
+    // "days" is first so that it is chosen when unit is empty.
+    {"days", [](auto n) { return Interval(0, 0, n); }},
+
+    // "minutes" comes before other "m"s so it is chosen for, say, "6m".
+    {"minutes", [](auto n) { return Interval(absl::Minutes(n)); }},
+
+    {"microseconds", [](auto n) { return Interval(absl::Microseconds(n)); }},
+    {"milliseconds", [](auto n) { return Interval(absl::Milliseconds(n)); }},
+    {"seconds", [](auto n) { return Interval(absl::Seconds(n)); }},
+    {"hours", [](auto n) { return Interval(absl::Hours(n)); }},
+    {"weeks", [](auto n) { return Interval(0, 0, n * 7); }},
+    {"months", [](auto n) { return Interval(0, n, 0); }},
+    {"years", [](auto n) { return Interval(n, 0, 0); }},
+    {"decades", [](auto n) { return Interval(n * 10, 0, 0); }},
+    {"century", [](auto n) { return Interval(n * 100, 0, 0); }},
+    {"centuries", [](auto n) { return Interval(n * 100, 0, 0); }},
+    {"millennium", [](auto n) { return Interval(n * 1000, 0, 0); }},
+    {"millennia", [](auto n) { return Interval(n * 1000, 0, 0); }},
+};
+
+// Interval comparison is done by logically combining the fields into a
+// single value by assuming that 1 month == 30 days and 1 day == 24 hours,
+// and by rounding to a microsecond boundary.
+void Normalize(std::int64_t& months, std::int64_t& days,
+               absl::Duration& offset) {
+  auto const precision = absl::Microseconds(1);
+  offset += ((offset < absl::ZeroDuration()) ? -precision : precision) / 2,
+  offset = absl::Trunc(offset, precision);
+  days += absl::IDivDuration(offset, absl::Hours(24), &offset);
+  if (offset < absl::ZeroDuration()) {
+    offset += absl::Hours(24);
+    days -= 1;
+  }
+  months += days / 30;
+  days %= 30;
+  if (days < 0) {
+    days += 30;
+    months -= 1;
+  }
+}
+
+template <template <typename> class C>
+bool Cmp(std::int64_t a_months, std::int64_t a_days, absl::Duration a_offset,
+         std::int64_t b_months, std::int64_t b_days, absl::Duration b_offset) {
+  Normalize(a_months, a_days, a_offset);
+  Normalize(b_months, b_days, b_offset);
+  if (a_months != b_months) return C<std::int64_t>()(a_months, b_months);
+  if (a_days != b_days) return C<std::int64_t>()(a_days, b_days);
+  return C<absl::Duration>()(a_offset, b_offset);
+}
+
+// "y years m months d days H:M:S.F"
+std::string Stringify(std::int32_t months, std::int32_t days,
+                      absl::Duration offset) {
+  std::ostringstream ss;
+  std::int32_t years = months / 12;
+  months %= 12;
+  if (months < 0) {
+    months += 12;
+    years -= 1;
+  }
+  auto plural = [](std::int32_t v) { return std::abs(v) == 1 ? "" : "s"; };
+  char const* sep = "";
+  if (years != 0) {
+    ss << sep << years << " year" << plural(years);
+    sep = " ";
+  }
+  if (months != 0) {
+    ss << sep << months << " month" << plural(months);
+    sep = " ";
+  }
+  if (days != 0) {
+    ss << sep << days << " day" << plural(days);
+    sep = " ";
+  }
+  if (offset == absl::ZeroDuration()) {
+    if (*sep == '\0') ss << "0 days";
+  } else {
+    char const* sign = (offset < absl::ZeroDuration()) ? "-" : "";
+    offset = absl::AbsDuration(offset);
+    auto hour = absl::IDivDuration(offset, absl::Hours(1), &offset);
+    auto min = absl::IDivDuration(offset, absl::Minutes(1), &offset);
+    auto sec = absl::IDivDuration(offset, absl::Seconds(1), &offset);
+    ss << sep << sign << std::setfill('0') << std::setw(2) << hour;
+    ss << ':' << std::setfill('0') << std::setw(2) << min;
+    ss << ':' << std::setfill('0') << std::setw(2) << sec;
+    if (auto ns = absl::ToInt64Nanoseconds(offset)) {
+      ss << '.' << std::setfill('0');
+      if (ns % 1000000 == 0) {
+        ss << std::setw(3) << ns / 1000000;
+      } else if (ns % 1000 == 0) {
+        ss << std::setw(6) << ns / 1000;
+      } else {
+        ss << std::setw(9) << ns;
+      }
+    }
+  }
+  return std::move(ss).str();
+}
+
+class Parser {
+ public:
+  explicit Parser(std::string s) : s_(std::move(s)) {}
+
+  /**
+   * https://www.postgresql.org/docs/current/datatype-datetime.html
+   *
+   * [@] quantity unit [quantity unit...] [direction]
+   *
+   * where quantity is a number (possibly signed); unit is microsecond,
+   * millisecond, second, minute, hour, day, week, month, year, decade,
+   * century, millennium, or abbreviations or plurals of these units;
+   * direction can be ago or empty. The at sign (@) is optional noise.
+   *
+   * The amounts of the different units are implicitly added with
+   * appropriate sign accounting. ago negates all the fields.
+   *
+   * Quantities of days, hours, minutes, and seconds can be specified
+   * without explicit unit markings. For example, '1 12:59:10' is read
+   * the same as '1 day 12 hours 59 min 10 sec'.
+   *
+   * Also, a combination of years and months can be specified with a
+   * dash; for example '200-10' is read the same as '200 years 10 months'.
+   */
+  StatusOr<Interval> Parse();
+
+ private:
+  static void ConsumeSpaces(absl::string_view& s) {
+    while (!s.empty() && absl::ascii_isspace(s.front())) s.remove_prefix(1);
+  }
+
+  static void ConsumeInteger(absl::string_view& s) {
+    while (!s.empty() && absl::ascii_isdigit(s.front())) s.remove_prefix(1);
+  }
+
+  static absl::string_view ConsumeSign(absl::string_view& s) {
+    auto t = s;
+    if (!absl::ConsumePrefix(&s, "-")) absl::ConsumePrefix(&s, "+");
+    return t.substr(0, t.size() - s.size());
+  }
+
+  static absl::string_view ConsumeWord(absl::string_view& s) {
+    auto t = s;
+    while (!s.empty() && absl::ascii_isalpha(s.front())) s.remove_prefix(1);
+    return t.substr(0, t.size() - s.size());
+  }
+
+  static bool ParseDouble(absl::string_view& s, double& d, bool allow_sign) {
+    auto t = s;
+    if (allow_sign) ConsumeSign(t);
+    ConsumeInteger(t);
+    if (!absl::ConsumePrefix(&t, ".")) return false;
+    ConsumeInteger(t);
+    auto len = s.size() - t.size();
+    if (!absl::SimpleAtod(s.substr(0, len), &d)) return false;
+    s.remove_prefix(len);
+    return true;
+  }
+
+  template <typename T>
+  static bool ParseInteger(absl::string_view& s, T& n, bool allow_sign) {
+    auto t = s;
+    if (allow_sign) ConsumeSign(t);
+    ConsumeInteger(t);
+    auto len = s.size() - t.size();
+    if (!absl::SimpleAtoi(s.substr(0, len), &n)) return false;
+    s.remove_prefix(len);
+    return true;
+  }
+
+  static bool ParseYearMonth(absl::string_view& s, Interval& intvl) {
+    auto t = s;
+    std::int32_t year;
+    if (!ParseInteger(t, year, true)) return false;
+    if (!absl::ConsumePrefix(&t, "-")) return false;
+    std::int32_t month;
+    if (!ParseInteger(t, month, false)) return false;
+    intvl = Interval(year, month, 0);
+    s.remove_prefix(s.size() - t.size());
+    return true;
+  }
+
+  static bool ParseHourMinuteSecond(absl::string_view& s, Interval& intvl) {
+    auto t = s;
+    auto d = absl::ZeroDuration();
+    auto sign = ConsumeSign(t);
+    std::int64_t hour;
+    if (!ParseInteger(t, hour, false)) return false;
+    d += absl::Hours(hour);
+    if (!absl::ConsumePrefix(&t, ":")) return false;
+    std::int64_t minute;
+    if (!ParseInteger(t, minute, false)) return false;
+    d += absl::Minutes(minute);
+    if (!absl::ConsumePrefix(&t, ":")) return false;
+    double second;
+    if (ParseDouble(t, second, false)) {
+      d += absl::Seconds(second);
+    } else {
+      std::int64_t second;
+      if (!ParseInteger(t, second, false)) return false;
+      d += absl::Seconds(second);
+    }
+    intvl = Interval(sign == "-" ? -d : d);
+    s.remove_prefix(s.size() - t.size());
+    return true;
+  }
+
+  static Interval Unit(absl::string_view& s, std::int32_t n) {
+    auto t = s;
+    auto unit = ConsumeWord(t);
+    if (unit.size() > 1) absl::ConsumeSuffix(&unit, "s");  // unpluralize
+    for (auto const& factory : kUnitFactories) {
+      if (absl::StartsWith(factory.name, unit)) {
+        s.remove_prefix(s.size() - t.size());
+        return factory.factory(n);
+      }
+    }
+    return Interval(0, 0, n);  // default to days without removing unit
+  }
+
+  std::string s_;
+};
+
+StatusOr<Interval> Parser::Parse() {
+  Interval intvl;
+  auto s = absl::string_view(s_);
+
+  ConsumeSpaces(s);
+  if (absl::ConsumePrefix(&s, "@")) {
+    ConsumeSpaces(s);
+  }
+
+  for (;; ConsumeSpaces(s)) {
+    Interval vi;
+    if (ParseYearMonth(s, vi)) {
+      intvl += vi;
+      continue;
+    }
+    if (ParseHourMinuteSecond(s, vi)) {
+      intvl += vi;
+      continue;
+    }
+    double vf;
+    if (ParseDouble(s, vf, true)) {
+      ConsumeSpaces(s);
+      intvl += Unit(s, 1) * vf;
+      continue;
+    }
+    std::int32_t vn;
+    if (ParseInteger(s, vn, true)) {
+      ConsumeSpaces(s);
+      intvl += Unit(s, vn);
+      continue;
+    }
+    break;  // no match
+  }
+
+  if (absl::ConsumePrefix(&s, "ago")) {
+    ConsumeSpaces(s);
+    intvl = -intvl;
+  }
+
+  if (!s.empty()) {
+    return internal::InvalidArgumentError(
+        absl::StrCat("\"", s_, "\": Syntax error at \"", s.substr(0, 5), "\""),
+        GCP_ERROR_INFO());
+  }
+  return intvl;
+}
+
+}  // namespace
+
+bool operator==(Interval const& a, Interval const& b) {
+  return Cmp<std::equal_to>(a.months_, a.days_, a.offset_,  //
+                            b.months_, b.days_, b.offset_);
+}
+
+bool operator<(Interval const& a, Interval const& b) {
+  return Cmp<std::less>(a.months_, a.days_, a.offset_,  //
+                        b.months_, b.days_, b.offset_);
+}
+
+Interval Interval::operator-() const {
+  Interval intvl;
+  intvl.months_ = -months_;
+  intvl.days_ = -days_;
+  intvl.offset_ = -offset_;
+  return intvl;
+}
+
+Interval& Interval::operator+=(Interval const& intvl) {
+  months_ += intvl.months_;
+  days_ += intvl.days_;
+  offset_ += intvl.offset_;
+  return *this;
+}
+
+Interval& Interval::operator*=(double d) {
+  // Fractional results only flow down into smaller units. Nothing ever
+  // carries up into larger units. This means that '1 month' / 2 becomes
+  // '15 days, but '1 month 15 days' * 3 is '3 months 45 days'.
+  double i_months;
+  double f_months = std::modf(months_ * d, &i_months);
+  months_ = static_cast<std::int32_t>(i_months);
+  double i_days;
+  double f_days = std::modf(days_ * d + f_months * 30, &i_days);
+  days_ = static_cast<std::int32_t>(i_days);
+  offset_ *= d;
+  offset_ += absl::Hours(f_days * 24);
+  return *this;
+}
+
+Interval::operator std::string() const {
+  return Stringify(months_, days_, offset_);
+}
+
+StatusOr<Interval> MakeInterval(absl::string_view s) {
+  return Parser(absl::AsciiStrToLower(s)).Parse();
+}
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace spanner
+}  // namespace cloud
+}  // namespace google
diff --git a/google/cloud/spanner/interval.h b/google/cloud/spanner/interval.h
new file mode 100644
index 0000000000000..49f1c97a676cd
--- /dev/null
+++ b/google/cloud/spanner/interval.h
@@ -0,0 +1,136 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_INTERVAL_H
+#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_INTERVAL_H
+
+#include "google/cloud/spanner/version.h"
+#include "google/cloud/status_or.h"
+#include "absl/strings/string_view.h"
+#include "absl/time/time.h"
+#include <cstdint>
+#include <iosfwd>
+#include <string>
+
+namespace google {
+namespace cloud {
+namespace spanner {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+/**
+ * A representation of the Spanner INTERVAL type: The difference between
+ * two date/time values.
+ *
+ * @see https://cloud.google.com/spanner/docs/data-types#interval_type
+ */
+class Interval {
+ public:
+  /// Default construction yields a zero-length interval.
+  Interval() : Interval(0, 0, 0) {}
+
+  Interval(std::int32_t years, std::int32_t months, std::int32_t days,
+           absl::Duration offset = absl::ZeroDuration())
+      : Interval((years * 12) + months, days, offset) {}
+
+  explicit Interval(absl::Duration offset) : Interval(0, 0, offset) {}
+
+  /// @name Regular value type, supporting copy, assign, move.
+  ///@{
+  Interval(Interval&&) = default;
+  Interval& operator=(Interval&&) = default;
+  Interval(Interval const&) = default;
+  Interval& operator=(Interval const&) = default;
+  ///@}
+
+  /// @name Relational operators
+  ///
+  /// Beware: Interval comparisons assume that 1 month == 30 days, and
+  /// 1 day == 24*60*60 seconds. This may lead to counterintuitive results.
+  /// It also means different Interval representations can compare equal,
+  /// e.g., Interval(0, 0, 1) == Interval(absl::Hours(24)).  Also note
+  /// that offsets are rounded to 1-microsecond boundaries during
+  /// comparisons (halfway cases rounding away from zero).
+  ///@{
+  friend bool operator==(Interval const& a, Interval const& b);
+  friend bool operator!=(Interval const& a, Interval const& b) {
+    return !(a == b);
+  }
+  friend bool operator<(Interval const& a, Interval const& b);
+  friend bool operator<=(Interval const& a, Interval const& b) {
+    return !(b < a);
+  }
+  friend bool operator>=(Interval const& a, Interval const& b) {
+    return !(a < b);
+  }
+  friend bool operator>(Interval const& a, Interval const& b) {
+    return (b < a);
+  }
+  ///@}
+
+  /// @name Arithmetic operators
+  ///
+  /// Beware: Fractional multiplication similarly assumes 30-days months
+  /// and 24-hour days, and may lead to counterintuitive results.
+  ///@{
+  Interval operator-() const;
+  Interval& operator+=(Interval const&);
+  Interval& operator-=(Interval const& intvl) {
+    *this += -intvl;
+    return *this;
+  }
+  Interval& operator*=(double);
+  Interval& operator/=(double d) {
+    *this *= 1.0 / d;
+    return *this;
+  }
+  ///@}
+
+  /// @name Conversion to a string using "intervalstyle == postgres".
+  explicit operator std::string() const;
+
+  /// @name Output streaming
+  friend std::ostream& operator<<(std::ostream& os, Interval intvl) {
+    return os << std::string(intvl);
+  }
+
+ private:
+  Interval(std::int32_t months, std::int32_t days, absl::Duration offset)
+      : months_(months), days_(days), offset_(offset) {}
+
+  std::int32_t months_;
+  std::int32_t days_;
+  absl::Duration offset_;
+};
+
+/// @name Binary operators
+///@{
+inline Interval operator+(Interval lhs, Interval rhs) { return lhs += rhs; }
+inline Interval operator-(Interval lhs, Interval rhs) { return lhs -= rhs; }
+inline Interval operator*(Interval lhs, double rhs) { return lhs *= rhs; }
+inline Interval operator*(double lhs, Interval rhs) { return rhs *= lhs; }
+inline Interval operator/(Interval lhs, double rhs) { return lhs /= rhs; }
+///@}
+
+/**
+ * Construct an `Interval` from a string. At least handles the format
+ * produced by `Interval::operator std::string()`.
+ */
+StatusOr<Interval> MakeInterval(absl::string_view);
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace spanner
+}  // namespace cloud
+}  // namespace google
+
+#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_INTERVAL_H
diff --git a/google/cloud/spanner/interval_test.cc b/google/cloud/spanner/interval_test.cc
new file mode 100644
index 0000000000000..e3a6020609fdd
--- /dev/null
+++ b/google/cloud/spanner/interval_test.cc
@@ -0,0 +1,205 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "google/cloud/spanner/interval.h"
+#include "google/cloud/testing_util/status_matchers.h"
+#include <gtest/gtest.h>
+#include <limits>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace google {
+namespace cloud {
+namespace spanner {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+namespace {
+
+TEST(Interval, RegularSemantics) {
+  Interval const intvl(0, 1, 2, absl::Hours(3));
+
+  Interval const copy1(intvl);
+  EXPECT_EQ(copy1, intvl);
+
+  Interval const copy2 = intvl;
+  EXPECT_EQ(copy2, intvl);
+
+  Interval assign;
+  assign = intvl;
+  EXPECT_EQ(assign, intvl);
+}
+
+// https://gist.github.com/henryivesjones/ebd653acbf61cb408380a49659e2be97
+// is the source of some of the relational/arithmetic test cases.
+
+TEST(Interval, RelationalOperators) {
+  EXPECT_EQ(Interval(), Interval());
+
+  EXPECT_LT(Interval(0, 1, 0), Interval(0, 2, 0));
+  EXPECT_EQ(Interval(0, 1, 30), Interval(0, 2, 0));
+  EXPECT_GT(Interval(0, 0, 365), Interval(1, 0, 0));
+  EXPECT_GT(Interval(0, 0, 52 * 7), Interval(1, 0, 0));
+
+  EXPECT_EQ(Interval(0, 2, -90, -absl::Hours(12)),
+            Interval(0, -1, -1, absl::Hours(12)));
+
+  // Check microsecond rounding.
+  EXPECT_EQ(Interval(absl::Microseconds(1.25)),
+            Interval(absl::Microseconds(1)));
+  EXPECT_EQ(Interval(-absl::Microseconds(1.25)),
+            Interval(-absl::Microseconds(1)));
+  EXPECT_EQ(Interval(absl::Microseconds(1.5)), Interval(absl::Microseconds(2)));
+  EXPECT_EQ(Interval(-absl::Microseconds(1.5)),
+            Interval(-absl::Microseconds(2)));
+
+  // Check that the logical value of an Interval used during comparison
+  // is able to represent values greater that (2^63-1) nanoseconds.
+  auto const max64 = std::numeric_limits<std::int64_t>::max();
+  EXPECT_GT(Interval(296, 6, 12), Interval(absl::Nanoseconds(max64)));
+}
+
+TEST(Interval, ArithmeticOperators) {
+  // Negation.
+  EXPECT_EQ(-Interval(), Interval());
+  EXPECT_EQ(-Interval(0, 10, 11, absl::Hours(12)),
+            Interval(0, -10, -11, -absl::Hours(12)));
+
+  // Addition/subtraction.
+  EXPECT_EQ(Interval(0, 1, 0) + Interval(0, 2, 0), Interval(0, 3, 0));
+  EXPECT_EQ(Interval(1, 0, 0, absl::Hours(24)) + Interval(1, 0, 3),
+            Interval(2, 0, 3, absl::Hours(24)));
+  EXPECT_EQ(Interval(1, 0, 1) - Interval(absl::Hours(24)),
+            Interval(1, 0, 1, -absl::Hours(24)));
+  EXPECT_EQ(Interval(0, 11, 0) + Interval(0, 1, 1), Interval(1, 0, 1));
+  EXPECT_EQ(Interval(absl::Hours(2) + absl::Minutes(50)) +
+                Interval(absl::Minutes(10)),
+            Interval(absl::Hours(3)));
+  EXPECT_EQ(Interval(absl::Hours(2) + absl::Minutes(50)) -
+                Interval(absl::Minutes(50)),
+            Interval(absl::Hours(2)));
+
+  // Multiplication/division.
+  EXPECT_EQ(Interval(0, 1, 0) * 2, Interval(0, 2, 0));
+  EXPECT_EQ(Interval(1, 6, 0) * 2, Interval(3, 0, 0));
+  EXPECT_EQ(Interval(absl::Hours(5) + absl::Minutes(5)) * 2,
+            Interval(absl::Hours(10) + absl::Minutes(10)));
+  EXPECT_EQ(Interval(0, 0, 15, absl::Hours(24)) * 3,
+            Interval(0, 1, 15, absl::Hours(72)));
+  EXPECT_EQ(Interval(0, 1, 15) * 3, Interval(0, 3, 45));
+  EXPECT_EQ(Interval(0, 1, 15) * 12, Interval(1, 0, 180));
+  EXPECT_EQ(Interval(0, 1, 0) / 30, Interval(0, 0, 1));
+  EXPECT_EQ(Interval(1, 0, 0) / 365, Interval(absl::Hours(24) * (360.0 / 365)));
+  EXPECT_EQ(Interval(1, 0, 0) / 12, Interval(0, 1, 0));
+  EXPECT_EQ(Interval(0, 1, 0) / 4, Interval(0, 0, 7, absl::Hours(12)));
+  EXPECT_EQ(Interval(0, 1, 0) * 0.5, Interval(0, 0, 15));
+  EXPECT_EQ(Interval(absl::Minutes(1)) * 0.5, Interval(absl::Seconds(30)));
+  EXPECT_EQ(Interval(0, 3, 30) / 30, Interval(0, 0, 4));
+  EXPECT_EQ(Interval(absl::Milliseconds(1001)) / 1'000'000 * 1'000,
+            Interval(absl::Microseconds(1001)));
+  EXPECT_EQ(Interval(absl::Minutes(1)) * 600, Interval(absl::Hours(10)));
+}
+
+TEST(Interval, Range) {
+  auto huge = Interval(178'000'000, 0, 0);
+  EXPECT_LT(-huge, huge);
+  EXPECT_EQ(std::string(huge), "178000000 years");
+  EXPECT_EQ(std::string(-huge), "-178000000 years");
+}
+
+TEST(Interval, RoundTrip) {
+  std::vector<Interval> test_cases = {
+      Interval(),
+      Interval(1, 0, 0),
+      Interval(0, 2, 0),
+      Interval(0, 2, 3),
+      Interval(absl::Hours(4)),
+      Interval(absl::Minutes(5)),
+      Interval(absl::Seconds(6)),
+      Interval(absl::Seconds(7.5)),
+  };
+
+  for (auto const& tc : test_cases) {
+    auto intvl = MakeInterval(std::string(tc));
+    EXPECT_STATUS_OK(intvl) << tc;
+    if (intvl) {
+      EXPECT_EQ(*intvl, tc);
+    }
+    intvl = MakeInterval(std::string(-tc));
+    EXPECT_STATUS_OK(intvl) << -tc;
+    if (intvl) {
+      EXPECT_EQ(*intvl, -tc);
+    }
+  }
+}
+
+// https://www.postgresql.org/docs/current/datatype-datetime.html and
+// https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-interval
+// are the sources of some of the MakeInterval() test cases.
+
+TEST(Interval, MakeInterval) {
+  auto hms = [](int h, int m, int s) {
+    return absl::Hours(h) + absl::Minutes(m) + absl::Seconds(s);
+  };
+  std::vector<std::pair<std::string, Interval>> test_cases = {
+      {"1.5 years", Interval(1, 6, 0)},
+      {"1.75 months", Interval(0, 1, 22, hms(12, 0, 0))},
+      {"@-1.5 years", Interval(-1, -6, 0)},
+
+      {"@ 1 year 2 mons", Interval(1, 2, 0)},
+      {"1 year 2 mons", Interval(1, 2, 0)},
+      {"1-2", Interval(1, 2, 0)},
+
+      {"@ 3 days 4 hours 5 mins 6 secs", Interval(0, 0, 3, hms(4, 5, 6))},
+      {"3 days 04:05:06", Interval(0, 0, 3, hms(4, 5, 6))},
+      {"3 4:05:06", Interval(0, 0, 3, hms(4, 5, 6))},
+
+      {" 6 years 5 months 4 days 3 hours 2 minutes 1 second ",
+       Interval(6, 5, 4, hms(3, 2, 1))},
+      {" @ 6 years 5 mons 4 days 3 hours 2 mins 1 sec ",
+       Interval(6, 5, 4, hms(3, 2, 1))},
+      {" 6 years 5 mons 4 days 03:02:01 ", Interval(6, 5, 4, hms(3, 2, 1))},
+      {" +6-5 +4 +3:02:01 ", Interval(6, 5, 4, hms(3, 2, 1))},
+
+      {"1 year 2 months 3 days 4 hours 5 minutes 6 seconds",
+       Interval(1, 2, 3, hms(4, 5, 6))},
+      {"-1 year -2 mons +3 days -04:05:06",
+       Interval(-1, -2, 3, hms(-4, -5, -6))},
+      {"-1-2 +3 -4:05:06", Interval(-1, 2, 3, hms(-4, -5, -6))},
+
+      {"@ 1 year 2 mons -3 days 4 hours 5 mins 6 secs ago",
+       Interval(-2, 10, 3, hms(-4, -5, -6))},
+
+      {"17h 20m 05s", Interval(hms(17, 20, 5))},
+
+      {"-42 microseconds", Interval(-absl::Microseconds(42))},
+      {"+87 milliseconds", Interval(absl::Milliseconds(87))},
+
+      {"4 decades", Interval(40, 0, 0)},
+      {"3 centuries", Interval(300, 0, 0)},
+      {"2 millennia", Interval(2'000, 0, 0)},
+  };
+
+  for (auto const& tc : test_cases) {
+    auto intvl = MakeInterval(tc.first);
+    EXPECT_STATUS_OK(intvl) << tc.first;
+    if (!intvl) continue;
+    EXPECT_EQ(*intvl, tc.second);
+  }
+}
+
+}  // namespace
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace spanner
+}  // namespace cloud
+}  // namespace google
diff --git a/google/cloud/spanner/spanner_client_unit_tests.bzl b/google/cloud/spanner/spanner_client_unit_tests.bzl
index 06fee1982e81c..b23ab1fa07817 100644
--- a/google/cloud/spanner/spanner_client_unit_tests.bzl
+++ b/google/cloud/spanner/spanner_client_unit_tests.bzl
@@ -46,6 +46,7 @@ spanner_client_unit_tests = [
     "internal/status_utils_test.cc",
     "internal/transaction_impl_test.cc",
     "internal/tuple_utils_test.cc",
+    "interval_test.cc",
     "json_test.cc",
     "keys_test.cc",
     "mutations_test.cc",

From 736e1d21fb49a64425cd926ae122b1cee7446f15 Mon Sep 17 00:00:00 2001
From: Bradley White <14679271+devbww@users.noreply.github.com>
Date: Wed, 24 Apr 2024 23:58:05 -0400
Subject: [PATCH 2/4] comma -> semi-colon

---
 google/cloud/spanner/interval.cc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/google/cloud/spanner/interval.cc b/google/cloud/spanner/interval.cc
index 8626a187e8642..d892d17aab059 100644
--- a/google/cloud/spanner/interval.cc
+++ b/google/cloud/spanner/interval.cc
@@ -67,7 +67,7 @@ struct {
 void Normalize(std::int64_t& months, std::int64_t& days,
                absl::Duration& offset) {
   auto const precision = absl::Microseconds(1);
-  offset += ((offset < absl::ZeroDuration()) ? -precision : precision) / 2,
+  offset += ((offset < absl::ZeroDuration()) ? -precision : precision) / 2;
   offset = absl::Trunc(offset, precision);
   days += absl::IDivDuration(offset, absl::Hours(24), &offset);
   if (offset < absl::ZeroDuration()) {

From 89e6858d646b4e2a438af0cfae1db38c63877b46 Mon Sep 17 00:00:00 2001
From: Bradley White <14679271+devbww@users.noreply.github.com>
Date: Fri, 26 Apr 2024 16:20:36 -0400
Subject: [PATCH 3/4] Address review comments

---
 google/cloud/spanner/interval.cc      | 258 +++++++++++++-------------
 google/cloud/spanner/interval_test.cc |  49 ++++-
 2 files changed, 170 insertions(+), 137 deletions(-)

diff --git a/google/cloud/spanner/interval.cc b/google/cloud/spanner/interval.cc
index d892d17aab059..9ada514cafd3b 100644
--- a/google/cloud/spanner/interval.cc
+++ b/google/cloud/spanner/interval.cc
@@ -38,25 +38,25 @@ namespace {
 
 // Interval factories for quantity units.
 struct {
-  absl::string_view name;
+  absl::string_view name;  // de-pluralized forms
   std::function<Interval(std::int32_t)> factory;
 } const kUnitFactories[] = {
-    // "days" is first so that it is chosen when unit is empty.
-    {"days", [](auto n) { return Interval(0, 0, n); }},
-
-    // "minutes" comes before other "m"s so it is chosen for, say, "6m".
-    {"minutes", [](auto n) { return Interval(absl::Minutes(n)); }},
-
-    {"microseconds", [](auto n) { return Interval(absl::Microseconds(n)); }},
-    {"milliseconds", [](auto n) { return Interval(absl::Milliseconds(n)); }},
-    {"seconds", [](auto n) { return Interval(absl::Seconds(n)); }},
-    {"hours", [](auto n) { return Interval(absl::Hours(n)); }},
-    {"weeks", [](auto n) { return Interval(0, 0, n * 7); }},
-    {"months", [](auto n) { return Interval(0, n, 0); }},
-    {"years", [](auto n) { return Interval(n, 0, 0); }},
-    {"decades", [](auto n) { return Interval(n * 10, 0, 0); }},
+    // "day" is first so that it is chosen when unit is empty.
+    {"day", [](auto n) { return Interval(0, 0, n); }},
+
+    // "minute" comes before other "m"s so it is chosen for, say, "6m".
+    {"minute", [](auto n) { return Interval(absl::Minutes(n)); }},
+
+    {"microsecond", [](auto n) { return Interval(absl::Microseconds(n)); }},
+    {"millisecond", [](auto n) { return Interval(absl::Milliseconds(n)); }},
+    {"second", [](auto n) { return Interval(absl::Seconds(n)); }},
+    {"hour", [](auto n) { return Interval(absl::Hours(n)); }},
+    {"week", [](auto n) { return Interval(0, 0, n * 7); }},
+    {"month", [](auto n) { return Interval(0, n, 0); }},
+    {"year", [](auto n) { return Interval(n, 0, 0); }},
+    {"decade", [](auto n) { return Interval(n * 10, 0, 0); }},
     {"century", [](auto n) { return Interval(n * 100, 0, 0); }},
-    {"centuries", [](auto n) { return Interval(n * 100, 0, 0); }},
+    {"centurie", [](auto n) { return Interval(n * 100, 0, 0); }},
     {"millennium", [](auto n) { return Interval(n * 1000, 0, 0); }},
     {"millennia", [](auto n) { return Interval(n * 1000, 0, 0); }},
 };
@@ -93,8 +93,8 @@ bool Cmp(std::int64_t a_months, std::int64_t a_days, absl::Duration a_offset,
 }
 
 // "y years m months d days H:M:S.F"
-std::string Stringify(std::int32_t months, std::int32_t days,
-                      absl::Duration offset) {
+std::string SerializeInterval(std::int32_t months, std::int32_t days,
+                              absl::Duration offset) {
   std::ostringstream ss;
   std::int32_t years = months / 12;
   months %= 12;
@@ -141,132 +141,122 @@ std::string Stringify(std::int32_t months, std::int32_t days,
   return std::move(ss).str();
 }
 
-class Parser {
- public:
-  explicit Parser(std::string s) : s_(std::move(s)) {}
-
-  /**
-   * https://www.postgresql.org/docs/current/datatype-datetime.html
-   *
-   * [@] quantity unit [quantity unit...] [direction]
-   *
-   * where quantity is a number (possibly signed); unit is microsecond,
-   * millisecond, second, minute, hour, day, week, month, year, decade,
-   * century, millennium, or abbreviations or plurals of these units;
-   * direction can be ago or empty. The at sign (@) is optional noise.
-   *
-   * The amounts of the different units are implicitly added with
-   * appropriate sign accounting. ago negates all the fields.
-   *
-   * Quantities of days, hours, minutes, and seconds can be specified
-   * without explicit unit markings. For example, '1 12:59:10' is read
-   * the same as '1 day 12 hours 59 min 10 sec'.
-   *
-   * Also, a combination of years and months can be specified with a
-   * dash; for example '200-10' is read the same as '200 years 10 months'.
-   */
-  StatusOr<Interval> Parse();
-
- private:
-  static void ConsumeSpaces(absl::string_view& s) {
-    while (!s.empty() && absl::ascii_isspace(s.front())) s.remove_prefix(1);
-  }
+void ConsumeSpaces(absl::string_view& s) {
+  while (!s.empty() && absl::ascii_isspace(s.front())) s.remove_prefix(1);
+}
 
-  static void ConsumeInteger(absl::string_view& s) {
-    while (!s.empty() && absl::ascii_isdigit(s.front())) s.remove_prefix(1);
-  }
+void ConsumeInteger(absl::string_view& s) {
+  while (!s.empty() && absl::ascii_isdigit(s.front())) s.remove_prefix(1);
+}
 
-  static absl::string_view ConsumeSign(absl::string_view& s) {
-    auto t = s;
-    if (!absl::ConsumePrefix(&s, "-")) absl::ConsumePrefix(&s, "+");
-    return t.substr(0, t.size() - s.size());
-  }
+absl::string_view ConsumeSign(absl::string_view& s) {
+  auto t = s;
+  if (!absl::ConsumePrefix(&s, "-")) absl::ConsumePrefix(&s, "+");
+  return t.substr(0, t.size() - s.size());
+}
 
-  static absl::string_view ConsumeWord(absl::string_view& s) {
-    auto t = s;
-    while (!s.empty() && absl::ascii_isalpha(s.front())) s.remove_prefix(1);
-    return t.substr(0, t.size() - s.size());
-  }
+absl::string_view ConsumeWord(absl::string_view& s) {
+  auto t = s;
+  while (!s.empty() && absl::ascii_isalpha(s.front())) s.remove_prefix(1);
+  return t.substr(0, t.size() - s.size());
+}
 
-  static bool ParseDouble(absl::string_view& s, double& d, bool allow_sign) {
-    auto t = s;
-    if (allow_sign) ConsumeSign(t);
-    ConsumeInteger(t);
-    if (!absl::ConsumePrefix(&t, ".")) return false;
-    ConsumeInteger(t);
-    auto len = s.size() - t.size();
-    if (!absl::SimpleAtod(s.substr(0, len), &d)) return false;
-    s.remove_prefix(len);
-    return true;
-  }
+bool ParseDouble(absl::string_view& s, double& d, bool allow_sign) {
+  auto t = s;
+  if (allow_sign) ConsumeSign(t);
+  ConsumeInteger(t);
+  if (!absl::ConsumePrefix(&t, ".")) return false;
+  ConsumeInteger(t);
+  auto len = s.size() - t.size();
+  if (!absl::SimpleAtod(s.substr(0, len), &d)) return false;
+  s.remove_prefix(len);
+  return true;
+}
 
-  template <typename T>
-  static bool ParseInteger(absl::string_view& s, T& n, bool allow_sign) {
-    auto t = s;
-    if (allow_sign) ConsumeSign(t);
-    ConsumeInteger(t);
-    auto len = s.size() - t.size();
-    if (!absl::SimpleAtoi(s.substr(0, len), &n)) return false;
-    s.remove_prefix(len);
-    return true;
-  }
+template <typename T>
+bool ParseInteger(absl::string_view& s, T& n, bool allow_sign) {
+  auto t = s;
+  if (allow_sign) ConsumeSign(t);
+  ConsumeInteger(t);
+  auto len = s.size() - t.size();
+  if (!absl::SimpleAtoi(s.substr(0, len), &n)) return false;
+  s.remove_prefix(len);
+  return true;
+}
 
-  static bool ParseYearMonth(absl::string_view& s, Interval& intvl) {
-    auto t = s;
-    std::int32_t year;
-    if (!ParseInteger(t, year, true)) return false;
-    if (!absl::ConsumePrefix(&t, "-")) return false;
-    std::int32_t month;
-    if (!ParseInteger(t, month, false)) return false;
-    intvl = Interval(year, month, 0);
-    s.remove_prefix(s.size() - t.size());
-    return true;
-  }
+bool ParseYearMonth(absl::string_view& s, Interval& intvl) {
+  auto t = s;
+  std::int32_t year;
+  if (!ParseInteger(t, year, true)) return false;
+  if (!absl::ConsumePrefix(&t, "-")) return false;
+  std::int32_t month;
+  if (!ParseInteger(t, month, false)) return false;
+  intvl = Interval(year, month, 0);
+  s.remove_prefix(s.size() - t.size());
+  return true;
+}
 
-  static bool ParseHourMinuteSecond(absl::string_view& s, Interval& intvl) {
-    auto t = s;
-    auto d = absl::ZeroDuration();
-    auto sign = ConsumeSign(t);
-    std::int64_t hour;
-    if (!ParseInteger(t, hour, false)) return false;
-    d += absl::Hours(hour);
-    if (!absl::ConsumePrefix(&t, ":")) return false;
-    std::int64_t minute;
-    if (!ParseInteger(t, minute, false)) return false;
-    d += absl::Minutes(minute);
-    if (!absl::ConsumePrefix(&t, ":")) return false;
-    double second;
-    if (ParseDouble(t, second, false)) {
-      d += absl::Seconds(second);
-    } else {
-      std::int64_t second;
-      if (!ParseInteger(t, second, false)) return false;
-      d += absl::Seconds(second);
-    }
-    intvl = Interval(sign == "-" ? -d : d);
-    s.remove_prefix(s.size() - t.size());
-    return true;
+bool ParseHourMinuteSecond(absl::string_view& s, Interval& intvl) {
+  auto t = s;
+  auto d = absl::ZeroDuration();
+  auto sign = ConsumeSign(t);
+  std::int64_t hour;
+  if (!ParseInteger(t, hour, false)) return false;
+  d += absl::Hours(hour);
+  if (!absl::ConsumePrefix(&t, ":")) return false;
+  std::int64_t minute;
+  if (!ParseInteger(t, minute, false)) return false;
+  d += absl::Minutes(minute);
+  if (!absl::ConsumePrefix(&t, ":")) return false;
+  double second;
+  if (ParseDouble(t, second, false)) {
+    d += absl::Seconds(second);
+  } else {
+    std::int64_t second;
+    if (!ParseInteger(t, second, false)) return false;
+    d += absl::Seconds(second);
   }
+  intvl = Interval(sign == "-" ? -d : d);
+  s.remove_prefix(s.size() - t.size());
+  return true;
+}
 
-  static Interval Unit(absl::string_view& s, std::int32_t n) {
-    auto t = s;
-    auto unit = ConsumeWord(t);
-    if (unit.size() > 1) absl::ConsumeSuffix(&unit, "s");  // unpluralize
-    for (auto const& factory : kUnitFactories) {
-      if (absl::StartsWith(factory.name, unit)) {
-        s.remove_prefix(s.size() - t.size());
-        return factory.factory(n);
-      }
+Interval Unit(absl::string_view& s, std::int32_t n) {
+  auto t = s;
+  auto unit = ConsumeWord(t);
+  if (unit.size() > 1) absl::ConsumeSuffix(&unit, "s");  // de-pluralize
+  for (auto const& factory : kUnitFactories) {
+    if (absl::StartsWith(factory.name, unit)) {
+      s.remove_prefix(s.size() - t.size());
+      return factory.factory(n);
     }
-    return Interval(0, 0, n);  // default to days without removing unit
   }
+  return Interval(0, 0, n);  // default to days without removing unit
+}
 
-  std::string s_;
-};
-
-StatusOr<Interval> Parser::Parse() {
+/**
+ * https://www.postgresql.org/docs/current/datatype-datetime.html
+ *
+ * [@] quantity unit [quantity unit...] [direction]
+ *
+ * where quantity is a number (possibly signed); unit is microsecond,
+ * millisecond, second, minute, hour, day, week, month, year, decade,
+ * century, millennium, or abbreviations or plurals of these units;
+ * direction can be ago or empty. The at sign (@) is optional noise.
+ *
+ * The amounts of the different units are implicitly added with
+ * appropriate sign accounting. ago negates all the fields.
+ *
+ * Quantities of days, hours, minutes, and seconds can be specified
+ * without explicit unit markings. For example, '1 12:59:10' is read
+ * the same as '1 day 12 hours 59 min 10 sec'.
+ *
+ * Also, a combination of years and months can be specified with a
+ * dash; for example '200-10' is read the same as '200 years 10 months'.
+ */
+StatusOr<Interval> ParseInterval(std::string const& str) {
   Interval intvl;
-  auto s = absl::string_view(s_);
+  absl::string_view s = str;
 
   ConsumeSpaces(s);
   if (absl::ConsumePrefix(&s, "@")) {
@@ -305,7 +295,7 @@ StatusOr<Interval> Parser::Parse() {
 
   if (!s.empty()) {
     return internal::InvalidArgumentError(
-        absl::StrCat("\"", s_, "\": Syntax error at \"", s.substr(0, 5), "\""),
+        absl::StrCat("\"", str, "\": Syntax error at \"", s.substr(0, 5), "\""),
         GCP_ERROR_INFO());
   }
   return intvl;
@@ -354,11 +344,11 @@ Interval& Interval::operator*=(double d) {
 }
 
 Interval::operator std::string() const {
-  return Stringify(months_, days_, offset_);
+  return SerializeInterval(months_, days_, offset_);
 }
 
 StatusOr<Interval> MakeInterval(absl::string_view s) {
-  return Parser(absl::AsciiStrToLower(s)).Parse();
+  return ParseInterval(absl::AsciiStrToLower(s));
 }
 
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
diff --git a/google/cloud/spanner/interval_test.cc b/google/cloud/spanner/interval_test.cc
index e3a6020609fdd..43984d4af2032 100644
--- a/google/cloud/spanner/interval_test.cc
+++ b/google/cloud/spanner/interval_test.cc
@@ -16,6 +16,7 @@
 #include "google/cloud/testing_util/status_matchers.h"
 #include <gtest/gtest.h>
 #include <limits>
+#include <sstream>
 #include <string>
 #include <utility>
 #include <vector>
@@ -26,6 +27,8 @@ namespace spanner {
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 namespace {
 
+using ::google::cloud::testing_util::StatusIs;
+
 TEST(Interval, RegularSemantics) {
   Interval const intvl(0, 1, 2, absl::Hours(3));
 
@@ -112,21 +115,27 @@ TEST(Interval, ArithmeticOperators) {
 
 TEST(Interval, Range) {
   auto huge = Interval(178'000'000, 0, 0);
-  EXPECT_LT(-huge, huge);
   EXPECT_EQ(std::string(huge), "178000000 years");
   EXPECT_EQ(std::string(-huge), "-178000000 years");
+
+  EXPECT_LT(-huge, huge);
+  EXPECT_GT(huge, huge - Interval(absl::Microseconds(1)));
+  EXPECT_LT(-huge, -huge + Interval(absl::Microseconds(1)));
 }
 
+// Check that parsing the result of a string conversion yields the same value.
 TEST(Interval, RoundTrip) {
   std::vector<Interval> test_cases = {
       Interval(),
       Interval(1, 0, 0),
       Interval(0, 2, 0),
-      Interval(0, 2, 3),
+      Interval(0, 0, 3),
       Interval(absl::Hours(4)),
       Interval(absl::Minutes(5)),
       Interval(absl::Seconds(6)),
-      Interval(absl::Seconds(7.5)),
+      Interval(absl::Milliseconds(123)),
+      Interval(absl::Microseconds(123456)),
+      Interval(absl::Nanoseconds(123456789)),
   };
 
   for (auto const& tc : test_cases) {
@@ -152,6 +161,22 @@ TEST(Interval, MakeInterval) {
     return absl::Hours(h) + absl::Minutes(m) + absl::Seconds(s);
   };
   std::vector<std::pair<std::string, Interval>> test_cases = {
+      {"2 microseconds", Interval(absl::Microseconds(2))},
+      {"3 milliseconds", Interval(absl::Milliseconds(3))},
+      {"4 seconds", Interval(absl::Seconds(4))},
+      {"5 minutes", Interval(absl::Minutes(5))},
+      {"6 hours", Interval(absl::Hours(6))},
+      {"7 days", Interval(0, 0, 7)},
+      {"8 weeks", Interval(0, 0, 8 * 7)},
+      {"9 months", Interval(0, 9, 0)},
+      {"10 years", Interval(10, 0, 0)},
+      {"11 decades", Interval(11 * 10, 0, 0)},
+      {"12 centuries", Interval(12 * 100, 0, 0)},
+      {"13 millennia", Interval(13 * 1'000, 0, 0)},
+
+      {"1 century", Interval(100, 0, 0)},
+      {"1 millennium", Interval(1'000, 0, 0)},
+
       {"1.5 years", Interval(1, 6, 0)},
       {"1.75 months", Interval(0, 1, 22, hms(12, 0, 0))},
       {"@-1.5 years", Interval(-1, -6, 0)},
@@ -188,6 +213,9 @@ TEST(Interval, MakeInterval) {
       {"4 decades", Interval(40, 0, 0)},
       {"3 centuries", Interval(300, 0, 0)},
       {"2 millennia", Interval(2'000, 0, 0)},
+
+      {"", Interval()},
+      {"ago", Interval()},
   };
 
   for (auto const& tc : test_cases) {
@@ -196,6 +224,21 @@ TEST(Interval, MakeInterval) {
     if (!intvl) continue;
     EXPECT_EQ(*intvl, tc.second);
   }
+
+  EXPECT_THAT(MakeInterval("junk"), StatusIs(StatusCode::kInvalidArgument));
+
+  // Check that we reject double plurals.
+  EXPECT_THAT(MakeInterval("7 dayss"), StatusIs(StatusCode::kInvalidArgument));
+}
+
+// Output streaming of an Interval is defined to use the string conversion
+// operator, so here we simply verify that output streaming is available.
+TEST(Interval, OutputStreaming) {
+  std::ostringstream os;
+  os << Interval(1, 2, 3,
+                 absl::Hours(4) + absl::Minutes(5) + absl::Seconds(6) +
+                     absl::Nanoseconds(123456789));
+  EXPECT_EQ("1 year 2 months 3 days 04:05:06.123456789", os.str());
 }
 
 }  // namespace

From c749a3b77b0a3640cd8d7bde88555248d27d414d Mon Sep 17 00:00:00 2001
From: Bradley White <14679271+devbww@users.noreply.github.com>
Date: Fri, 26 Apr 2024 17:17:09 -0400
Subject: [PATCH 4/4] Fix typo

---
 google/cloud/spanner/interval.cc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/google/cloud/spanner/interval.cc b/google/cloud/spanner/interval.cc
index 9ada514cafd3b..8b7ea823e2067 100644
--- a/google/cloud/spanner/interval.cc
+++ b/google/cloud/spanner/interval.cc
@@ -331,7 +331,7 @@ Interval& Interval::operator+=(Interval const& intvl) {
 Interval& Interval::operator*=(double d) {
   // Fractional results only flow down into smaller units. Nothing ever
   // carries up into larger units. This means that '1 month' / 2 becomes
-  // '15 days, but '1 month 15 days' * 3 is '3 months 45 days'.
+  // '15 days', but '1 month 15 days' * 3 is '3 months 45 days'.
   double i_months;
   double f_months = std::modf(months_ * d, &i_months);
   months_ = static_cast<std::int32_t>(i_months);