Widen/narrow datetime precision — datetime

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)
#> [1] "missing" "year"    "day"     "minute" 
  datetime_narrow(dts, "day")
#> <datetimeoffset[4]>
#> [1] <NA>       2020       2020-04-10 2020-04-10
  datetime_widen(dts, "day")
#> <datetimeoffset[4]>
#> [1] <NA>             2020-01-01       2020-04-10       2020-04-10T10:10
  datetime_cast(dts, "day")
#> <datetimeoffset[4]>
#> [1] <NA>       2020-01-01 2020-04-10 2020-04-10

  datetime_widen(datetimeoffset(2020L), "day", month = 6, day = 15)
#> <datetimeoffset[1]>
#> [1] 2020-06-15

  # vectorized "precision" is allowed
  datetime_narrow(as_datetimeoffset(Sys.time()),
                  c("year", "day", "second"))
#> <datetimeoffset[3]>
#> [1] 2025                                          
#> [2] 2025-03-24                                    
#> [3] 2025-03-24T09:52:30-07:00[America/Los_Angeles]
  datetime_widen(NA_datetimeoffset_, c("year", "day", "second"), na_set = TRUE)
#> <datetimeoffset[3]>
#> [1] 0000                0000-01-01          0000-01-01T00:00:00

  library("clock")
  ymd <- year_month_day(1918, 11, 11, 11)
  datetime_narrow(ymd, "day")
#> <year_month_day<day>[1]>
#> [1] "1918-11-11"
  datetime_narrow(ymd, "second") # already narrower than "second"
#> <year_month_day<hour>[1]>
#> [1] "1918-11-11T11"
  datetime_widen(ymd, "second")
#> <year_month_day<second>[1]>
#> [1] "1918-11-11T11:00:00"
  datetime_widen(ymd, "day") # already wider than "day"
#> <year_month_day<hour>[1]>
#> [1] "1918-11-11T11"

  if (FALSE) { # \dontrun{
    # 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")
#> <naive_time<day>[1]>
#> [1] "1918-11-11"
  datetime_narrow(nt, "second")
#> <naive_time<hour>[1]>
#> [1] "1918-11-11T11"
  datetime_widen(nt, "second")
#> <naive_time<second>[1]>
#> [1] "1918-11-11T11:00:00"
  datetime_widen(nt, "day")
#> <naive_time<hour>[1]>
#> [1] "1918-11-11T11"
  datetime_cast(nt, "day") # same as clock::time_point_floor(nt, "day")
#> <naive_time<day>[1]>
#> [1] "1918-11-11"
  datetime_cast(nt, "day", method = "cast") # same as clock::time_point_cast(nt, "day")
#> <naive_time<day>[1]>
#> [1] "1918-11-12"