ARROW-14822: [C++] Implement floor/ceil/round for temporal objects

cpp/src/arrow/compute/api_scalar.cc

@@ -118,6 +118,7 @@ struct EnumTraits<compute::AssumeTimezoneOptions::Ambiguous>
     return "<INVALID>";
   }
 };
+
 template <>
 struct EnumTraits<compute::AssumeTimezoneOptions::Nonexistent>
     : BasicEnumTraits<compute::AssumeTimezoneOptions::Nonexistent,
@@ -174,6 +175,45 @@ struct EnumTraits<compute::RoundMode>
   }
 };
 
+template <>
+struct EnumTraits<compute::CalendarUnit>
+    : BasicEnumTraits<compute::CalendarUnit, compute::CalendarUnit::NANOSECOND,
+                      compute::CalendarUnit::MICROSECOND,
+                      compute::CalendarUnit::MILLISECOND, compute::CalendarUnit::SECOND,
+                      compute::CalendarUnit::MINUTE, compute::CalendarUnit::HOUR,
+                      compute::CalendarUnit::DAY, compute::CalendarUnit::WEEK,
+                      compute::CalendarUnit::MONTH, compute::CalendarUnit::QUARTER,
+                      compute::CalendarUnit::YEAR> {
+  static std::string name() { return "compute::CalendarUnit"; }
+  static std::string value_name(compute::CalendarUnit value) {
+    switch (value) {
+      case compute::CalendarUnit::NANOSECOND:
+        return "NANOSECOND";
+      case compute::CalendarUnit::MICROSECOND:
+        return "MICROSECOND";
+      case compute::CalendarUnit::MILLISECOND:
+        return "MILLISECOND";
+      case compute::CalendarUnit::SECOND:
+        return "SECOND";
+      case compute::CalendarUnit::MINUTE:
+        return "MINUTE";
+      case compute::CalendarUnit::HOUR:
+        return "HOUR";
+      case compute::CalendarUnit::DAY:
+        return "DAY";
+      case compute::CalendarUnit::WEEK:
+        return "WEEK";
+      case compute::CalendarUnit::MONTH:
+        return "MONTH";
+      case compute::CalendarUnit::QUARTER:
+        return "QUARTER";
+      case compute::CalendarUnit::YEAR:
+        return "YEAR";
+    }
+    return "<INVALID>";
+  }
+};
+
 template <>
 struct EnumTraits<compute::Utf8NormalizeOptions::Form>
     : BasicEnumTraits<compute::Utf8NormalizeOptions::Form,
@@ -266,6 +306,9 @@ static auto kReplaceSubstringOptionsType =
 static auto kRoundOptionsType = GetFunctionOptionsType<RoundOptions>(
     DataMember("ndigits", &RoundOptions::ndigits),
     DataMember("round_mode", &RoundOptions::round_mode));
+static auto kRoundTemporalOptionsType = GetFunctionOptionsType<RoundTemporalOptions>(
+    DataMember("multiple", &RoundTemporalOptions::multiple),
+    DataMember("unit", &RoundTemporalOptions::unit));
 static auto kRoundToMultipleOptionsType = GetFunctionOptionsType<RoundToMultipleOptions>(
     DataMember("multiple", &RoundToMultipleOptions::multiple),
     DataMember("round_mode", &RoundToMultipleOptions::round_mode));
@@ -412,6 +455,12 @@ RoundOptions::RoundOptions(int64_t ndigits, RoundMode round_mode)
 }
 constexpr char RoundOptions::kTypeName[];
 
