[SPARK-29390][SQL] Add the justify_days(), justify_hours() and justif_interval() functions

### What changes were proposed in this pull request?

Add 3 interval functions justify_days, justify_hours, justif_interval to support justify interval values

### Why are the changes needed?

For feature parity with postgres

add three interval functions to justify interval values.

justify_days(interval) | interval | Adjust interval so 30-day time periods are represented as months | justify_days(interval '35 days') | 1 mon 5 days
-- | -- | -- | -- | --
justify_hours(interval) | interval | Adjust interval so 24-hour time periods are represented as days | justify_hours(interval '27 hours') | 1 day 03:00:00
justify_interval(interval) | interval | Adjust interval using justify_days and justify_hours, with additional sign adjustments | justify_interval(interval '1 mon -1 hour') | 29 days 23:00:00

### Does this PR introduce any user-facing change?

yes. new interval functions are added

### How was this patch tested?

add ut

Closes apache#26465 from yaooqinn/SPARK-29390.

Authored-by: Kent Yao <[email protected]>
Signed-off-by: Takeshi Yamamuro <[email protected]>

Author: yaooqinn

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/analysis/FunctionRegistry.scala

@@ -420,6 +420,9 @@ object FunctionRegistry {
     expression[MakeDate]("make_date"),
     expression[MakeTimestamp]("make_timestamp"),
     expression[MakeInterval]("make_interval"),
+    expression[JustifyDays]("justify_days"),
+    expression[JustifyHours]("justify_hours"),
+    expression[JustifyInterval]("justify_interval"),
     expression[DatePart]("date_part"),
 
     // collection functions

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/intervalExpressions.scala

@@ -19,6 +19,8 @@ package org.apache.spark.sql.catalyst.expressions
 
 import java.util.Locale
 
+import scala.util.control.NonFatal
+
 import org.apache.spark.sql.catalyst.expressions.codegen.{CodegenContext, ExprCode}
 import org.apache.spark.sql.catalyst.util.IntervalUtils
 import org.apache.spark.sql.catalyst.util.IntervalUtils._
@@ -257,3 +259,69 @@ case class MakeInterval(
 
   override def prettyName: String = "make_interval"
 }
+
+abstract class IntervalJustifyLike(
+    child: Expression,
+    justify: CalendarInterval => CalendarInterval,
+    justifyFuncName: String) extends UnaryExpression with ExpectsInputTypes {
+  override def inputTypes: Seq[AbstractDataType] = Seq(CalendarIntervalType)
+
+  override def dataType: DataType = CalendarIntervalType
+
+  override def nullSafeEval(input: Any): Any = {
+    try {
+      justify(input.asInstanceOf[CalendarInterval])
+    } catch {
+      case NonFatal(_) => null
+    }
+  }
+
+  override protected def doGenCode(ctx: CodegenContext, ev: ExprCode): ExprCode = {
+    nullSafeCodeGen(ctx, ev, child => {
+      val iu = IntervalUtils.getClass.getCanonicalName.stripSuffix("$")
+      s"""
+         |try {
+         |  ${ev.value} = $iu.$justifyFuncName($child);
+         |} catch (java.lang.ArithmeticException e) {
+         |  ${ev.isNull} = true;
+         |}
+         |""".stripMargin
+    })
+  }
+
+  override def prettyName: String = justifyFuncName
+}
+
+@ExpressionDescription(
+  usage = "_FUNC_(expr) - Adjust interval so 30-day time periods are represented as months",
+  examples = """
+    Examples:
+      > SELECT _FUNC_(interval '1 month -59 day 25 hour');
+       -29 days 25 hours
+  """,
+  since = "3.0.0")
+case class JustifyDays(child: Expression)
+  extends IntervalJustifyLike(child, justifyDays, "justifyDays")
+
+@ExpressionDescription(
+  usage = "_FUNC_(expr) - Adjust interval so 24-hour time periods are represented as days",
+  examples = """
+    Examples:
+      > SELECT _FUNC_(interval '1 month -59 day 25 hour');
+       1 months -57 days -23 hours
+  """,
+  since = "3.0.0")
+case class JustifyHours(child: Expression)
+  extends IntervalJustifyLike(child, justifyHours, "justifyHours")
+
+@ExpressionDescription(
+  usage = "_FUNC_(expr) - Adjust interval using justifyHours and justifyDays, with additional" +
+    " sign adjustments",
+  examples = """
+    Examples:
+      > SELECT _FUNC_(interval '1 month -59 day 25 hour');
+       -27 days -23 hours
+  """,
+  since = "3.0.0")
+case class JustifyInterval(child: Expression)
+  extends IntervalJustifyLike(child, justifyInterval, "justifyInterval")

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/util/IntervalUtils.scala

@@ -637,4 +637,40 @@ object IntervalUtils {
 
     new CalendarInterval(totalMonths, totalDays, micros)
   }
+
+  /**
+   * Adjust interval so 30-day time periods are represented as months.
+   */
+  def justifyDays(interval: CalendarInterval): CalendarInterval = {
+    val monthToDays = interval.months * DAYS_PER_MONTH
+    val totalDays = monthToDays + interval.days
+    val months = Math.toIntExact(totalDays / DAYS_PER_MONTH)
+    val days = totalDays % DAYS_PER_MONTH
+    new CalendarInterval(months, days.toInt, interval.microseconds)
+  }
+
+  /**
+   * Adjust interval so 24-hour time periods are represented as days.
+   */
+  def justifyHours(interval: CalendarInterval): CalendarInterval = {
+    val dayToUs = MICROS_PER_DAY * interval.days
+    val totalUs = Math.addExact(interval.microseconds, dayToUs)
+    val days = totalUs / MICROS_PER_DAY
+    val microseconds = totalUs % MICROS_PER_DAY
+    new CalendarInterval(interval.months, days.toInt, microseconds)
+  }
+
+  /**
+   * Adjust interval using justifyHours and justifyDays, with additional sign adjustments.
+   */
+  def justifyInterval(interval: CalendarInterval): CalendarInterval = {
+    val monthToDays = DAYS_PER_MONTH * interval.months
+    val dayToUs = Math.multiplyExact(monthToDays + interval.days, MICROS_PER_DAY)
+    val totalUs = Math.addExact(interval.microseconds, dayToUs)
+    val microseconds = totalUs % MICROS_PER_DAY
+    val totalDays = totalUs / MICROS_PER_DAY
+    val days = totalDays % DAYS_PER_MONTH
+    val months = totalDays / DAYS_PER_MONTH
+    new CalendarInterval(months.toInt, days.toInt, microseconds)
+  }
 }

