Skip to contents

Convert to length-1 date-time

Source: R/to_dttm.R
to_dttm_scalar.Rd

Checks whether a vector can be converted to a length-1 base::POSIXct vector. to_datetime_scalar() is a synonym of to_dttm_scalar().

Usage

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

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

allow_null

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

allow_zero_length

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

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.

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

See also

Other datetime functions: locale_datetime_formats(), resolve_tz(), specify_dttm(), stabilize_dttm(), stabilize_dttm_scalar(), to(), to_dttm()

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(), to_date_scalar(), to_dbl(), to_dbl_scalar(), to_dttm(), 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_dttm_scalar("2024-01-01T12:00:00Z")
#> [1] "2024-01-01 12:00:00 UTC"
try(to_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.