diff --git a/core/src/main/scala/doric/syntax/DateColumns.scala b/core/src/main/scala/doric/syntax/DateColumns.scala index ea66cfa99..78245b743 100644 --- a/core/src/main/scala/doric/syntax/DateColumns.scala +++ b/core/src/main/scala/doric/syntax/DateColumns.scala @@ -23,22 +23,24 @@ private[syntax] trait DateColumns { ) { /** - * Adds to the date the number of months + * Adds to the Date or Timestamp column the number of months * * @group Date & Timestamp Type * @param nMonths * the number of months to add, can be negative to subtract. * @return - * DoricColumn of the same type as the original with the month changed. + * Date column after adding months + * @note Timestamp columns will be truncated to Date column */ def addMonths(nMonths: IntegerColumn): DateColumn = (column.elem, nMonths.elem).mapN(f.add_months).toDC /** - * Returns the date that is `days` days after `start` + * Returns the date that is `days` days after date column * - * @param days A column of the number of days to add to `start`, can be negative to subtract days + * @param days A column of the number of days to add to date column, can be negative to subtract days * @group Date & Timestamp Type + * @note Timestamp columns will be truncated to Date column */ def addDays(days: IntegerColumn): DateColumn = (column.elem, days.elem).mapN(f.date_add).toDC @@ -60,19 +62,20 @@ private[syntax] trait DateColumns { .toDC /** - * Returns the date that is `days` days before `start` + * Returns the date that is `days` days before date column * - * @param days A column of the number of days to subtract from `start`, can be negative to add + * @param days A column of the number of days to subtract from date column, can be negative to add * days * @group Date & Timestamp Type + * @note Timestamp columns will be truncated to Date column */ def subDays(days: IntegerColumn): DateColumn = (column.elem, days.elem).mapN(f.date_sub).toDC /** - * Returns the number of days from `start` to `end`. + * Returns the number of days from date column to `dateCol`. * - * @param dateCol A date, timestamp or string. If a string, the data must be in a format that + * @param dateCol A Date or Timestamp column. If a string, the data must be in a format that * can be cast to a date, such as `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss.SSSS` * @group Date & Timestamp Type */ @@ -105,6 +108,7 @@ private[syntax] trait DateColumns { /** * Sets the moment to the last day of the same month. + * * @group Date & Timestamp Type */ def endOfMonth: DateColumn = lastDayOfMonth @@ -126,28 +130,28 @@ private[syntax] trait DateColumns { def month: IntegerColumn = column.elem.map(f.month).toDC /** - * Returns number of months between dates `start` and `end`. + * Returns number of months between dates date column and `dateCol`. * * A whole number is returned if both inputs have the same day of month or both are the last day * of their respective months. Otherwise, the difference is calculated assuming 31 days per month. * * For example: * {{{ - * months_between("2017-11-14", "2017-07-14") // returns 4.0 - * months_between("2017-01-01", "2017-01-10") // returns 0.29032258 - * months_between("2017-06-01", "2017-06-16 12:00:00") // returns -0.5 + * Date("2017-11-14").monthsBetween(Date("2017-07-14")) // returns 4.0 + * Date("2017-01-01").monthsBetween(Date("2017-01-10")) // returns 0.29032258 + * Timestamp("2017-06-01 00:00:00").monthsBetween(Timestamp("2017-06-16 12:00:00")) // returns -0.5 * }}} * - * @param dateCol Date column + * @param dateCol Date or Timestamp column * @group Date & Timestamp Type */ def monthsBetween(dateCol: DoricColumn[T]): DoubleColumn = (column.elem, dateCol.elem).mapN(f.months_between).toDC /** - * Returns number of months between dates `end` and `start`. + * Returns number of months between dates `dateCol` and date column. * - * @param dateCol Date column + * @param dateCol Date or Timestamp column * @param roundOff If `roundOff` is set to true, the result is rounded off to 8 digits; * it is not rounded otherwise. * @group Date & Timestamp Type @@ -166,11 +170,12 @@ private[syntax] trait DateColumns { * Returns the first date which is later than the value of the `date` column that is on the * specified day of the week. * - * For example, `next_day('2015-07-27', "Sunday")` returns 2015-08-02 because that is the first - * Sunday after 2015-07-27. + * For example, `Date("2015-07-27").nextDay("Sunday")` returns Date("2015-08-02") because + * that is the first Sunday after 2015-07-27. * * @param dayOfWeek Case insensitive, and accepts: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" * @group Date & Timestamp Type + * @note Timestamp columns will be truncated to Date column */ def nextDay(dayOfWeek: StringColumn): DateColumn = (column.elem, dayOfWeek.elem) @@ -189,12 +194,13 @@ private[syntax] trait DateColumns { /** * Returns date truncated to the unit specified by the format. * - * For example, `trunc("2018-11-19 12:01:19", "year")` returns 2018-01-01 + * For example, `Timestamp("2018-11-19 12:01:19").trunc("year")` returns Date("2018-01-01") * * @param format 'year', 'yyyy', 'yy' to truncate by year, * or 'month', 'mon', 'mm' to truncate by month * Other options are: 'week', 'quarter' * @group Date & Timestamp Type + * @note Timestamp columns will be truncated to Date column */ def trunc(format: StringColumn): DateColumn = (column.elem, format.elem)