+RoundTemporalOptions::RoundTemporalOptions(int multiple, CalendarUnit unit)
+    : FunctionOptions(internal::kRoundTemporalOptionsType),
+      multiple(std::move(multiple)),
+      unit(unit) {}
+constexpr char RoundTemporalOptions::kTypeName[];
+
 RoundToMultipleOptions::RoundToMultipleOptions(double multiple, RoundMode round_mode)
     : RoundToMultipleOptions(std::make_shared<DoubleScalar>(multiple), round_mode) {}
 RoundToMultipleOptions::RoundToMultipleOptions(std::shared_ptr<Scalar> multiple,
@@ -511,6 +560,7 @@ void RegisterScalarOptions(FunctionRegistry* registry) {
   DCHECK_OK(registry->AddFunctionOptionsType(kReplaceSliceOptionsType));
   DCHECK_OK(registry->AddFunctionOptionsType(kReplaceSubstringOptionsType));
   DCHECK_OK(registry->AddFunctionOptionsType(kRoundOptionsType));
+  DCHECK_OK(registry->AddFunctionOptionsType(kRoundTemporalOptionsType));
   DCHECK_OK(registry->AddFunctionOptionsType(kRoundToMultipleOptionsType));
   DCHECK_OK(registry->AddFunctionOptionsType(kSetLookupOptionsType));
   DCHECK_OK(registry->AddFunctionOptionsType(kSliceOptionsType));
@@ -711,6 +761,21 @@ Result<Datum> DayOfWeek(const Datum& arg, DayOfWeekOptions options, ExecContext*
   return CallFunction("day_of_week", {arg}, &options, ctx);
 }
 
+Result<Datum> CeilTemporal(const Datum& arg, RoundTemporalOptions options,
+                           ExecContext* ctx) {
+  return CallFunction("ceil_temporal", {arg}, &options, ctx);
+}
+
+Result<Datum> FloorTemporal(const Datum& arg, RoundTemporalOptions options,
+                            ExecContext* ctx) {
+  return CallFunction("floor_temporal", {arg}, &options, ctx);
+}
+
+Result<Datum> RoundTemporal(const Datum& arg, RoundTemporalOptions options,
+                            ExecContext* ctx) {
+  return CallFunction("round_temporal", {arg}, &options, ctx);
+}
+
 Result<Datum> Strftime(const Datum& arg, StrftimeOptions options, ExecContext* ctx) {
   return CallFunction("strftime", {arg}, &options, ctx);
 }

cpp/src/arrow/compute/api_scalar.h

@@ -90,6 +90,32 @@ class ARROW_EXPORT RoundOptions : public FunctionOptions {
   RoundMode round_mode;
 };
 
+enum class CalendarUnit : int8_t {
+  NANOSECOND,
+  MICROSECOND,
+  MILLISECOND,
+  SECOND,
+  MINUTE,
+  HOUR,
+  DAY,
+  WEEK,
+  MONTH,
+  QUARTER,
+  YEAR
+};
+
+class ARROW_EXPORT RoundTemporalOptions : public FunctionOptions {
+ public:
+  explicit RoundTemporalOptions(int multiple = 1, CalendarUnit unit = CalendarUnit::DAY);
+  constexpr static char const kTypeName[] = "RoundTemporalOptions";
+  static RoundTemporalOptions Defaults() { return RoundTemporalOptions(); }
+
+  /// Number of units to round to
+  int multiple;
+  /// The unit used for rounding of time
+  CalendarUnit unit;
+};
+
 class ARROW_EXPORT RoundToMultipleOptions : public FunctionOptions {
  public:
   explicit RoundToMultipleOptions(double multiple = 1.0,
@@ -781,6 +807,54 @@ Result<Datum> RoundToMultiple(
     const Datum& arg, RoundToMultipleOptions options = RoundToMultipleOptions::Defaults(),
     ExecContext* ctx = NULLPTR);
 
+/// \brief Ceil a temporal value to a given frequency
+///
+/// If argument is null the result will be null.
+///
+/// \param[in] arg the temporal value to ceil
+/// \param[in] options temporal rounding options, optional
+/// \param[in] ctx the function execution context, optional
+/// \return the element-wise rounded value
+///
+/// \since 7.0.0
+/// \note API not yet finalized
+ARROW_EXPORT
+Result<Datum> CeilTemporal(
+    const Datum& arg, RoundTemporalOptions options = RoundTemporalOptions::Defaults(),
+    ExecContext* ctx = NULLPTR);
+
+/// \brief Floor a temporal value to a given frequency
+///
+/// If argument is null the result will be null.
+///
+/// \param[in] arg the temporal value to floor
+/// \param[in] options temporal rounding options, optional
+/// \param[in] ctx the function execution context, optional
+/// \return the element-wise rounded value
+///
+/// \since 7.0.0
+/// \note API not yet finalized
+ARROW_EXPORT
+Result<Datum> FloorTemporal(
+    const Datum& arg, RoundTemporalOptions options = RoundTemporalOptions::Defaults(),
+    ExecContext* ctx = NULLPTR);
+
+/// \brief Round a temporal value to a given frequency
+///
+/// If argument is null the result will be null.
+///
+/// \param[in] arg the temporal value to round
+/// \param[in] options temporal rounding options, optional
+/// \param[in] ctx the function execution context, optional
+/// \return the element-wise rounded value
+///
+/// \since 7.0.0
+/// \note API not yet finalized
+ARROW_EXPORT
+Result<Datum> RoundTemporal(
+    const Datum& arg, RoundTemporalOptions options = RoundTemporalOptions::Defaults(),
+    ExecContext* ctx = NULLPTR);
+
 /// \brief Compare a numeric array with a scalar.
 ///
 /// \param[in] left datum to compare, must be an Array

cpp/src/arrow/compute/function_test.cc

@@ -61,6 +61,10 @@ TEST(FunctionOptions, Equality) {
   options.emplace_back(new RoundOptions());
   options.emplace_back(
       new RoundOptions(/*ndigits=*/2, /*round_mode=*/RoundMode::TOWARDS_INFINITY));
+  options.emplace_back(new RoundTemporalOptions());
+  options.emplace_back(new RoundTemporalOptions(
+      /*multiple=*/2,
+      /*unit=*/CalendarUnit::WEEK));
   options.emplace_back(new RoundToMultipleOptions());
   options.emplace_back(new RoundToMultipleOptions(
       /*multiple=*/100, /*round_mode=*/RoundMode::TOWARDS_INFINITY));