Skip to content

Round datetime

Source code

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.

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

Date/Datetime expr

Examples

library("polars")

t1 = as.POSIXct("3040-01-01", tz = "GMT")
t2 = t1 + as.difftime(25, units = "secs")
s = pl$datetime_range(t1, t2, interval = "2s", time_unit = "ms")

df = pl$DataFrame(datetime = s)$with_columns(
  pl$col("datetime")$dt$round("4s")$alias("rounded_4s")
)
df

#> shape: (13, 2)
#> ┌─────────────────────────┬─────────────────────────┐
#> │ datetime                ┆ rounded_4s              │
#> │ ---                     ┆ ---                     │
#> │ datetime[ms, GMT]       ┆ datetime[ms, GMT]       │
#> ╞═════════════════════════╪═════════════════════════╡
#> │ 3040-01-01 00:00:00 GMT ┆ 3040-01-01 00:00:00 GMT │
#> │ 3040-01-01 00:00:02 GMT ┆ 3040-01-01 00:00:04 GMT │
#> │ 3040-01-01 00:00:04 GMT ┆ 3040-01-01 00:00:04 GMT │
#> │ 3040-01-01 00:00:06 GMT ┆ 3040-01-01 00:00:08 GMT │
#> │ 3040-01-01 00:00:08 GMT ┆ 3040-01-01 00:00:08 GMT │
#> │ …                       ┆ …                       │
#> │ 3040-01-01 00:00:16 GMT ┆ 3040-01-01 00:00:16 GMT │
#> │ 3040-01-01 00:00:18 GMT ┆ 3040-01-01 00:00:20 GMT │
#> │ 3040-01-01 00:00:20 GMT ┆ 3040-01-01 00:00:20 GMT │
#> │ 3040-01-01 00:00:22 GMT ┆ 3040-01-01 00:00:24 GMT │
#> │ 3040-01-01 00:00:24 GMT ┆ 3040-01-01 00:00:24 GMT │
#> └─────────────────────────┴─────────────────────────┘