Convert to date

Checks whether a vector can be converted to a base::Date without losing information, returning it silently if so. Otherwise an informative error message is signaled.

Usage

to_date(
  x,
  ...,
  tz = "UTC",
  treat_number_as = c("days", "seconds", "milliseconds", "error"),
  x_arg = caller_arg(x),
  to_arg = NULL,
  call = caller_env(),
  x_class = object_type(x)
)

# S3 method for class '`NULL`'
to_date(
  x,
  ...,
  allow_null = TRUE,
  x_arg = caller_arg(x),
  to_arg = NULL,
  call = caller_env()
)

# S3 method for class 'character'
to_date(
  x,
  ...,
  x_arg = caller_arg(x),
  to_arg = NULL,
  call = caller_env(),
  x_class = object_type(x)
)

# S3 method for class 'factor'
to_date(
  x,
  ...,
  x_arg = caller_arg(x),
  to_arg = NULL,
  call = caller_env(),
  x_class = object_type(x)
)

# S3 method for class 'POSIXct'
to_date(x, ..., tz = "UTC", call = caller_env())

# S3 method for class 'POSIXlt'
to_date(x, ...)

# S3 method for class 'numeric'
to_date(
  x,
  ...,
  tz = "UTC",
  treat_number_as = c("days", "seconds", "milliseconds", "error"),
  x_arg = caller_arg(x),
  to_arg = NULL,
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

x

The object to stabilize.

...

Arguments passed to methods.

tz

(character(1)) The time zone to normalize x to. Must be a value from OlsonNames() or "", which is replaced by the name of your local time zone (as reported by Sys.timezone()) so that the result always names its time zone. To use the time zone of an existing object, or your local time zone if it doesn't have one, use tz = resolve_tz(x) (see resolve_tz()).

treat_number_as

(character(1)) How to interpret numeric input: "seconds" or "milliseconds" since the Unix epoch, "days" since the Unix epoch, or "error" to reject numbers. Ignored for non-numeric input.

x_arg

(character(1)) The name of the object being stabilized to use in error messages. The automatic value will work in most cases, or pass it through from higher-level functions to make error messages clearer in unexported functions.

to_arg

(character(1) or NULL) The name of the object that x is being converted to match, for use in error messages. When NULL, error messages describe only x. When supplied, conversion failure messages name both x_arg and to_arg.

call

(environment) The execution environment to mention as the source of error messages.

x_class

(character(1)) The class name of the object being stabilized to use in error messages. Use this if you remove a special class from the object before checking its conversion, but want the error message to match the original class.

allow_null

(logical(1)) Is NULL an acceptable value?

Value

The input as a base::Date vector, or an error condition with classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>, <condition>, and a specific class by failure mode:

• <stbl-error-incompatible_values-date> when some values cannot be safely converted to date.

• <stbl-error-bad_null> for NULL values when allow_null = FALSE.

Details

Character vectors must use the RFC 3339 full-date format ("YYYY-MM-DD"); any other shape (such as "11/13/2018") is rejected (but see stabilize_date()). POSIXct and POSIXlt values are truncated to their date component, discarding the time-of-day and timezone offset. Numeric and integer values are interpreted according to treat_number_as, by default as the number of days since the Unix epoch ("1970-01-01"). Seconds and milliseconds since the epoch are converted to the date in the time zone named by tz ("UTC" by default), rounding down. POSIXct values are likewise converted to tz before truncating. tz is ignored for other types of input, and treat_number_as is ignored for non-numeric input.

See also

Other date functions: locale_datetime_formats(), specify_date(), stabilize_date(), stabilize_date_scalar(), to(), to_date_scalar()

Other stabilization functions: assert_contains(), assert_not(), assert_present(), stabilize_all_of(), stabilize_any_of(), stabilize_arg(), stabilize_chr(), stabilize_chr_scalar(), stabilize_date(), stabilize_date_scalar(), stabilize_dbl(), stabilize_dbl_scalar(), stabilize_df(), stabilize_dttm(), stabilize_dttm_scalar(), stabilize_dur(), stabilize_dur_scalar(), stabilize_fct(), stabilize_fct_scalar(), stabilize_int(), stabilize_int_scalar(), stabilize_lgl(), stabilize_lgl_scalar(), stabilize_lst(), stabilize_one_of(), stabilize_time(), stabilize_time_scalar(), to_chr(), to_chr_scalar(), to_date_scalar(), to_dbl(), to_dbl_scalar(), to_dttm(), to_dttm_scalar(), to_dur(), to_dur_scalar(), to_fct(), to_fct_scalar(), to_int(), to_int_scalar(), to_lgl(), to_lgl_scalar(), to_time(), to_time_scalar()

Examples

to_date(as.Date("2024-01-01"))
#> [1] "2024-01-01"
to_date("2024-01-01")
#> [1] "2024-01-01"
to_date(c("2024-01-01", NA))
#> [1] "2024-01-01" NA          
to_date(0L)
#> [1] "1970-01-01"
to_date(1704110400, treat_number_as = "seconds")
#> [1] "2024-01-01"
try(to_date(0, treat_number_as = "error"))
#> Error in eval(expr, envir) : 
#>   Can't convert `0` <double> to <date>.
to_date(as.POSIXct("2024-01-01 23:00:00", tz = "UTC"))
#> [1] "2024-01-01"
to_date(NULL)
#> NULL
try(to_date("11/13/2018"))
#> Error in eval(expr, envir) : 
#>   `"11/13/2018"` <character> must be convertible to <date>
#> ✖ Can't convert some values due to invalid or ambiguous date format.
#> • Locations: 1
#> • Values: "11/13/2018"
try(to_date(c("2024-01-01", "not-a-date")))
#> Error in eval(expr, envir) : 
#>   `c("2024-01-01", "not-a-date")` <character> must be convertible to
#> <date>
#> ✖ Can't convert some values due to invalid or ambiguous date format.
#> • Locations: 2
#> • Values: "not-a-date"