datetimeoffset (version 1.0.0)

datetime_cast: Widen/narrow datetime precision

Description

datetime_widen() sets a floor on the minimum "precision" in the datetime vector by setting any missing elements to their minimum possible value. datetime_narrow() sets a cap on the maximum "precision" by setting any more precise elements missing. datetime_cast() sets the precision exactly by calling both datetime_narrow() and datetime_widen().

Usage

datetime_narrow(x, precision, ...)
# S3 method for datetimeoffset
datetime_narrow(x, precision, ...)
# S3 method for clock_calendar
datetime_narrow(x, precision, ...)
# S3 method for clock_time_point
datetime_narrow(
  x,
  precision,
  ...,
  method = c("floor", "round", "ceiling", "cast")
)
# S3 method for POSIXt
datetime_narrow(
  x,
  precision,
  ...,
  method = c("floor", "round", "ceiling"),
  nonexistent = "error",
  ambiguous = x
)
datetime_widen(x, precision, ...)
# S3 method for datetimeoffset
datetime_widen(
  x,
  precision,
  ...,
  year = 0L,
  month = 1L,
  day = 1L,
  hour = 0L,
  minute = 0L,
  second = 0L,
  nanosecond = 0L,
  na_set = FALSE
)
# S3 method for clock_calendar
datetime_widen(x, precision, ...)
# S3 method for clock_time_point
datetime_widen(x, precision, ...)
# S3 method for POSIXt
datetime_widen(x, precision, ...)
datetime_cast(x, precision, ...)
# S3 method for default
datetime_cast(x, precision, ...)

Value

A datetime vector.

Arguments

x

A datetime vector. Either datetimeoffset(), a "clock" "calendar", or a "clock" "time point".

precision

Precision to narrow/widen to. Either "missing", "year", "month", "day", "hour", "minute", "second", or "nanosecond".

...

Used by some methods. The default method for datetime_cast() will pass this to both datetime_narrow() and datetime_widen().

method

Depending on the class either "floor", "ceiling", "round", and/or "cast".

nonexistent

What to do when the "clock time" in the new time zone doesn't exist. See clock::as_zoned_time.clock_naive_time().

ambiguous

What to do when the "clock time" in the new time zone is ambiguous. See clock::as_zoned_time.clock_naive_time().

year

If missing what year to assume

month

If missing what month to assume

day

If missing what day to assume

hour

If missing what hour to assume

minute

If missing what minute to assume

second

If missing what second to assume

nanosecond

If missing what nanosecond to assume

na_set

If TRUE widen the "missing" datetimes as well.

Examples

  dts <- as_datetimeoffset(c(NA_character_, "2020", "2020-04-10", "2020-04-10T10:10"))
  datetime_precision(dts)
  datetime_narrow(dts, "day")
  datetime_widen(dts, "day")
  datetime_cast(dts, "day")

  datetime_widen(datetimeoffset(2020L), "day", month = 6, day = 15)

  # vectorized "precision" is allowed
  datetime_narrow(as_datetimeoffset(Sys.time()),
                  c("year", "day", "second"))
  datetime_widen(NA_datetimeoffset_, c("year", "day", "second"), na_set = TRUE)

  library("clock")
  ymd <- year_month_day(1918, 11, 11, 11)
  datetime_narrow(ymd, "day")
  datetime_narrow(ymd, "second") # already narrower than "second"
  datetime_widen(ymd, "second")
  datetime_widen(ymd, "day") # already wider than "day"

  if (FALSE) {
    # comparable {clock} calendar methods throw an error in certain cases
    clock::calendar_narrow(ymd, "second") # already narrower than "second"
    clock::calendar_widen(ymd, "day") # already wider than "day"
  }

  nt <- as_naive_time(ymd)
  datetime_narrow(nt, "day")
  datetime_narrow(nt, "second")
  datetime_widen(nt, "second")
  datetime_widen(nt, "day")
  datetime_cast(nt, "day") # same as clock::time_point_floor(nt, "day")
  datetime_cast(nt, "day", method = "cast") # same as clock::time_point_cast(nt, "day")