posixtrounding {clock}  R Documentation 
Rounding: datetime
Description
These are POSIXct/POSIXlt methods for the
rounding generics.

date_floor()
rounds a datetime down to a multiple of
the specified precision
.

date_ceiling()
rounds a datetime up to a multiple of
the specified precision
.

date_round()
rounds up or down depending on what is closer,
rounding up on ties.
You can group by irregular periods such as "month"
or "year"
by using
date_group()
.
Usage
## S3 method for class 'POSIXt'
date_floor(
x,
precision,
...,
n = 1L,
origin = NULL,
nonexistent = NULL,
ambiguous = x
)
## S3 method for class 'POSIXt'
date_ceiling(
x,
precision,
...,
n = 1L,
origin = NULL,
nonexistent = NULL,
ambiguous = x
)
## S3 method for class 'POSIXt'
date_round(
x,
precision,
...,
n = 1L,
origin = NULL,
nonexistent = NULL,
ambiguous = x
)
Arguments
x 
[POSIXct / POSIXlt]
A datetime vector.

precision 
[character(1)]
One of:

"week"

"day"

"hour"

"minute"

"second"
"week" is an alias for "day" with n * 7 .

... 
These dots are for future extensions and must be empty.

n 
[positive integer(1)]
A single positive integer specifying a multiple of precision to use.

origin 
[POSIXct(1) / POSIXlt(1) / NULL]
An origin to start counting from.
origin must have exactly the same time zone as x .
origin will be floored to precision . If information is lost when
flooring, a warning will be thrown.
If NULL , defaults to midnight on 19700101 in the time zone of x .

nonexistent 
[character / NULL]
One of the following nonexistent time resolution strategies, allowed to be
either length 1, or the same length as the input:

"rollforward" : The next valid instant in time.

"rollbackward" : The previous valid instant in time.

"shiftforward" : Shift the nonexistent time forward by the size of
the daylight saving time gap.

"shiftbackward : Shift the nonexistent time backward by the size of
the daylight saving time gap.

"NA" : Replace nonexistent times with NA .

"error" : Error on nonexistent times.
Using either "rollforward" or "rollbackward" is generally
recommended over shifting, as these two strategies maintain the
relative ordering between elements of the input.
If NULL , defaults to "error" .
If getOption("clock.strict") is TRUE , nonexistent must be supplied
and cannot be NULL . This is a convenient way to make production code
robust to nonexistent times.

ambiguous 
[character / zoned_time / POSIXct / list(2) / NULL]
One of the following ambiguous time resolution strategies, allowed to be
either length 1, or the same length as the input:

"earliest" : Of the two possible times, choose the earliest one.

"latest" : Of the two possible times, choose the latest one.

"NA" : Replace ambiguous times with NA .

"error" : Error on ambiguous times.
Alternatively, ambiguous is allowed to be a zoned_time (or POSIXct) that
is either length 1, or the same length as the input. If an ambiguous time
is encountered, the zoned_time is consulted. If the zoned_time corresponds
to a naive_time that is also ambiguous and uses the same daylight saving
time transition point as the original ambiguous time, then the offset of
the zoned_time is used to resolve the ambiguity. If the ambiguity cannot be
resolved by consulting the zoned_time, then this method falls back to
NULL .
Finally, ambiguous is allowed to be a list of size 2, where the first
element of the list is a zoned_time (as described above), and the second
element of the list is an ambiguous time resolution strategy to use when
the ambiguous time cannot be resolved by consulting the zoned_time.
Specifying a zoned_time on its own is identical to list(<zoned_time>, NULL) .
If NULL , defaults to "error" .
If getOption("clock.strict") is TRUE , ambiguous must be supplied and
cannot be NULL . Additionally, ambiguous cannot be specified as a
zoned_time on its own, as this implies NULL for ambiguous times that the
zoned_time cannot resolve. Instead, it must be specified as a list
alongside an ambiguous time resolution strategy as described above. This is
a convenient way to make production code robust to ambiguous times.

Details
When rounding by "week"
, remember that the origin
determines the "week
start". By default, 19700101 is the implicit origin, which is a
Thursday. If you would like to round by weeks with a different week start,
just supply an origin on the weekday you are interested in.
Value
x
rounded to the specified precision
.
Examples
x < as.POSIXct("20190331", "America/New_York")
x < add_days(x, 0:5)
# Flooring by 2 days, note that this is not tied to the current month,
# and instead counts from the specified `origin`, so groups can cross
# the month boundary
date_floor(x, "day", n = 2)
# Compare to `date_group()`, which groups by the day of the month
date_group(x, "day", n = 2)
# Note that daylight saving time gaps can throw off rounding
x < as.POSIXct("19700426 01:59:59", "America/New_York") + c(0, 1)
x
# Rounding is done in naivetime, which means that rounding by 2 hours
# will attempt to generate a time of 19700426 02:00:00, which doesn't
# exist in this time zone
try(date_floor(x, "hour", n = 2))
# You can handle this by specifying a nonexistent time resolution strategy
date_floor(x, "hour", n = 2, nonexistent = "rollforward")
[Package
clock version 0.7.0
Index]