Skip to content

Replace time zone for an expression of type Datetime

Description

Different from $dt$convert_time_zone(), this will also modify the underlying timestamp and will ignore the original time zone.

Usage

<Expr>$dt$replace_time_zone(
  time_zone,
  ...,
  ambiguous = c("raise", "earliest", "latest", "null"),
  non_existent = c("raise", "null")
)

Arguments

time_zone NULL or a character time zone from base::OlsonNames(). Pass NULL to unset time zone.
… These dots are for future extensions and must be empty.
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
non_existent Determine how to deal with non-existent datetimes. One of the followings:
  • “raise” (default): Throw an error
  • “null”: Return a null value

Value

A polars expression

Examples

library("polars")

df <- pl$select(
  london_timezone = pl$datetime_range(
    as.Date("2020-03-01"),
    as.Date("2020-07-01"),
    "1mo",
    time_zone = "UTC"
  )$dt$convert_time_zone(time_zone = "Europe/London")
)
df$with_columns(
  London_to_Amsterdam = pl$col("london_timezone")$dt$replace_time_zone(
    time_zone="Europe/Amsterdam"
  )
)

#> shape: (5, 2)
#> ┌─────────────────────────────┬────────────────────────────────┐
#> │ london_timezone             ┆ London_to_Amsterdam            │
#> │ ---                         ┆ ---                            │
#> │ datetime[μs, Europe/London] ┆ datetime[μs, Europe/Amsterdam] │
#> ╞═════════════════════════════╪════════════════════════════════╡
#> │ 2020-03-01 00:00:00 GMT     ┆ 2020-03-01 00:00:00 CET        │
#> │ 2020-04-01 01:00:00 BST     ┆ 2020-04-01 01:00:00 CEST       │
#> │ 2020-05-01 01:00:00 BST     ┆ 2020-05-01 01:00:00 CEST       │
#> │ 2020-06-01 01:00:00 BST     ┆ 2020-06-01 01:00:00 CEST       │
#> │ 2020-07-01 01:00:00 BST     ┆ 2020-07-01 01:00:00 CEST       │
#> └─────────────────────────────┴────────────────────────────────┘

# You can use `ambiguous` to deal with ambiguous datetimes:
dates <- c(
  "2018-10-28 01:30",
  "2018-10-28 02:00",
  "2018-10-28 02:30",
  "2018-10-28 02:00"
) |>
  as.POSIXct("UTC")

df2 <- pl$DataFrame(
  ts = as_polars_series(dates),
  ambiguous = c("earliest", "earliest", "latest", "latest"),
)

df2$with_columns(
  ts_localized = pl$col("ts")$dt$replace_time_zone(
    "Europe/Brussels",
    ambiguous = pl$col("ambiguous")
  )
)

#> shape: (4, 3)
#> ┌─────────────────────────┬───────────┬───────────────────────────────┐
#> │ ts                      ┆ ambiguous ┆ ts_localized                  │
#> │ ---                     ┆ ---       ┆ ---                           │
#> │ datetime[ms, UTC]       ┆ str       ┆ datetime[ms, Europe/Brussels] │
#> ╞═════════════════════════╪═══════════╪═══════════════════════════════╡
#> │ 2018-10-28 01:30:00 UTC ┆ earliest  ┆ 2018-10-28 01:30:00 CEST      │
#> │ 2018-10-28 02:00:00 UTC ┆ earliest  ┆ 2018-10-28 02:00:00 CEST      │
#> │ 2018-10-28 02:30:00 UTC ┆ latest    ┆ 2018-10-28 02:30:00 CET       │
#> │ 2018-10-28 02:00:00 UTC ┆ latest    ┆ 2018-10-28 02:00:00 CET       │
#> └─────────────────────────┴───────────┴───────────────────────────────┘