Parse datetime strings

Transforms numeric and string representations of Ymd[HMS] datetimes to POSIXct format.

Y, Ym, Ymd, YmdH, YmdHM, and YmdHMS formats are understood, where:

Y

four digit year

m

month number (1-12, 01-12) or english name month (October, oct.)

d

day number of the month (0-31 or 01-31)

H

hour number (0-24 or 00-24)

M

minute number (0-59 or 00-59)

S

second number (0-61 or 00-61)

This allows for mixed inputs. For example, 20181012130900, "2018-10-12-13-09-00", and "2018 Oct. 12 13:09:00" will all be converted to the same POSIXct datetime. The incoming datetime vector does not need to have a homogeneous format either -- "20181012" and "2018-10-12 13:09" can exist in the same vector without issue. All incoming datetimes will be interpreted in the specified timezone.

If datetime is a POSIXct it will be returned unmodified, and formats not recognized will be returned as NA.

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

Arguments

datetime

Vector of character or integer datetimes in Ymd[HMS] format (or POSIXct).

timezone

Olson timezone used to interpret dates (required).

expectAll

Logical value determining if the function should fail if any elements fail to parse (default FALSE).

isJulian

Logical value determining whether datetime should be interpreted as a Julian date with day of year as a decimal number.

quiet

Logical value passed on to lubridate::parse_date_time to optionally suppress warning messages.

Value

A vector of POSIXct datetimes.

Note

If datetime is a character string containing signed offset information, e.g. "-07:00", this information is used to generate an equivalent UTC time which is then assigned to the timezone specified by the timezone argument.

Mazama Science Conventions

Within Mazama Science package, datetimes not in POSIXct format are often represented as decimal values with no separation (ex: 20181012, 20181012130900), either as numerics or strings.

Implementation

parseDatetime is essentially a wrapper around parse_date_time, handling which formats we want to account for.

See also

parse_date_time for implementation details.

Examples

library(MazamaCoreUtils)

# All y[md-hms] formats are accepted
parseDatetime(2018, timezone = "America/Los_Angeles")
#> [1] "2018-01-01 PST"
parseDatetime(201808, timezone = "America/Los_Angeles")
#> [1] "2018-08-01 PDT"
parseDatetime(20180807, timezone = "America/Los_Angeles")
#> [1] "2018-08-07 PDT"
parseDatetime(2018080718, timezone = "America/Los_Angeles")
#> [1] "2018-08-07 18:00:00 PDT"
parseDatetime(201808071812, timezone = "America/Los_Angeles")
#> [1] "2018-08-07 18:12:00 PDT"
parseDatetime(20180807181215, timezone = "America/Los_Angeles")
#> [1] "2018-08-07 18:12:15 PDT"
parseDatetime("2018-08-07 18:12:15", timezone = "America/Los_Angeles")
#> [1] "2018-08-07 18:12:15 PDT"
parseDatetime("2018-08-07 18:12:15-07:00", timezone = "America/Los_Angeles")
#> [1] "2018-08-07 18:12:15 PDT"
parseDatetime("2018-08-07 18:12:15-07:00", timezone = "UTC")
#> [1] "2018-08-08 01:12:15 UTC"

# Julian days are accepeted
parseDatetime(2018219181215, timezone = "America/Los_Angeles",
              isJulian = TRUE)
#> [1] "2018-08-07 18:12:15 PDT"

# Vector dates are accepted and daylight savings is respected
parseDatetime(
  c("2018-10-24 12:00", "2018-10-31 12:00",
    "2018-11-07 12:00", "2018-11-08 12:00"),
  timezone = "America/New_York"
)
#> [1] "2018-10-24 12:00:00 EDT" "2018-10-31 12:00:00 EDT"
#> [3] "2018-11-07 12:00:00 EST" "2018-11-08 12:00:00 EST"

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

# Return a vector with \code{NA} for dates that could not be parsed
parseDatetime(badInput, timezone = "UTC", expectAll = FALSE)
#> [1] "2018-10-13 UTC" NA               "2018-10-15 UTC" NA              
#> [5] NA              

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