Skip to content

Convert a String column into a Datetime column

Description

Convert a String column into a Datetime column

Usage

<Expr>$str$to_datetime(
  format = NULL,
  ...,
  time_unit = NULL,
  time_zone = NULL,
  strict = TRUE,
  exact = TRUE,
  cache = TRUE,
  ambiguous = c("raise", "earliest", "latest", "null")
)

Arguments

format Format to use for conversion. Refer to the chrono crate documentation for the full specification. Example: “%Y-%m-%d %H:%M:%S”. If NULL (default), the format is inferred from the data. Notice that time zone %Z is not supported and will just ignore timezones. Numeric time zones like %z or %:z are supported.
… These dots are for future extensions and must be empty.
time_unit Unit of time for the resulting Datetime column. If NULL (default), the time unit is inferred from the format string if given, e.g.: “%F %T%.3f” =\> pl$Datetime("ms"). If no fractional second component is found, the default is “us” (microsecond).
time_zone for the resulting Datetime column.
strict If TRUE (default), raise an error if a single string cannot be parsed. If FALSE, produce a polars null.
exact If TRUE (default), require an exact format match. If FALSE, allow the format to match anywhere in the target string. Note that using exact = FALSE introduces a performance penalty - cleaning your data beforehand will almost certainly be more performant.
cache Use a cache of unique, converted dates to apply the datetime conversion.
ambiguous Determine how to deal with ambiguous datetimes. Character vector or expression containing the followings:
  • “raise” (default): Throw an error
  • “earliest”: Use the earliest datetime
  • “latest”: Use the latest datetime
  • “null”: Return a null value

Value

A polars expression

See Also

  • \$str$strptime()

Examples

library("polars")

df <- pl$DataFrame(x = c("2020-01-01 01:00Z", "2020-01-01 02:00Z"))

df$select(pl$col("x")$str$to_datetime("%Y-%m-%d %H:%M%#z"))

#> shape: (2, 1)
#> ┌─────────────────────────┐
#> │ x                       │
#> │ ---                     │
#> │ datetime[μs, UTC]       │
#> ╞═════════════════════════╡
#> │ 2020-01-01 01:00:00 UTC │
#> │ 2020-01-01 02:00:00 UTC │
#> └─────────────────────────┘

df$select(pl$col("x")$str$to_datetime(time_unit = "ms"))

#> shape: (2, 1)
#> ┌─────────────────────────┐
#> │ x                       │
#> │ ---                     │
#> │ datetime[ms, UTC]       │
#> ╞═════════════════════════╡
#> │ 2020-01-01 01:00:00 UTC │
#> │ 2020-01-01 02:00:00 UTC │
#> └─────────────────────────┘