rok commented on a change in pull request #10960:
URL: https://github.com/apache/arrow/pull/10960#discussion_r710554635
##########
File path: cpp/src/arrow/compute/kernels/scalar_temporal.cc
##########
@@ -1103,6 +1399,115 @@ const FunctionDoc assume_timezone_doc{
{"timestamps"},
"AssumeTimezoneOptions"};
+const FunctionDoc years_between_doc{
+ "Compute the number of years between two timestamps",
+ ("Returns the number of year boundaries crossed from the first timestamp
to the\n"
+ "second. That is, the difference is calculated as if the timestamps
were\n"
+ "truncated to the year.\n"
+ "Null values emit null."),
+ {"start", "end"}};
+
+const FunctionDoc quarters_between_doc{
+ "Compute the number of quarters between two timestamps",
+ ("Returns the number of quarter start boundaries crossed from the first
timestamp\n"
+ "to the second. That is, the difference is calculated as if the
timestamps were\n"
+ "truncated to the quarter.\n"
+ "Null values emit null."),
+ {"start", "end"}};
+
+const FunctionDoc months_between_doc{
+ "Compute the number of months between two timestamps",
+ ("Returns the number of month boundaries crossed from the first
timestamp\n"
+ "to the second. That is, the difference is calculated as if the
timestamps were\n"
+ "truncated to the month.\n"
+ "Null values emit null."),
+ {"start", "end"}};
+
+const FunctionDoc month_day_nano_interval_between_doc{
+ "Compute the number of months, days and nanoseconds between two
timestamps",
+ ("Returns the number of months, days, and milliseconds from the first
timestamp\n"
Review comment:
```suggestion
("Returns the number of months, days, and nanoseconds from the first
timestamp\n"
```
##########
File path: cpp/src/arrow/compute/kernels/scalar_temporal.cc
##########
@@ -1103,6 +1399,115 @@ const FunctionDoc assume_timezone_doc{
{"timestamps"},
"AssumeTimezoneOptions"};
+const FunctionDoc years_between_doc{
+ "Compute the number of years between two timestamps",
+ ("Returns the number of year boundaries crossed from the first timestamp
to the\n"
Review comment:
Should `\n`s appear mid sentence? Same below.
##########
File path: cpp/src/arrow/compute/kernels/scalar_temporal.cc
##########
@@ -1103,6 +1399,115 @@ const FunctionDoc assume_timezone_doc{
{"timestamps"},
"AssumeTimezoneOptions"};
+const FunctionDoc years_between_doc{
+ "Compute the number of years between two timestamps",
+ ("Returns the number of year boundaries crossed from the first timestamp
to the\n"
Review comment:
Should `\n`s appear mid sentence?
##########
File path: cpp/src/arrow/compute/kernels/scalar_temporal.cc
##########
@@ -1103,6 +1399,115 @@ const FunctionDoc assume_timezone_doc{
{"timestamps"},
"AssumeTimezoneOptions"};
+const FunctionDoc years_between_doc{
+ "Compute the number of years between two timestamps",
+ ("Returns the number of year boundaries crossed from the first timestamp
to the\n"
+ "second. That is, the difference is calculated as if the timestamps
were\n"
+ "truncated to the year.\n"
+ "Null values emit null."),
+ {"start", "end"}};
+
+const FunctionDoc quarters_between_doc{
+ "Compute the number of quarters between two timestamps",
+ ("Returns the number of quarter start boundaries crossed from the first
timestamp\n"
+ "to the second. That is, the difference is calculated as if the
timestamps were\n"
+ "truncated to the quarter.\n"
+ "Null values emit null."),
+ {"start", "end"}};
+
+const FunctionDoc months_between_doc{
+ "Compute the number of months between two timestamps",
+ ("Returns the number of month boundaries crossed from the first
timestamp\n"
+ "to the second. That is, the difference is calculated as if the
timestamps were\n"
+ "truncated to the month.\n"
+ "Null values emit null."),
+ {"start", "end"}};
+
+const FunctionDoc month_day_nano_interval_between_doc{
+ "Compute the number of months, days and nanoseconds between two
timestamps",
+ ("Returns the number of months, days, and milliseconds from the first
timestamp\n"
+ "to the second. That is, first the difference in months is computed as if
both\n"
+ "timestamps were truncated to the months, then the then the difference
between "
+ "time times\n"
+ "of the two timestamps is computed as if both times were truncated to
the\n"
+ "millisecond.\n"
Review comment:
```suggestion
"nanosecond.\n"
```
##########
File path: docs/source/cpp/compute.rst
##########
@@ -1356,6 +1356,50 @@ For timestamps inputs with non-empty timezone, localized
timestamp components wi
.. _ISO 8601 week date definition:
https://en.wikipedia.org/wiki/ISO_week_date#First_week
+Temporal difference
+~~~~~~~~~~~~~~~~~~~
+
+These functions compute the difference between two timestamps in the
+specified unit. The difference is determined by the number of
+boundaries crossed, not the span of time. For example, the difference
+in days between 23:59:59 on one day and 00:00:01 on the next day is
+one day (since midnight was crossed), not zero days (even though less
+than 24 hours elapsed). Additionally, if the timestamp is zoned, the
+difference is calculated in the local timezone. For instance, the
+difference in years between "2019-12-31 18:00:00-0500" and "2019-12-31
+23:00:00-0500" is zero years, even though the underlying values in UTC
+do differ by a year.
+
++---------------------------------+------------+-------------------+-----------------------+----------------------------+-------+
+| Function name | Arity | Input types | Output
type | Options class | Notes |
++=================================+============+===================+=======================+============================+=======+
+| day_time_interval_between | Binary | Timestamp | DayTime
interval | | |
++---------------------------------+------------+-------------------+-----------------------+----------------------------+-------+
+| days_between | Binary | Timestamp | Int64
| | |
++---------------------------------+------------+-------------------+-----------------------+----------------------------+-------+
+| hours_between | Binary | Timestamp | Int64
| | |
++---------------------------------+------------+-------------------+-----------------------+----------------------------+-------+
+| microseconds_between | Binary | Timestamp | Int64
| | |
++---------------------------------+------------+-------------------+-----------------------+----------------------------+-------+
+| milliseconds_between | Binary | Timestamp | Int64
| | |
++---------------------------------+------------+-------------------+-----------------------+----------------------------+-------+
+| minutes_between | Binary | Timestamp | Int64
| | |
++---------------------------------+------------+-------------------+-----------------------+----------------------------+-------+
+| month_interval_between | Binary | Timestamp | Month
interval | | |
Review comment:
Sometimes you use `_interval_` and sometimes you don't. I realize it's
due to the type returned but it still bothers my eyes :). Probably best keep it
as is.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
