datetime_cast {datetimeoffset}

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

Value

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