apache / apache/arrow

[C++] Support rolling backwards and forwards with temporal arithmetic

Open
#31,334 6 comments 0 reactions 1 assignee Claimed by @rok View on GitHub
Component: C++ Type: task
Dominant language
C++
Stars
17.1k
Forks
4.3k
Avg merge
3d 13h
Merged PRs (30d)
88

Description

Original description in ARROW-11090:
"This should also cover the ability to do with and without rollback (so have the ability to do e.g. 2021-03-30 minus 1 month and either get a null back, or 2021-02-28), plus the ability to specify whether to rollback to the first or last, and whether to preserve or rest the time.)"

For example, in R, lubridate has the following functionality:

- `rollbackward()` or `rollback()` which changes a date to the last day of the previous month or to the first day of the current month
- `rollforward()` which rolls to the last day of the current month or to the first day of the next month.
- all of the above also offer the option to preserve hms (hours, minutes and seconds) when rolling.

This functionality underpins functions such as `%m-%` and `%m+%` which are used to add or subtract months to a date without exceeding the last day of the new month.

{code:r}
library(lubridate)

jan <- ymd_hms("2010-01-31 03:04:05")
jan + months(1:3) # Feb 31 and April 31 returned as NA
#> [1] NA "2010-03-31 03:04:05 UTC"
#> [3] NA
1. NA "2010-03-31 03:04:05 UTC" NA
jan %m+% months(1:3) # No rollover
#> [1] "2010-02-28 03:04:05 UTC" "2010-03-31 03:04:05 UTC"
#> [3] "2010-04-30 03:04:05 UTC"

leap <- ymd("2012-02-29")
"2012-02-29 UTC"
#> [1] "2012-02-29 UTC"
leap %m+% years(1)
#> [1] "2013-02-28"
leap %m+% years(-1)
#> [1] "2011-02-28"
leap %m-% years(1)
#> [1] "2011-02-28"

x <- ymd_hms("2019-01-29 01:02:03")
add_with_rollback(x, months(1))
#> [1] "2019-02-28 01:02:03 UTC"
add_with_rollback(x, months(1), preserve_hms = FALSE)
#> [1] "2019-02-28 UTC"
add_with_rollback(x, months(1), roll_to_first = TRUE)
#> [1] "2019-03-01 01:02:03 UTC"
add_with_rollback(x, months(1), roll_to_first = TRUE, preserve_hms = FALSE)
#> [1] "2019-03-01 UTC"
{code}

**Reporter**: [Dragoș Moldovan-Grünfeld](https://issues.apache.org/jira/browse/ARROW-15904) / @dragosmg
**Assignee**: [Rok Mihevc](https://issues.apache.org/jira/browse/ARROW-15904) / @rok
**Watchers**: [Rok Mihevc](https://issues.apache.org/jira/browse/ARROW-15904) / @rok
#### Related issues:
- [[R] Implement lubridate's %m+%, %m-%, add_with_rollback, and addition and subtraction with timestamp](https://github.com/apache/arrow/issues/30470) (is depended upon by)
- [[R] Implement lubridate functions for doing maths with dates](https://github.com/apache/arrow/issues/30467) (is depended upon by)

**Note**: *This issue was originally created as [ARROW-15904](https://issues.apache.org/jira/browse/ARROW-15904). Please see the [migration documentation](https://github.com/apache/arrow/issues/14542) for further details.*

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.