Skip to contents

Convert date or time collected values to ISO 8601

Source: R/dtc_create_iso8601.R
create_iso8601.Rd

create_iso8601() converts vectors of dates, times or date-times to ISO 8601 format. Learn more in vignette("iso_8601").

Usage

create_iso8601(
  ...,
  .format,
  .fmt_c = fmt_cmp(),
  .na = NULL,
  .cutoff_2000 = 68L,
  .check_format = FALSE,
  .warn = TRUE
)

Arguments

...

Character vectors of dates, times or date-times' components.

.format

Parsing format(s). Either a character vector or a list of character vectors. If a character vector is passed then each element is taken as parsing format for each vector passed in .... If a list is provided, then each element must be a character vector of formats. The first vector of formats is used for parsing the first vector passed in ..., and so on.

.fmt_c

A list of regexps to use when parsing .format. Use fmt_cmp() to create such an object to pass as argument to this parameter.

.na

A character vector of string literals to be regarded as missing values during parsing.

.cutoff_2000

An integer value. Two-digit years smaller or equal to .cutoff_2000 are parsed as though starting with 20, otherwise parsed as though starting with 19.

.check_format

Whether to check the formats passed in .format, meaning to check against a selection of validated formats in dtc_formats; or to have a more permissible interpretation of the formats.

.warn

Whether to warn about parsing failures.

Value

A vector of dates, times or date-times in ISO 8601 format

Examples

# Converting dates
create_iso8601(c("2020-01-01", "20200102"), .format = "y-m-d")
#> [1] "2020-01-01" NA          
create_iso8601(c("2020-01-01", "20200102"), .format = "ymd")
#> [1] NA           "2020-01-02"
create_iso8601(c("2020-01-01", "20200102"), .format = list(c("y-m-d", "ymd")))
#> [1] "2020-01-01" "2020-01-02"

# Two-digit years are supported
create_iso8601(c("20-01-01", "200101"), .format = list(c("y-m-d", "ymd")))
#> [1] "2020-01-01" "2020-01-01"

# `.cutoff_2000` sets the cutoff for two-digit to four-digit year conversion
# Default is at 68.
create_iso8601(c("67-01-01", "68-01-01", "69-01-01"), .format = "y-m-d")
#> [1] "2067-01-01" "2068-01-01" "1969-01-01"

# Change it to 80.
create_iso8601(c("79-01-01", "80-01-01", "81-01-01"), .format = "y-m-d", .cutoff_2000 = 80)
#> [1] "2079-01-01" "2080-01-01" "1981-01-01"

# Converting times
create_iso8601("15:10", .format = "HH:MM")
#> [1] "-----T15:10"
create_iso8601("2:10", .format = "HH:MM")
#> [1] "-----T02:10"
create_iso8601("2:1", .format = "HH:MM")
#> [1] "-----T02:01"
create_iso8601("02:01:56", .format = "HH:MM:SS")
#> [1] "-----T02:01:56"
create_iso8601("020156.5", .format = "HHMMSS")
#> [1] "-----T02:01:56.5"

# Converting date-times
create_iso8601("12 NOV 202015:15", .format = "dd mmm yyyyHH:MM")
#> [1] "2020-11-12T15:15"

# Indicate allowed missing values to make the parsing pass
create_iso8601("U DEC 201914:00", .format = "dd mmm yyyyHH:MM")
#> [1] NA
create_iso8601("U DEC 201914:00", .format = "dd mmm yyyyHH:MM", .na = "U")
#> [1] "2019-12--T14:00"

create_iso8601("NOV 2020", .format = "m y")
#> [1] "2020-11"
create_iso8601(c("MAR 2019", "MaR 2020", "mar 2021"), .format = "m y")
#> [1] "2019-03" "2020-03" "2021-03"

create_iso8601("2019-04-041045-", .format = "yyyy-mm-ddHHMM-")
#> [1] "2019-04-04T10:45"

create_iso8601("20200507null", .format = "ymd(HH:MM:SS)")
#> [1] NA
create_iso8601("20200507null", .format = "ymd((HH:MM:SS)|null)")
#> [1] "2020-05-07"

# Fractional seconds
create_iso8601("2019-120602:20:13.1230001", .format = "y-mdH:M:S")
#> [1] "2019-12-06T02:20:13.1230001"

# Use different reserved characters in the format specification
# Here we change "H" to "x" and "M" to "w", for hour and minute, respectively.
create_iso8601("14H00M", .format = "HHMM")
#> [1] NA
create_iso8601("14H00M", .format = "xHwM", .fmt_c = fmt_cmp(hour = "x", min = "w"))
#> [1] "-----T14:00"

# Alternative formats with unknown values
datetimes <- c("UN UNK 201914:00", "UN JAN 2021")
format <- list(c("dd mmm yyyy", "dd mmm yyyyHH:MM"))
create_iso8601(datetimes, .format = format, .na = c("UN", "UNK"))
#> [1] "2019----T14:00" "2021-01"       

# Dates and times may come in many format variations
fmt <- "dd MMM yyyy HH nn ss"
fmt_cmp <- fmt_cmp(mon = "MMM", min = "nn", sec = "ss")
create_iso8601("05 feb 1985 12 55 02", .format = fmt, .fmt_c = fmt_cmp)
#> [1] "1985-02-05T12:55:02"