% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/parseDatetime.R
\name{parseDatetime}
\alias{parseDatetime}
\title{Parse datetimes}
\usage{
parseDatetime(
  datetime = NULL,
  timezone = NULL,
  expectAll = FALSE,
  isJulian = FALSE,
  quiet = TRUE
)
}
\arguments{
\item{datetime}{Vector of character, numeric, integer, or \code{POSIXct}
datetimes.}

\item{timezone}{Olson timezone used to interpret incoming datetimes.}

\item{expectAll}{Logical value specifying whether to stop if any non-missing
input values fail to parse.}

\item{isJulian}{Logical value specifying whether \code{datetime} should be
interpreted as a Julian date using day-of-year notation.}

\item{quiet}{Logical value passed to \code{\link[lubridate:parse_date_time]{lubridate::parse_date_time()}} to
suppress parsing warnings.}
}
\value{
A \code{POSIXct} vector.
}
\description{
Convert character, numeric, integer, or \code{POSIXct} datetimes to \code{POSIXct}.
}
\details{
This function accepts a variety of compact date/time formats commonly used in
Mazama Science packages, including \code{Y}, \code{Ym}, \code{Ymd}, \code{YmdH}, \code{YmdHM}, and
\code{YmdHMS}. Inputs may be mixed within the same vector.

Examples of equivalent inputs include:

\preformatted{
20181012130900
"2018-10-12-13-09-00"
"2018 Oct. 12 13:09:00"
}

All incoming datetimes are interpreted in the specified \code{timezone}. If
\code{datetime} is already \code{POSIXct}, it is converted to the requested timezone
with \code{\link[lubridate:with_tz]{lubridate::with_tz()}}.

If a character datetime includes signed offset information, such as
\code{"-07:00"}, that offset is used by \code{\link[lubridate:parse_date_time]{lubridate::parse_date_time()}} when
determining the equivalent instant.
}
\section{Mazama Science conventions}{

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

\section{Implementation}{

\code{parseDatetime()} is a wrapper around \code{\link[lubridate:parse_date_time]{lubridate::parse_date_time()}} that
defines the datetime formats supported by MazamaCoreUtils.
}

\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)

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

}
\seealso{
\code{\link[lubridate:parse_date_time]{lubridate::parse_date_time()}}
}