sql/catalyst/src/test/scala/org/apache/spark/sql/catalyst/util/IntervalUtilsSuite.scala

@@ -266,4 +266,35 @@ class IntervalUtilsSuite extends SparkFunSuite {
         assert(e.getMessage.contains("divide by zero"))
     }
   }
+
+  test("justify days") {
+    assert(justifyDays(fromString("1 month 35 day")) === new CalendarInterval(2, 5, 0))
+    assert(justifyDays(fromString("-1 month 35 day")) === new CalendarInterval(0, 5, 0))
+    assert(justifyDays(fromString("1 month -35 day")) === new CalendarInterval(0, -5, 0))
+    assert(justifyDays(fromString("-1 month -35 day")) === new CalendarInterval(-2, -5, 0))
+    assert(justifyDays(fromString("-1 month 2 day")) === new CalendarInterval(0, -28, 0))
+  }
+
+  test("justify hours") {
+    assert(justifyHours(fromString("29 day 25 hour")) ===
+      new CalendarInterval(0, 30, 1 * MICROS_PER_HOUR))
+    assert(justifyHours(fromString("29 day -25 hour")) ===
+      new CalendarInterval(0, 27, 23 * MICROS_PER_HOUR))
+    assert(justifyHours(fromString("-29 day 25 hour")) ===
+      new CalendarInterval(0, -27, -23 * MICROS_PER_HOUR))
+    assert(justifyHours(fromString("-29 day -25 hour")) ===
+      new CalendarInterval(0, -30, -1 * MICROS_PER_HOUR))
+  }
+
+  test("justify interval") {
+    assert(justifyInterval(fromString("1 month 29 day 25 hour")) ===
+      new CalendarInterval(2, 0, 1 * MICROS_PER_HOUR))
+    assert(justifyInterval(fromString("-1 month 29 day -25 hour")) ===
+      new CalendarInterval(0, -2, -1 * MICROS_PER_HOUR))
+    assert(justifyInterval(fromString("1 month -29 day -25 hour")) ===
+      new CalendarInterval(0, 0, -1 * MICROS_PER_HOUR))
+    assert(justifyInterval(fromString("-1 month -29 day -25 hour")) ===
+      new CalendarInterval(-2, 0, -1 * MICROS_PER_HOUR))
+    intercept[ArithmeticException](justifyInterval(new CalendarInterval(2, 0, Long.MaxValue)))
+  }
 }

sql/core/src/test/resources/sql-tests/inputs/interval.sql

@@ -74,3 +74,17 @@ select cast('+     1 second' as interval);
 select cast('-     1 second' as interval);
 select cast('- -1 second' as interval);
 select cast('- +1 second' as interval);
+
+-- justify intervals
+select justify_days(cast(null as interval));
+select justify_hours(cast(null as interval));
+select justify_interval(cast(null as interval));
+select justify_days(interval '1 month 59 day 25 hour');
+select justify_hours(interval '1 month 59 day 25 hour');
+select justify_interval(interval '1 month 59 day 25 hour');
+select justify_days(interval '1 month -59 day 25 hour');
+select justify_hours(interval '1 month -59 day 25 hour');
+select justify_interval(interval '1 month -59 day 25 hour');
+select justify_days(interval '1 month 59 day -25 hour');
+select justify_hours(interval '1 month 59 day -25 hour');
+select justify_interval(interval '1 month 59 day -25 hour');

