Skip to content

Round datetime

Description

Divide the date/datetime range into buckets. Each date/datetime in the first half of the interval is mapped to the start of its bucket. Each date/datetime in the second half of the interval is mapped to the end of its bucket. Ambiguous results are localised using the DST offset of the original timestamp - for example, rounding ‘2022-11-06 01:20:00 CST’ by ‘1h’ results in ‘2022-11-06 01:00:00 CST’, whereas rounding ‘2022-11-06 01:20:00 CDT’ by ‘1h’ results in ‘2022-11-06 01:00:00 CDT’.

Usage

<Expr>$dt$round(every)

Arguments

every Either an Expr or a string indicating a column name or a duration (see Details).

Details

The every and offset argument are created with the the following string language:

  • 1ns \# 1 nanosecond
  • 1us \# 1 microsecond
  • 1ms \# 1 millisecond
  • 1s \# 1 second
  • 1m \# 1 minute
  • 1h \# 1 hour
  • 1d \# 1 day
  • 1w \# 1 calendar week
  • 1mo \# 1 calendar month
  • 1y \# 1 calendar year These strings can be combined:
    • 3d12h4m25s \# 3 days, 12 hours, 4 minutes, and 25 seconds

Value

A polars expression

Examples

library("polars")

df <- pl$select(
  datetime = pl$datetime_range(
    as.Date("2001-01-01"),
    as.Date("2001-01-02"),
    as.difftime("0:25:0")
  )
)
df$with_columns(round = pl$col("datetime")$dt$round("1h"))

#> shape: (58, 2)
#> ┌─────────────────────┬─────────────────────┐
#> │ datetime            ┆ round               │
#> │ ---                 ┆ ---                 │
#> │ datetime[μs]        ┆ datetime[μs]        │
#> ╞═════════════════════╪═════════════════════╡
#> │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
#> │ 2001-01-01 00:25:00 ┆ 2001-01-01 00:00:00 │
#> │ 2001-01-01 00:50:00 ┆ 2001-01-01 01:00:00 │
#> │ 2001-01-01 01:15:00 ┆ 2001-01-01 01:00:00 │
#> │ 2001-01-01 01:40:00 ┆ 2001-01-01 02:00:00 │
#> │ …                   ┆ …                   │
#> │ 2001-01-01 22:05:00 ┆ 2001-01-01 22:00:00 │
#> │ 2001-01-01 22:30:00 ┆ 2001-01-01 23:00:00 │
#> │ 2001-01-01 22:55:00 ┆ 2001-01-01 23:00:00 │
#> │ 2001-01-01 23:20:00 ┆ 2001-01-01 23:00:00 │
#> │ 2001-01-01 23:45:00 ┆ 2001-01-02 00:00:00 │
#> └─────────────────────┴─────────────────────┘

df <- pl$select(
  datetime = pl$datetime_range(
    as.POSIXct("2001-01-01 00:00"),
    as.POSIXct("2001-01-01 01:00"),
    as.difftime("0:10:0")
  )
)
df$with_columns(round = pl$col("datetime")$dt$round("1h"))

#> shape: (7, 2)
#> ┌─────────────────────┬─────────────────────┐
#> │ datetime            ┆ round               │
#> │ ---                 ┆ ---                 │
#> │ datetime[ms]        ┆ datetime[ms]        │
#> ╞═════════════════════╪═════════════════════╡
#> │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
#> │ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
#> │ 2001-01-01 00:20:00 ┆ 2001-01-01 00:00:00 │
#> │ 2001-01-01 00:30:00 ┆ 2001-01-01 01:00:00 │
#> │ 2001-01-01 00:40:00 ┆ 2001-01-01 01:00:00 │
#> │ 2001-01-01 00:50:00 ┆ 2001-01-01 01:00:00 │
#> │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
#> └─────────────────────┴─────────────────────┘