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

\item{enddate}{Desired end datetime.}

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

\item{ceilingEnd}{Logical specifying whether to include the end of the final
day.}
}
\value{
A vector of \code{POSIXct} datetimes at local midnight.
}
\description{
Create a sequence of local-midnight \code{POSIXct} datetimes in a specified
timezone.
}
\details{
The returned sequence begins at midnight local time on \code{startdate} and ends
at midnight local time on \code{enddate}, \emph{i.e.} the \emph{beginning} of \code{enddate}.

The \code{ceilingEnd} argument addresses ambiguity in date ranges such as
\code{"August 1-8"}. With \code{ceilingEnd = FALSE} (default), the sequence ends at
the beginning of August 8. With \code{ceilingEnd = TRUE}, the sequence
includes the entirety of August 8, ending at the midnight that begins August 9.

Input dates are parsed with \code{\link[=parseDatetime]{parseDatetime()}} using the specified
\code{timezone}. Any hour-minute-second information is removed after parsing.
}
\note{
This function preserves local clock-time midnight boundaries across daylight
savings transitions. This differs from \code{seq.Date(..., by = "day")}, which
advances by fixed 24-hour intervals and can drift away from midnight local
time during daylight savings changes.
}
\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. They are then floored to local midnight.
}

\examples{
dateSequence(
  "2019-11-01",
  "2019-11-08",
  timezone = "America/Los_Angeles"
)

dateSequence(
  "2019-11-01",
  "2019-11-07",
  timezone = "America/Los_Angeles",
  ceilingEnd = TRUE
)

# Observe daylight savings handling
datetime <- dateSequence(
  "2019-11-01",
  "2019-11-08",
  timezone = "America/Los_Angeles"
)

datetime
lubridate::with_tz(datetime, "UTC")

# POSIXct inputs preserve the represented instant before flooring
jst <- dateSequence(
  20190307,
  20190315,
  timezone = "Asia/Tokyo"
)

jst

dateSequence(
  jst[1],
  jst[7],
  timezone = "UTC"
)

}
