Update java datetime APIs to match CUDF.

java/src/main/java/ai/rapids/cudf/ColumnView.java

@@ -917,6 +917,16 @@ public final ColumnVector mergeAndSetValidity(BinaryOp mergeOp, ColumnView... co
   // DATE/TIME
   /////////////////////////////////////////////////////////////////////////////
 
+  /**
+   * Extract a particular date time component from a timestamp.
+   * @param component what should be extracted
+   * @return a column with the extracted information in it.
+   */
+  public final ColumnVector extractDateTimeComponent(DateTimeComponent component) {
+    assert type.isTimestampType();
+    return new ColumnVector(extractDateTimeComponent(getNativeView(), component.getNativeId()));
+  }
+
   /**
    * Get year from a timestamp.
    * <p>
@@ -925,8 +935,7 @@ public final ColumnVector mergeAndSetValidity(BinaryOp mergeOp, ColumnView... co
    * @return - A new INT16 vector allocated on the GPU.
    */
   public final ColumnVector year() {
-    assert type.isTimestampType();
-    return new ColumnVector(year(getNativeView()));
+    return extractDateTimeComponent(DateTimeComponent.YEAR);
   }
 
   /**
@@ -937,8 +946,7 @@ public final ColumnVector year() {
    * @return - A new INT16 vector allocated on the GPU.
    */
   public final ColumnVector month() {
-    assert type.isTimestampType();
-    return new ColumnVector(month(getNativeView()));
+    return extractDateTimeComponent(DateTimeComponent.MONTH);
   }
 
   /**
@@ -949,8 +957,7 @@ public final ColumnVector month() {
    * @return - A new INT16 vector allocated on the GPU.
    */
   public final ColumnVector day() {
-    assert type.isTimestampType();
-    return new ColumnVector(day(getNativeView()));
+    return extractDateTimeComponent(DateTimeComponent.DAY);
   }
 
   /**
@@ -961,8 +968,7 @@ public final ColumnVector day() {
    * @return - A new INT16 vector allocated on the GPU.
    */
   public final ColumnVector hour() {
-    assert type.hasTimeResolution();
-    return new ColumnVector(hour(getNativeView()));
+    return extractDateTimeComponent(DateTimeComponent.HOUR);
   }
 
   /**
@@ -973,8 +979,7 @@ public final ColumnVector hour() {
    * @return - A new INT16 vector allocated on the GPU.
    */
   public final ColumnVector minute() {
-    assert type.hasTimeResolution();
-    return new ColumnVector(minute(getNativeView()));
+    return extractDateTimeComponent(DateTimeComponent.MINUTE);
   }
 
   /**
@@ -985,8 +990,7 @@ public final ColumnVector minute() {
    * @return A new INT16 vector allocated on the GPU.
    */
   public final ColumnVector second() {
-    assert type.hasTimeResolution();
-    return new ColumnVector(second(getNativeView()));
+    return extractDateTimeComponent(DateTimeComponent.SECOND);
   }
 
   /**
@@ -997,8 +1001,7 @@ public final ColumnVector second() {
    * @return A new INT16 vector allocated on the GPU. Monday=1, ..., Sunday=7
    */
   public final ColumnVector weekDay() {
-    assert type.isTimestampType();
-    return new ColumnVector(weekDay(getNativeView()));
+    return extractDateTimeComponent(DateTimeComponent.WEEKDAY);
   }
 
   /**
@@ -1045,6 +1048,16 @@ public final ColumnVector addCalendricalMonths(ColumnView months) {
     return new ColumnVector(addCalendricalMonths(getNativeView(), months.getNativeView()));
   }
 
+  /**
+   * Add the specified number of months to the timestamp.
+   * @param months must be a INT16 column indicating the number of months to add. A negative number
+   *               of months works too.
+   * @return the updated timestamp
+   */
+  public final ColumnVector addCalendricalMonths(Scalar months) {
+    return new ColumnVector(addScalarCalendricalMonths(getNativeView(), months.getScalarHandle()));
+  }
+
   /**
    * Check to see if the year for this timestamp is a leap year or not.
    * @return BOOL8 vector of results
@@ -1053,6 +1066,45 @@ public final ColumnVector isLeapYear() {
     return new ColumnVector(isLeapYear(getNativeView()));
   }
 
+  /**
+   * Extract the number of days in the month
+   * @return INT16 column of the number of days in the correspond month
+   */
+  public final ColumnVector daysInMonth() {
+    assert type.isTimestampType();
+    return new ColumnVector(daysInMonth(getNativeView()));
+  }
+
+  /**
+   * Round the timestamp up to the given frequency keeping the type the same.
+   * @param freq what part of the timestamp to round.
+   * @return a timestamp with the same type, but rounded up.
+   */
+  public final ColumnVector dateTimeCeil(DateTimeRoundingFrequency freq) {
+    assert type.isTimestampType();
+    return new ColumnVector(dateTimeCeil(getNativeView(), freq.getNativeId()));
+  }
+
+  /**
+   * Round the timestamp down to the given frequency keeping the type the same.
+   * @param freq what part of the timestamp to round.
+   * @return a timestamp with the same type, but rounded down.
+   */
+  public final ColumnVector dateTimeFloor(DateTimeRoundingFrequency freq) {
+    assert type.isTimestampType();
+    return new ColumnVector(dateTimeFloor(getNativeView(), freq.getNativeId()));
+  }
+
+  /**
+   * Round the timestamp (half up) to the given frequency keeping the type the same.
+   * @param freq what part of the timestamp to round.
+   * @return a timestamp with the same type, but rounded (half up).
+   */
+  public final ColumnVector dateTimeRound(DateTimeRoundingFrequency freq) {
+    assert type.isTimestampType();
+    return new ColumnVector(dateTimeRound(getNativeView(), freq.getNativeId()));
+  }
+
   /**
    * Rounds all the values in a column to the specified number of decimal places.
    *
@@ -4684,19 +4736,7 @@ private static native long segmentedGather(long sourceColumnHandle, long gatherM
 
   private static native long unaryOperation(long viewHandle, int op);
 
-  private static native long year(long viewHandle) throws CudfException;
-
-  private static native long month(long viewHandle) throws CudfException;
-
-  private static native long day(long viewHandle) throws CudfException;
-
-  private static native long hour(long viewHandle) throws CudfException;
-
-  private static native long minute(long viewHandle) throws CudfException;
-
-  private static native long second(long viewHandle) throws CudfException;
-
-  private static native long weekDay(long viewHandle) throws CudfException;
+  private static native long extractDateTimeComponent(long viewHandle, int component);
 
   private static native long lastDayOfMonth(long viewHandle) throws CudfException;
 
@@ -4706,8 +4746,18 @@ private static native long segmentedGather(long sourceColumnHandle, long gatherM
 
   private static native long addCalendricalMonths(long tsViewHandle, long monthsViewHandle);
 
+  private static native long addScalarCalendricalMonths(long tsViewHandle, long scalarHandle);
+
   private static native long isLeapYear(long viewHandle) throws CudfException;
 
+  private static native long daysInMonth(long viewHandle) throws CudfException;
+
+  private static native long dateTimeCeil(long viewHandle, int freq);
+
+  private static native long dateTimeFloor(long viewHandle, int freq);
+
+  private static native long dateTimeRound(long viewHandle, int freq);
+
   private static native boolean containsScalar(long columnViewHaystack, long scalarHandle) throws CudfException;
 
   private static native long containsVector(long valuesHandle, long searchSpaceHandle) throws CudfException;

java/src/main/java/ai/rapids/cudf/DateTimeComponent.java

@@ -0,0 +1,74 @@
+/*
+ *
+ *  Copyright (c) 2024, NVIDIA CORPORATION.
+ *
+ *  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
+ *
+ *      http://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.
+ *
+ */
+
+package ai.rapids.cudf;
+
+/**
+ * Types of datetime components that may be extracted.
+ */
+public enum DateTimeComponent {
+  /**
+   * year as an INT16
+   */
+  YEAR(0),
+  /**
+   * month 1 - jan, as an INT16
+   */
+  MONTH(1),
+  /**
+   * Day of the month as an INT16
+   */
+  DAY(2),
+  /**
+   * day of the week, Monday=1, ..., Sunday=7 as an INT16
+   */
+  WEEKDAY(3),
+  /**
+   * hour of the day 24-hour clock as an INT16
+   */
+  HOUR(4),
+  /**
+   * minutes past the hour as an INT16
+   */
+  MINUTE(5),
+  /**
+   * seconds past the minute as an INT16
+   */
+  SECOND(6),
+  /**
+   * milliseconds past the seconds as an INT16
+   */
+  MILLISECOND(7),
+  /**
+   * microseconds past the millisecond as an INT16
+   */
+  MICROSECOND(8),
+  /**
+   * nanoseconds past the microsecond as an INT16
+   */
+  NANOSECOND(9);
+
+  final int id;
+  DateTimeComponent(int id) {
+    this.id = id;
+  }
+
+  public int getNativeId() {
+    return id;
+  }
+}

java/src/main/java/ai/rapids/cudf/DateTimeRoundingFrequency.java

@@ -0,0 +1,38 @@
+/*
+ *
+ *  Copyright (c) 2024, NVIDIA CORPORATION.
+ *
+ *  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
+ *
+ *      http://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.
+ *
+ */
+
+package ai.rapids.cudf;
+
+public enum DateTimeRoundingFrequency {
+  DAY(0),
+  HOUR(1),
+  MINUTE(2),
+  SECOND(3),
+  MILLISECOND(4),
+  MICROSECOND(5),
+  NANOSECOND(6);
+
+  final int id;
+  DateTimeRoundingFrequency(int id) {
+    this.id = id;
+  }
+
+  public int getNativeId() {
+    return id;
+  }
+}