Skip to contents

Create a specified datetime stabilizer function

Source: R/specify_dttm.R
specify_dttm.Rd

specify_dttm() creates a function that will call stabilize_dttm() with the provided arguments. specify_dttm_scalar() creates a function that will call stabilize_dttm_scalar() with the provided arguments. specify_datetime() is a synonym of specify_dttm(), and specify_datetime_scalar() is a synonym of specify_dttm_scalar().

Usage

specify_dttm(
  tz = "UTC",
  treat_number_as = c("seconds", "milliseconds", "days", "error"),
  allow_null = TRUE,
  allow_na = TRUE,
  named = NULL,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

specify_dttm_scalar(
  tz = "UTC",
  treat_number_as = c("seconds", "milliseconds", "days", "error"),
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  named = NULL,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

specify_datetime(
  tz = "UTC",
  treat_number_as = c("seconds", "milliseconds", "days", "error"),
  allow_null = TRUE,
  allow_na = TRUE,
  named = NULL,
  min_size = NULL,
  max_size = NULL,
  unique = FALSE,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

specify_datetime_scalar(
  tz = "UTC",
  treat_number_as = c("seconds", "milliseconds", "days", "error"),
  allow_null = FALSE,
  allow_zero_length = FALSE,
  allow_na = TRUE,
  named = NULL,
  min_value = NULL,
  max_value = NULL,
  allowed_values = NULL,
  accepted_datetime_formats = locale_datetime_formats()
)

Arguments

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?

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.

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.

allow_zero_length

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

Value

A function of class "stbl_specified_fn" that calls stabilize_dttm() or stabilize_dttm_scalar() with the provided arguments. The generated function will also accept ... for additional arguments to pass to stabilize_dttm() or stabilize_dttm_scalar(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See also

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

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_df(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_recent <- specify_dttm(min_value = "2000-01-01T00:00:00Z")
stabilize_recent("2024-01-01T00:00:00Z")
#> [1] "2024-01-01 UTC"
try(stabilize_recent("1999-12-31T00:00:00Z"))
#> Error in eval(expr, envir) : 
#>   `"1999-12-31T00:00:00Z"` must be >= 2000-01-01 UTC.
#> ✖ "1999-12-31 UTC" is too low.