date_time: Construct Date-Time Indices from Date and Time Components

Description

date_time can be used to create date-time indices from its components: date and time of day (hour, minute, and second).

date_time_split performs the opposite computation: given date-time indices, it returns a two-element list with vectors of dates and times.

Usage

date_time(d, H, M, S, tz = NULL, grid = FALSE)
date_time_split(x)

Value

date_time returns an object of tind class with date-time indices (type "t"). date_time_split

returns a two-element list with vectors of dates ($date) and times ($time).

Arguments

d: an object of tind class of type date (type "d") or an R object coercible to it.
H: a numeric vector with hour values or an R object coercible to time index of time-of-day type (type "h").
M: (optional) a numeric vector with minutes.
S: (optional) a numeric vector with seconds.
tz: (optional) a character value determining the time zone (the default NULL is interpreted as the system time zone). See tzone documentation for information on time zones.
grid: a logical value, if TRUE date-time indices are constructed from all combinations of dates and times (FALSE by default).
x: an object of tind class of type date-time (type "t") or an R object coercible to it.

Details

If arguments of date_time are of different length, they are recycled.

When grid is set to TRUE, date-time indices are constructed from all combinations of dates and times in a way similar to how functions expand.grid and kronecker work, see Examples.

If H argument is numeric, time of day is constructed from H, M, and S arguments. In the last step date and time are combined in order to construct date-time index. If H is not numeric, M and S should not be supplied and time of day is constructed from H argument only.

When provided without H argument date_time behaves just like as.date_time i.e. returns the beginning of a day.

When an hour occurs twice in a day (due to DST/UTC offset changes), the second occurrence is selected with a warning. When hour is missing (for the same reason), NA is returned with a warning. See Examples.

Examples

Run this code

date_time(today() + (0:1), "11:25:20.75")
date_time(today() + (0:1), as.time("11:25:20.75"))
date_time(today() + (0:1), 11, 25, 20.75)
date_time(today() + (0:1), "11:25:20")
date_time(today() + (0:1), 11, 25, 20)
date_time(today() + (0:1), "11:25")
date_time(today() + (0:1), 11, 25)
date_time(today() + (0:1), "11")
date_time(today() + (0:1), 11)
date_time(today() + (0:1))
# using 'grid' argument
date_time(today() + 0:2, c(8, 12, 16))
date_time(today() + 0:2, c(8, 12, 16), grid = TRUE)

# split date-time
(nw <- now())
date_time_split(nw)

# corner cases (with warnings)
if ("Europe/Warsaw" %in% OlsonNames()) try({
    # 2020-10-25 had 25h with 02:00 repeated
    date_time("2020-10-25", 0:2, tz = "Europe/Warsaw")
})
if ("Europe/Warsaw" %in% OlsonNames()) try({
    # 2021-03-28 had 23h with 02:00 missing
    date_time("2021-03-28", 0:2, tz = "Europe/Warsaw")
})