time-point-rounding: Time point rounding

Description Usage Arguments Value Boundary Handling Examples

Description

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().

Usage

1
2
3
4
5
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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
library(magrittr)

x <- as_naive_time(year_month_day(2019, 01, 01))
x <- add_days(x, 0:40)
head(x)

# 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)

# 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

# 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_ceiling(y, "day")

clock documentation built on July 23, 2021, 1:06 a.m.