% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dateRange.R
\name{dateRange}
\alias{dateRange}
\title{Create a POSIXct date range}
\usage{
dateRange(
  startdate = NULL,
  enddate = NULL,
  timezone = NULL,
  unit = "sec",
  ceilingStart = FALSE,
  ceilingEnd = FALSE,
  days = 7
)
}
\arguments{
\item{startdate}{Desired start datetime.}

\item{enddate}{Desired end datetime.}

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

\item{unit}{Temporal precision used for the returned end-of-range value.
One of \code{"day"}, \code{"hour"}, \code{"min"}, or \code{"sec"}.}

\item{ceilingStart}{Logical specifying whether to round \code{startdate} up to the
next day boundary instead of down.}

\item{ceilingEnd}{Logical specifying whether to include the entirety of the
final day.}

\item{days}{Number of days to include when either \code{startdate} or \code{enddate}
is omitted.}
}
\value{
Two-element \code{POSIXct} vector ordered from earliest to latest.
}
\description{
Create a two-element \code{POSIXct} vector representing a date/time range in a
specified timezone.
}
\details{
The returned range is ordered from earliest to latest. The first element
represents the beginning of the requested date range and the second element
represents the end of the requested date range at the requested temporal
precision.

By default, the returned end time is one \code{unit} \emph{before} the beginning of
\code{enddate}. For example:

\preformatted{
dateRange(20190101, 20190102, timezone = "UTC")
[1] "2019-01-01 00:00:00 UTC"
[2] "2019-01-01 23:59:59 UTC"
}

Setting \code{ceilingEnd = TRUE} includes the entirety of \code{enddate}:

\preformatted{
dateRange(
  20190101,
  20190101,
  timezone = "UTC",
  ceilingEnd = TRUE
)
[1] "2019-01-01 00:00:00 UTC"
[2] "2019-01-01 23:59:59 UTC"
}

The \code{ceilingEnd} argument addresses ambiguity in phrases such as
\code{"August 1-8"}. With \code{ceilingEnd = FALSE} (default), the range extends
through the end of August 7, stopping at the midnight boundary where August 8
begins. With \code{ceilingEnd = TRUE}, the range
extends through the end of August 8.

Input dates are parsed with \code{\link[=parseDatetime]{parseDatetime()}} using the specified
\code{timezone}.
}
\section{Default arguments}{

If either \code{startdate} or \code{enddate} is missing, the missing boundary is
calculated using \code{days}.

If both are missing, \code{enddate} defaults to the current day in \code{timezone}
and \code{startdate} is calculated as \code{enddate - days}.
}

\section{End-of-day units}{

The returned end time is adjusted to the last representable value within the
requested unit:

\describe{
\item{\code{unit = "day"}}{End time is midnight at the start of the final day.}
\item{\code{unit = "hour"}}{End time is \code{23:00:00}.}
\item{\code{unit = "min"}}{End time is \code{23:59:00}.}
\item{\code{unit = "sec"}}{End time is \code{23:59:59}.}
}
}

\section{POSIXct inputs}{

When \code{startdate} or \code{enddate} are already \code{POSIXct} values, they are first
converted to \code{timezone} with \code{\link[lubridate:with_tz]{lubridate::with_tz()}} without changing the
represented instant in time.
}

\section{Parameter precedence}{

When parameters conflict, the following rules apply:

\enumerate{
\item If both \code{startdate} and \code{enddate} are supplied, \code{days} is ignored.
\item If \code{startdate} is missing, \code{ceilingStart} is ignored.
\item If \code{enddate} is missing, \code{ceilingEnd} is ignored.
}
}

\examples{
dateRange("2019-01-08", timezone = "UTC")

dateRange("2019-01-08", unit = "min", timezone = "UTC")

dateRange("2019-01-08", unit = "hour", timezone = "UTC")

dateRange("2019-01-08", unit = "day", timezone = "UTC")

dateRange("2019-01-08", "2019-01-11", timezone = "UTC")

dateRange(
  enddate = 20190112,
  days = 3,
  unit = "day",
  timezone = "America/Los_Angeles"
)

}
