Skip to contents

Convert to length-1 date-time with additional checks

Source: R/stabilize_dttm.R
stabilize_dttm_scalar.Rd

Checks whether a vector can be converted to a length-1 base::POSIXct vector. stabilize_dttm_scalar() is optimized to check for length-1 date-time vectors (compared to stabilize_dttm() with max_size = 1). stabilise_dttm_scalar are synonyms of stabilize_dttm_scalar().

Usage

stabilize_dttm_scalar(
  x,
  ...,
  tz = "UTC",
  treat_number_as = c("seconds", "milliseconds", "days", "error"),
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  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_dttm_scalar(
  x,
  ...,
  tz = "UTC",
  treat_number_as = c("seconds", "milliseconds", "days", "error"),
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  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)
)

stabilize_datetime_scalar(
  x,
  ...,
  tz = "UTC",
  treat_number_as = c("seconds", "milliseconds", "days", "error"),
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  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_datetime_scalar(
  x,
  ...,
  tz = "UTC",
  treat_number_as = c("seconds", "milliseconds", "days", "error"),
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  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_zero_length

(logical(1)) Are zero-length vectors acceptable?

allow_na

(logical(1)) Are NA values ok?

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 length-1 base::POSIXct 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-datetime> when x cannot be converted to datetime.

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

  • <stbl-error-bad_tz> when tz is not "" or a value from OlsonNames(), or is "" and your local time zone can't be determined.

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

  • <stbl-error-bad_empty> for empty vectors when allow_zero_length = FALSE.

  • <stbl-error-non_scalar> for non-scalar vectors.

  • <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-outside_range> when values fall outside min_value or max_value.

  • <stbl-error-allowed_values> when the value is not in allowed_values.

See also

Other datetime functions: locale_datetime_formats(), resolve_tz(), specify_dttm(), stabilize_dttm(), to(), to_dttm(), to_dttm_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_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(), 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

stabilize_dttm_scalar(as.POSIXct("2024-01-01 12:00:00", tz = "UTC"))
#> [1] "2024-01-01 12:00:00 UTC"
stabilize_dttm_scalar("2024-01-01T12:00:00Z")
#> [1] "2024-01-01 12:00:00 UTC"
try(stabilize_dttm_scalar(c(
  "2024-01-01T12:00:00Z",
  "2024-01-02T12:00:00Z"
)))
#> Error in eval(expr, envir) : 
#>   `c("2024-01-01T12:00:00Z", "2024-01-02T12:00:00Z")` must be a single
#> <POSIXct/POSIXt>.
#> ✖ `c("2024-01-01T12:00:00Z", "2024-01-02T12:00:00Z")` has 2 values.
try(stabilize_dttm_scalar(NULL))
#> Error in eval(expr, envir) : `NULL` must not be <NULL>.
stabilize_dttm_scalar(NULL, allow_null = TRUE)
#> NULL