posixt-setters | R Documentation |
Setters: date-time
Description
These are POSIXct/POSIXlt methods for the setter generics.
-
set_year()
sets the year.
-
set_month()
sets the month of the year. Valid values are in the range
of [1, 12]
.
-
set_day()
sets the day of the month. Valid values are in the range
of [1, 31]
.
There are sub-daily setters for setting more precise components, up to
a precision of seconds.
Usage
## S3 method for class 'POSIXt'
set_year(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
set_month(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
set_day(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
set_hour(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
set_minute(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
set_second(x, value, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
Arguments
x |
[POSIXct / POSIXlt]
A date-time vector.
|
value |
[integer / "last"]
The value to set the component to.
For set_day() , this can also be "last" to set the day to the
last day of the month.
|
... |
These dots are for future extensions and must be empty.
|
invalid |
[character(1) / NULL]
One of the following invalid date resolution strategies:
-
"previous" : The previous valid instant in time.
-
"previous-day" : The previous valid day in time, keeping the time of
day.
-
"next" : The next valid instant in time.
-
"next-day" : The next valid day in time, keeping the time of day.
-
"overflow" : Overflow by the number of days that the input is invalid
by. Time of day is dropped.
-
"overflow-day" : Overflow by the number of days that the input is
invalid by. Time of day is kept.
-
"NA" : Replace invalid dates with NA .
-
"error" : Error on invalid dates.
Using either "previous" or "next" is generally recommended, as these
two strategies maintain the relative ordering between elements of the
input.
If NULL , defaults to "error" .
If getOption("clock.strict") is TRUE , invalid must be supplied and
cannot be NULL . This is a convenient way to make production code robust
to invalid dates.
|
nonexistent |
[character / NULL]
One of the following nonexistent time resolution strategies, allowed to be
either length 1, or the same length as the input:
-
"roll-forward" : The next valid instant in time.
-
"roll-backward" : The previous valid instant in time.
-
"shift-forward" : Shift the nonexistent time forward by the size of
the daylight saving time gap.
-
"shift-backward : 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 "roll-forward" or "roll-backward" 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.
|
Value
x
with the component set.
Examples
x <- as.POSIXct("2019-02-01", tz = "America/New_York")
# Set the day
set_day(x, 12:14)
# Set to the "last" day of the month
set_day(x, "last")
# You cannot set a date-time to an invalid date like you can with
# a year-month-day. Instead, the default strategy is to error.
try(set_day(x, 31))
set_day(as_year_month_day(x), 31)
# You can resolve these issues while setting the day by specifying
# an invalid date resolution strategy with `invalid`
set_day(x, 31, invalid = "previous")
y <- as.POSIXct("2020-03-08 01:30:00", tz = "America/New_York")
# Nonexistent and ambiguous times must be resolved immediately when
# working with R's native date-time types. An error is thrown by default.
try(set_hour(y, 2))
set_hour(y, 2, nonexistent = "roll-forward")
set_hour(y, 2, nonexistent = "roll-backward")