lidavidm commented on a change in pull request #10960: URL: https://github.com/apache/arrow/pull/10960#discussion_r711028573
########## 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: Yeah, I wasn't sure how to disambiguate these. Note that month_interval_between and months_between are basically redundant, except MonthIntervalType is int32_t, not int64_t. -- 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]
