Convert to date with additional checks

Compared to to_date(), stabilize_date() checks more details, but is slower. stabilise_date() is a synonym of stabilize_date().

Usage

stabilize_date(
  x,
  ...,
  tz = "UTC",
  treat_number_as = c("days", "seconds", "milliseconds", "error"),
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats(),
  named = NULL,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

stabilise_date(
  x,
  ...,
  tz = "UTC",
  treat_number_as = c("days", "seconds", "milliseconds", "error"),
  allow_null = TRUE,
  allow_na = TRUE,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats(),
  named = NULL,
  x_arg = caller_arg(x),
  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.
allow_null: (logical(1)) Is NULL an acceptable value?
allow_na: (logical(1)) Are NA values ok?
min_size: (integer(1)) The minimum size of the object. Object size will be tested using vctrs::vec_size().
max_size: (integer(1)) The maximum size of the object. Object size will be tested using vctrs::vec_size().
unique: (logical(1)) Should all elements in x be distinct?
min_value: (numeric(1)) The lowest allowed value for x. If NULL (default) values are not checked.
max_value: (numeric(1)) The highest allowed value for x. If NULL (default) values are not checked.
allowed_values: A vector of permitted values (converted to the target type). NULL (default) skips the check. NA values in x are permitted independently of allowed_values, subject to allow_na.
accepted_datetime_formats: (character) strptime()-style format strings to try, in order, when parsing a character x. The first format that parses every non-NA element of x is used; if none do, the result (and any error) is based on the first format tried. Defaults to locale_datetime_formats(), which starts with the unambiguous RFC 3339 shape ("%Y-%m-%d", optionally with a time-of-day component) before falling back to the current locale's conventional date order.
named: Controls the names of x. NULL (default), NA, or character(0) skip the check. TRUE requires every element to have a non-empty name; FALSE requires that no elements are named. A character vector (or factor) requires x to be named, with every name in the vector. A single stabilizer or conversion function (such as stabilize_chr(), a to_* function, or the result of specify_chr()) requires x to be named and is applied to names(x), so every name must satisfy it.
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.
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.

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-coerce-date> when x cannot be converted to date.
<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.
<stbl-error-bad_na> for NA values when allow_na = FALSE.
<stbl-error-bad_named> when the presence of names doesn't match named.
<stbl-error-allowed_names> when names are not in named.
<stbl-error-size_too_small> when the vector is shorter than min_size.
<stbl-error-size_too_large> when the vector is longer than max_size.
<stbl-error-duplicate_elements> when unique = TRUE and duplicates are present.
<stbl-error-outside_range> when values fall outside min_value or max_value.
<stbl-error-allowed_values> when values are not in allowed_values.

Examples

stabilize_date(as.Date("2024-01-01"))
#> [1] "2024-01-01"
stabilize_date("2024-01-01")
#> [1] "2024-01-01"
stabilize_date(NULL)
#> NULL
try(stabilize_date(NULL, allow_null = FALSE))
#> Error in eval(expr, envir) : `NULL` must not be <NULL>.
try(stabilize_date(c(as.Date("2024-01-01"), NA), allow_na = FALSE))
#> Error in eval(expr, envir) : 
#>   `c(as.Date("2024-01-01"), NA)` must not contain NA values.
#> • NA locations: 2
stabilize_date(
  "11/13/2018",
   accepted_datetime_formats = locale_datetime_formats("en_US.UTF-8")
)
#> [1] "2018-11-13"
try(stabilize_date("2024-01-01", min_value = "2024-06-01"))
#> Error in eval(expr, envir) : `"2024-01-01"` must be >= 2024-06-01.
#> ✖ "2024-01-01" is too low.
try(stabilize_date("2024-12-01", max_value = "2024-06-01"))
#> Error in eval(expr, envir) : `"2024-12-01"` must be <= 2024-06-01.
#> ✖ "2024-12-01" is too high.
try(stabilize_date(
  c("2024-01-01", "2024-01-02"),
  allowed_values = "2024-01-01"
))
#> Error in eval(expr, envir) : 
#>   `c("2024-01-01", "2024-01-02")` must be one of the allowed values.
#> ℹ Allowed value: "2024-01-01".
#> ✖ Unexpected location: 2
#> ✖ Unexpected value: "2024-01-02".

Usage

Arguments

Value

See also

Examples