Skip to contents

Update components of a date-time object

Source: R/update.R
time_update.Rd

Update components of a date-time object

Usage

time_update(
  time,
  updates = NULL,
  year = NULL,
  month = NULL,
  yday = NULL,
  mday = NULL,
  wday = NULL,
  hour = NULL,
  minute = NULL,
  second = NULL,
  tz = NULL,
  roll_month = "preday",
  roll_dst = c("boundary", "post"),
  week_start = getOption("timechange.week_start", 1),
  exact = FALSE
)

Arguments

time

a date-time object

updates

a named list of components

year, month, yday, wday, mday, hour, minute, second

components of the date-time to be updated. All components except second will be converted to integer. Components are replicated according to vctrs semantics, i.e. vectors must be either of length 1 or same length as time vector.

tz

time zone component (a singleton character vector)

roll_month

controls how addition of months and years behaves when standard arithmetic rules exceed limits of the resulting date's month. Possible values are "preday", "boundary", "postday", "full" and "NA". See "Details" or [(timechange::time_add()) for further details.

roll_dst

is a string vector of length one or two. When two values are supplied they specify how to roll date-times when they fall into "skipped" and "repeated" DST transitions respectively. A single value is replicated to the length of two. Possible values are:

* `pre` - Use the time before the transition boundary.
* `boundary` - Use the time exactly at the boundary transition.
* `post` - Use the time after the boundary transition.
* `xfirst` - crossed-first: First time which occurred when crossing the
   boundary. For addition with positive units pre interval is crossed first and
   post interval last. With negative units post interval is crossed first, pre -
   last. For subtraction the logic is reversed.
* `xlast` - crossed-last.
* `NA` - Produce NAs when the resulting time falls inside the problematic interval.

For example `roll_dst = c("NA", "pre") indicates that for skipped intervals return NA and for repeated times return the earlier time.

When multiple units are supplied the meaning of "negative period" is determined by the largest unit. For example time_add(t, days = -1, hours = 2, roll_dst = "xfirst") would operate as if with negative period, thus crossing the boundary from the "post" to "pre" side and "xfirst" and hence resolving to "post" time. As this might result in confusing behavior. See examples.

"xfirst" and "xlast" make sense for addition and subtraction only. An error is raised if an attempt is made to use them with other functions.

week_start

first day of the week (default is 1, Monday). Set timechange.week_start option to change this globally.

exact

logical (TRUE), whether the update should be exact. If set to FALSE no rolling or unit-recycling is allowed and NA is produced whenever the units of the end date-time don't match the provided units. This can occur when an end date falls into a gap (e.g. DST or Feb.29) or when large components (e.g. hour = 25) are supplied and result in crossing boundaries of higher units. When exact = TRUE, roll_month and roll_dst arguments are ignored.

Value

A date-time with the requested elements updated. Retain its original class unless the original class is Date and at least one of the hour, minute, second or tz is supplied, in which case a POSIXct object is returned.

See also

[time_add()]

Examples


date <- as.Date("2009-02-10")
time_update(date, year = 2010, month = 1, mday = 1)
#> [1] "2010-01-01"
time_update(date, year = 2010, month = 13, mday = 1)
#> [1] "2011-01-01"
time_update(date, minute = 10, second = 3)
#> [1] "2009-02-10 00:10:03 UTC"
time_update(date, minute = 10, second = 3, tz = "America/New_York")
#> [1] "2009-02-10 00:10:03 EST"

time <- as.POSIXct("2015-02-03 01:02:03", tz = "America/New_York")
time_update(time, month = 2, mday = 31, roll_month = "preday")
#> [1] "2015-02-28 01:02:03 EST"
time_update(time, month = 2, mday = 31, roll_month = "boundary")
#> [1] "2015-03-01 EST"
time_update(time, month = 2, mday = 31, roll_month = "postday")
#> [1] "2015-03-01 01:02:03 EST"
time_update(time, month = 2, mday = 31, exact = TRUE)
#> [1] NA
time_update(time, month = 2, mday = 31, exact = FALSE)
#> [1] "2015-02-28 01:02:03 EST"

## DST skipped
time <- as.POSIXct("2015-02-03 01:02:03", tz = "America/New_York")
time_update(time, year = 2016, yday = 10)
#> [1] "2016-01-10 01:02:03 EST"
time_update(time, year = 2016, yday = 10, tz = "Europe/Amsterdam")
#> [1] "2016-01-10 01:02:03 CET"
time_update(time, second = 30,  tz = "America/New_York")
#> [1] "2015-02-03 01:02:30 EST"