MazamaCoreUtils (version 0.6.2)

parseDatetime: Parse datetimes

Description

Convert character, numeric, integer, or POSIXct datetimes to POSIXct.

Usage

parseDatetime(
  datetime = NULL,
  timezone = NULL,
  expectAll = FALSE,
  isJulian = FALSE,
  quiet = TRUE
)

Value

A POSIXct vector.

Arguments

datetime

Vector of character, numeric, integer, or POSIXct datetimes.

timezone

Olson timezone used to interpret incoming datetimes.

expectAll

Logical value specifying whether to stop if any non-missing input values fail to parse.

isJulian

Logical value specifying whether datetime should be interpreted as a Julian date using day-of-year notation.

quiet

Logical value passed to lubridate::parse_date_time() to suppress parsing warnings.

Mazama Science conventions

Within Mazama Science packages, datetimes not already in POSIXct format are often represented as compact decimal values with no separators, such as 20181012 or 20181012130900, either as numbers or strings.

Implementation

parseDatetime() is a wrapper around lubridate::parse_date_time() that defines the datetime formats supported by MazamaCoreUtils.

Details

This function accepts a variety of compact date/time formats commonly used in Mazama Science packages, including Y, Ym, Ymd, YmdH, YmdHM, and YmdHMS. Inputs may be mixed within the same vector.

Examples of equivalent inputs include:

20181012130900
"2018-10-12-13-09-00"
"2018 Oct. 12 13:09:00"

All incoming datetimes are interpreted in the specified timezone. If datetime is already POSIXct, it is converted to the requested timezone with lubridate::with_tz().

If a character datetime includes signed offset information, such as "-07:00", that offset is used by lubridate::parse_date_time() when determining the equivalent instant.

See Also

lubridate::parse_date_time()

Examples

# All Y[mdHMS] formats are accepted
parseDatetime(2018, timezone = "America/Los_Angeles")
parseDatetime(201808, timezone = "America/Los_Angeles")
parseDatetime(20180807, timezone = "America/Los_Angeles")
parseDatetime(2018080718, timezone = "America/Los_Angeles")
parseDatetime(201808071812, timezone = "America/Los_Angeles")
parseDatetime(20180807181215, timezone = "America/Los_Angeles")

parseDatetime("2018-08-07 18:12:15", timezone = "America/Los_Angeles")
parseDatetime("2018-08-07 18:12:15-07:00", timezone = "UTC")

# Julian days are accepted
parseDatetime(
  2018219181215,
  timezone = "America/Los_Angeles",
  isJulian = TRUE
)

# Mixed vector inputs are accepted
parseDatetime(
  c("2018-10-24 12:00", "201810311200", "2018-11-07 12:00"),
  timezone = "America/New_York"
)

badInput <- c("20181013", NA, "20181015", "181016", "10172018")

# Return NA for dates that cannot be parsed
parseDatetime(badInput, timezone = "UTC", expectAll = FALSE)

if (FALSE) {
# Fail if any non-missing dates cannot be parsed
parseDatetime(badInput, timezone = "UTC", expectAll = TRUE)
}