Skip to contents

Convert to date-time

Source: R/to_dttm.R
to_dttm.Rd

Checks whether a vector can be converted to a base::POSIXct without losing information, returning it silently if so. Otherwise an informative error message is signaled. to_datetime() is a synonym of to_dttm().

Usage

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

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

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

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

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

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

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

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

# S3 method for class 'numeric'
to_dttm(
  x,
  ...,
  tz = "UTC",
  treat_number_as = c("seconds", "milliseconds", "days", "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::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.

Details

Character vectors must use the RFC 3339 date-time format ("YYYY-MM-DDTHH:MM:SS", optionally followed by fractional seconds and either "Z" or a numeric offset such as "+05:00"); any other shape is rejected (but see stabilize_dttm()). A space may be used instead of "T" to separate the date and time. All values are normalized to the time zone named by tz ("UTC" by default); the underlying instant in time is preserved, only its display time zone changes.

Numeric and integer values are interpreted according to treat_number_as, by default as the number of seconds since the Unix epoch ("1970-01-01 00:00:00 UTC"). Milliseconds are converted to seconds by dividing by 1000, which preserves whole milliseconds for realistic dates. Doubles can't represent whole milliseconds beyond roughly the year 287,000, so values that large have already lost precision before conversion. Note that format() truncates rather than rounds fractional seconds, so a value such as 12:00:00.1228 may display as 12:00:00.122; the stored value is not affected. With treat_number_as = "days", numbers are days since the epoch, giving midnight UTC. treat_number_as is ignored for other types of input.

base::Date values are treated as midnight UTC on that date.

See also

Other datetime functions: locale_datetime_formats(), resolve_tz(), specify_dttm(), stabilize_dttm(), stabilize_dttm_scalar(), to(), 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_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_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_dttm(as.POSIXct("2024-01-01 12:00:00", tz = "UTC"))
#> [1] "2024-01-01 12:00:00 UTC"
to_dttm("2024-01-01T12:00:00Z")
#> [1] "2024-01-01 12:00:00 UTC"
to_dttm("2024-01-01T12:00:00-05:00")
#> [1] "2024-01-01 17:00:00 UTC"
to_dttm(c("2024-01-01T12:00:00Z", NA))
#> [1] "2024-01-01 12:00:00 UTC" NA                       
to_dttm(0L)
#> [1] "1970-01-01 UTC"
to_dttm(1704110400000, treat_number_as = "milliseconds")
#> [1] "2024-01-01 12:00:00 UTC"
try(to_dttm(0, treat_number_as = "error"))
#> Error in eval(expr, envir) : 
#>   Can't convert `0` <double> to <datetime>.
to_dttm(as.Date("2024-01-01"))
#> [1] "2024-01-01 UTC"
to_dttm(NULL)
#> NULL
try(to_dttm("2024-01-01 12:00:00"))
#> Error in eval(expr, envir) : 
#>   `"2024-01-01 12:00:00"` <character> must be convertible to <datetime>
#> ✖ Can't convert some values due to invalid or ambiguous date-time format.
#> • Locations: 1
#> • Values: "2024-01-01 12:00:00"
try(to_dttm(c("2024-01-01T12:00:00Z", "not-a-datetime")))
#> Error in eval(expr, envir) : 
#>   `c("2024-01-01T12:00:00Z", "not-a-datetime")` <character> must be
#> convertible to <datetime>
#> ✖ Can't convert some values due to invalid or ambiguous date-time format.
#> • Locations: 2
#> • Values: "not-a-datetime"