• time_point_floor() rounds a sys-time or naive-time down to a multiple of the specified precision.

  • time_point_ceiling() rounds a sys-time or naive-time up to a multiple of the specified precision.

  • time_point_round() rounds up or down depending on what is closer, rounding up on ties.

Rounding time points is mainly useful for rounding sub-daily time points up to daily time points.

It can also be useful for flooring by a set number of days (like 20) with respect to some origin. By default, the origin is 1970-01-01 00:00:00.

If you want to group by components, such as "day of the month", rather than by "n days", see calendar_group().

time_point_floor(x, precision, ..., n = 1L, origin = NULL)

time_point_ceiling(x, precision, ..., n = 1L, origin = NULL)

time_point_round(x, precision, ..., n = 1L, origin = NULL)

Arguments

x

[clock_sys_time / clock_naive_time]

A sys-time or naive-time.

precision

[character(1)]

A time point precision. One of:

  • "day"

  • "hour"

  • "minute"

  • "second"

  • "millisecond"

  • "microsecond"

  • "nanosecond"

...

These dots are for future extensions and must be empty.

n

[positive integer(1)]

A positive integer specifying the multiple of precision to use.

origin

[clock_sys_time(1) / clock_naive_time(1) / NULL]

An origin to begin counting from. Mostly useful when n > 1 and you want to control how the rounding groups are created.

If x is a sys-time, origin must be a sys-time.

If x is a naive-time, origin must be a naive-time.

The precision of origin must be equally precise as or less precise than precision.

If NULL, a default origin of midnight on 1970-01-01 is used.

Value

x rounded to the new precision.

Boundary Handling

To understand how flooring and ceiling work, you need to know how they create their intervals for rounding.

  • time_point_floor() constructs intervals of [lower, upper) that bound each element of x, then always chooses the left-hand side.

  • time_point_ceiling() constructs intervals of (lower, upper] that bound each element of x, then always chooses the right-hand side.

As an easy example, consider 2020-01-02 00:00:05.

To floor this to the nearest day, the following interval is constructed, and the left-hand side is returned at day precision:

[2020-01-02 00:00:00, 2020-01-03 00:00:00)

To ceiling this to the nearest day, the following interval is constructed, and the right-hand side is returned at day precision:

(2020-01-02 00:00:00, 2020-01-03 00:00:00]

Here is another example, this time with a time point on a boundary, 2020-01-02 00:00:00.

To floor this to the nearest day, the following interval is constructed, and the left-hand side is returned at day precision:

[2020-01-02 00:00:00, 2020-01-03 00:00:00)

To ceiling this to the nearest day, the following interval is constructed, and the right-hand side is returned at day precision:

(2020-01-01 00:00:00, 2020-01-02 00:00:00]

Notice that, regardless of whether you are doing a floor or ceiling, if the input falls on a boundary then it will be returned as is.

Examples

library(magrittr) x <- as_naive_time(year_month_day(2019, 01, 01)) x <- add_days(x, 0:40) head(x)
#> <time_point<naive><day>[6]> #> [1] "2019-01-01" "2019-01-02" "2019-01-03" "2019-01-04" "2019-01-05" #> [6] "2019-01-06"
# Floor by sets of 20 days # The implicit origin to start the 20 day counter is 1970-01-01 time_point_floor(x, "day", n = 20)
#> <time_point<naive><day>[41]> #> [1] "2018-12-15" "2018-12-15" "2018-12-15" "2019-01-04" "2019-01-04" #> [6] "2019-01-04" "2019-01-04" "2019-01-04" "2019-01-04" "2019-01-04" #> [11] "2019-01-04" "2019-01-04" "2019-01-04" "2019-01-04" "2019-01-04" #> [16] "2019-01-04" "2019-01-04" "2019-01-04" "2019-01-04" "2019-01-04" #> [21] "2019-01-04" "2019-01-04" "2019-01-04" "2019-01-24" "2019-01-24" #> [26] "2019-01-24" "2019-01-24" "2019-01-24" "2019-01-24" "2019-01-24" #> [31] "2019-01-24" "2019-01-24" "2019-01-24" "2019-01-24" "2019-01-24" #> [36] "2019-01-24" "2019-01-24" "2019-01-24" "2019-01-24" "2019-01-24" #> [41] "2019-01-24"
# You can easily customize the origin by creating a duration out of the # origin date of interest... origin <- year_month_day(2019, 01, 01) %>% as_naive_time() %>% as_duration() # Which you can subtract from, floor, and then add to your input time_point_floor(x - origin, "day", n = 20) + origin
#> <time_point<naive><day>[41]> #> [1] "2019-01-01" "2019-01-01" "2019-01-01" "2019-01-01" "2019-01-01" #> [6] "2019-01-01" "2019-01-01" "2019-01-01" "2019-01-01" "2019-01-01" #> [11] "2019-01-01" "2019-01-01" "2019-01-01" "2019-01-01" "2019-01-01" #> [16] "2019-01-01" "2019-01-01" "2019-01-01" "2019-01-01" "2019-01-01" #> [21] "2019-01-21" "2019-01-21" "2019-01-21" "2019-01-21" "2019-01-21" #> [26] "2019-01-21" "2019-01-21" "2019-01-21" "2019-01-21" "2019-01-21" #> [31] "2019-01-21" "2019-01-21" "2019-01-21" "2019-01-21" "2019-01-21" #> [36] "2019-01-21" "2019-01-21" "2019-01-21" "2019-01-21" "2019-01-21" #> [41] "2019-02-10"
# For times on the boundary, floor and ceiling both return the input # at the new precision. Notice how the first element is on the boundary, # and the second is 1 second after the boundary. y <- as_naive_time(year_month_day(2020, 01, 02, 00, 00, c(00, 01))) time_point_floor(y, "day")
#> <time_point<naive><day>[2]> #> [1] "2020-01-02" "2020-01-02"
time_point_ceiling(y, "day")
#> <time_point<naive><day>[2]> #> [1] "2020-01-02" "2020-01-03"