Create a POSIXct date range — dateRange • MazamaCoreUtils

Create a two-element POSIXct vector representing a date/time range in a specified timezone.

dateRange(
  startdate = NULL,
  enddate = NULL,
  timezone = NULL,
  unit = "sec",
  ceilingStart = FALSE,
  ceilingEnd = FALSE,
  days = 7
)

Arguments

startdate: Desired start datetime.
enddate: Desired end datetime.
timezone: Olson timezone used to interpret incoming dates.
unit: Temporal precision used for the returned end-of-range value. One of "day", "hour", "min", or "sec".
ceilingStart: Logical specifying whether to round startdate up to the next day boundary instead of down.
ceilingEnd: Logical specifying whether to include the entirety of the final day.
days: Number of days to include when either startdate or enddate is omitted.

Value

Two-element POSIXct vector ordered from earliest to latest.

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 unit before the beginning of enddate. For example:


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

Setting ceilingEnd = TRUE includes the entirety of enddate:


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

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

Input dates are parsed with parseDatetime() using the specified timezone.

Default arguments

If either startdate or enddate is missing, the missing boundary is calculated using days.

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

End-of-day units

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

unit = "day": End time is midnight at the start of the final day.
unit = "hour": End time is 23:00:00.
unit = "min": End time is 23:59:00.
unit = "sec": End time is 23:59:59.

POSIXct inputs

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

Parameter precedence

When parameters conflict, the following rules apply:

If both startdate and enddate are supplied, days is ignored.
If startdate is missing, ceilingStart is ignored.
If enddate is missing, ceilingEnd is ignored.

Examples

dateRange("2019-01-08", timezone = "UTC")
#> [1] "2019-01-08 00:00:00 UTC" "2019-01-14 23:59:59 UTC"

dateRange("2019-01-08", unit = "min", timezone = "UTC")
#> [1] "2019-01-08 00:00:00 UTC" "2019-01-14 23:59:00 UTC"

dateRange("2019-01-08", unit = "hour", timezone = "UTC")
#> [1] "2019-01-08 00:00:00 UTC" "2019-01-14 23:00:00 UTC"

dateRange("2019-01-08", unit = "day", timezone = "UTC")
#> [1] "2019-01-08 UTC" "2019-01-15 UTC"

dateRange("2019-01-08", "2019-01-11", timezone = "UTC")
#> [1] "2019-01-08 00:00:00 UTC" "2019-01-10 23:59:59 UTC"

dateRange(
  enddate = 20190112,
  days = 3,
  unit = "day",
  timezone = "America/Los_Angeles"
)
#> [1] "2019-01-09 PST" "2019-01-12 PST"