datetime_cast function

Widen/narrow datetime precision

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().

datetime_narrow(x, precision, ...)

## S3 method for class 'datetimeoffset'
datetime_narrow(x, precision, ...)

## S3 method for class 'clock_calendar'
datetime_narrow(x, precision, ...)

## S3 method for class 'clock_time_point'
datetime_narrow(
  x,
  precision,
  ...,
  method = c("floor", "round", "ceiling", "cast")
)

## S3 method for class 'POSIXt'
datetime_narrow(
  x,
  precision,
  ...,
  method = c("floor", "round", "ceiling"),
  nonexistent = "error",
  ambiguous = x
)

datetime_widen(x, precision, ...)

## S3 method for class '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 class 'clock_calendar'
datetime_widen(x, precision, ...)

## S3 method for class 'clock_time_point'
datetime_widen(x, precision, ...)

## S3 method for class 'POSIXt'
datetime_widen(x, precision, ...)

datetime_cast(x, precision, ...)

## Default S3 method:
datetime_cast(x, precision, ...)

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.

Returns

A datetime vector.

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"

  ## Not run:

    # 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"
## End(Not run)

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