sql/core/src/test/resources/sql-tests/inputs/postgreSQL/interval.sql

@@ -157,13 +157,11 @@
 -- select '100000000y 10mon -1000000000d -100000h -10min -10.000001s ago'::interval;
 
 -- test justify_hours() and justify_days()
--- [SPARK-29390] Add the justify_days(), justify_hours() and justify_interval() functions
--- SELECT justify_hours(interval '6 months 3 days 52 hours 3 minutes 2 seconds') as `6 mons 5 days 4 hours 3 mins 2 seconds`;
--- SELECT justify_days(interval '6 months 36 days 5 hours 4 minutes 3 seconds') as `7 mons 6 days 5 hours 4 mins 3 seconds`;
+SELECT justify_hours(interval '6 months 3 days 52 hours 3 minutes 2 seconds') as `6 mons 5 days 4 hours 3 mins 2 seconds`;
+SELECT justify_days(interval '6 months 36 days 5 hours 4 minutes 3 seconds') as `7 mons 6 days 5 hours 4 mins 3 seconds`;
 
 -- test justify_interval()
-
--- SELECT justify_interval(interval '1 month -1 hour') as `1 month -1 hour`;
+SELECT justify_interval(interval '1 month -1 hour') as `1 month -1 hour`;
 
 -- test fractional second input, and detection of duplicate units
 -- [SPARK-28259] Date/Time Output Styles and Date Order Conventions

sql/core/src/test/resources/sql-tests/results/interval.sql.out

@@ -1,5 +1,5 @@
 -- Automatically generated by SQLQueryTestSuite
--- Number of queries: 45
+-- Number of queries: 57
 
 
 -- !query 0
@@ -362,3 +362,99 @@ select cast('- +1 second' as interval)
 struct<CAST(- +1 second AS INTERVAL):interval>
 -- !query 44 output
 NULL
+
+
+-- !query 45
+select justify_days(cast(null as interval))
+-- !query 45 schema
+struct<justifyDays(CAST(NULL AS INTERVAL)):interval>
+-- !query 45 output
+NULL
+
+
+-- !query 46
+select justify_hours(cast(null as interval))
+-- !query 46 schema
+struct<justifyHours(CAST(NULL AS INTERVAL)):interval>
+-- !query 46 output
+NULL
+
+
+-- !query 47
+select justify_interval(cast(null as interval))
+-- !query 47 schema
+struct<justifyInterval(CAST(NULL AS INTERVAL)):interval>
+-- !query 47 output
+NULL
+
+
+-- !query 48
+select justify_days(interval '1 month 59 day 25 hour')
+-- !query 48 schema
+struct<justifyDays(1 months 59 days 25 hours):interval>
+-- !query 48 output
+2 months 29 days 25 hours
+
+
+-- !query 49
+select justify_hours(interval '1 month 59 day 25 hour')
+-- !query 49 schema
+struct<justifyHours(1 months 59 days 25 hours):interval>
+-- !query 49 output
+1 months 60 days 1 hours
+
+
+-- !query 50
+select justify_interval(interval '1 month 59 day 25 hour')
+-- !query 50 schema
+struct<justifyInterval(1 months 59 days 25 hours):interval>
+-- !query 50 output
+3 months 1 hours
+
+
+-- !query 51
+select justify_days(interval '1 month -59 day 25 hour')
+-- !query 51 schema
+struct<justifyDays(1 months -59 days 25 hours):interval>
+-- !query 51 output
+-29 days 25 hours
+
+
+-- !query 52
+select justify_hours(interval '1 month -59 day 25 hour')
+-- !query 52 schema
+struct<justifyHours(1 months -59 days 25 hours):interval>
+-- !query 52 output
+1 months -57 days -23 hours
+
+
+-- !query 53
+select justify_interval(interval '1 month -59 day 25 hour')
+-- !query 53 schema
+struct<justifyInterval(1 months -59 days 25 hours):interval>
+-- !query 53 output
+-27 days -23 hours
+
+
+-- !query 54
+select justify_days(interval '1 month 59 day -25 hour')
+-- !query 54 schema
+struct<justifyDays(1 months 59 days -25 hours):interval>
+-- !query 54 output
+2 months 29 days -25 hours
+
+
+-- !query 55
+select justify_hours(interval '1 month 59 day -25 hour')
+-- !query 55 schema
+struct<justifyHours(1 months 59 days -25 hours):interval>
+-- !query 55 output
+1 months 57 days 23 hours
+
+
+-- !query 56
+select justify_interval(interval '1 month 59 day -25 hour')
+-- !query 56 schema
+struct<justifyInterval(1 months 59 days -25 hours):interval>
+-- !query 56 output
+2 months 27 days 23 hours