Skip to content

Generate a list containing a datetime range

Source code

Description

Generate a list containing a datetime range

Usage

pl$datetime_ranges(
  start,
  end,
  interval = "1d",
  ...,
  closed = "both",
  time_unit = NULL,
  time_zone = NULL
)

Arguments

start Lower bound of the date range. Something that can be coerced to a Date or a Datetime expression. See examples for details.
end Upper bound of the date range. Something that can be coerced to a Date or a Datetime expression. See examples for details.
interval Interval of the range periods, specified as a difftime object or using the Polars duration string language. See the Polars duration string language section for details.
… Ignored.
closed Define which sides of the range are closed (inclusive). One of the followings: “both” (default), “left”, “right”, “none”.
time_unit Time unit of the resulting the Datetime data type. One of “ns”, “us”, “ms” or NULL
time_zone Time zone of the resulting Datetime data type.

Value

An Expr of data type list(Datetime)

Polars duration string language

Polars duration string language is a simple representation of durations. It is used in many Polars functions that accept durations.

It has the following format:

  • 1ns (1 nanosecond)
  • 1us (1 microsecond)
  • 1ms (1 millisecond)
  • 1s (1 second)
  • 1m (1 minute)
  • 1h (1 hour)
  • 1d (1 calendar day)
  • 1w (1 calendar week)
  • 1mo (1 calendar month)
  • 1q (1 calendar quarter)
  • 1y (1 calendar year)

Or combine them: “3d12h4m25s” # 3 days, 12 hours, 4 minutes, and 25 seconds

By "calendar day", we mean the corresponding time on the next day (which may not be 24 hours, due to daylight savings). Similarly for "calendar week", "calendar month", "calendar quarter", and "calendar year".

See Also

pl$datetime_range() to create a simple Series of data type Datetime.

Examples

library("polars")

df = pl$DataFrame(
  start = as.POSIXct(c("2022-01-01 10:00", "2022-01-01 11:00", NA)),
  end = as.POSIXct("2022-01-01 12:00")
)

df$with_columns(
  dt_range = pl$datetime_ranges("start", "end", interval = "1h"),
  dt_range_cr = pl$datetime_ranges("start", "end", closed = "right", interval = "1h")
)

#> shape: (3, 4)
#> ┌─────────────────────┬─────────────────────┬───────────────────────┬───────────────────────┐
#> │ start               ┆ end                 ┆ dt_range              ┆ dt_range_cr           │
#> │ ---                 ┆ ---                 ┆ ---                   ┆ ---                   │
#> │ datetime[ms]        ┆ datetime[ms]        ┆ list[datetime[ms]]    ┆ list[datetime[ms]]    │
#> ╞═════════════════════╪═════════════════════╪═══════════════════════╪═══════════════════════╡
#> │ 2022-01-01 10:00:00 ┆ 2022-01-01 12:00:00 ┆ [2022-01-01 10:00:00, ┆ [2022-01-01 11:00:00, │
#> │                     ┆                     ┆ 2022-01-…             ┆ 2022-01-…             │
#> │ 2022-01-01 11:00:00 ┆ 2022-01-01 12:00:00 ┆ [2022-01-01 11:00:00, ┆ [2022-01-01 12:00:00] │
#> │                     ┆                     ┆ 2022-01-…             ┆                       │
#> │ null                ┆ 2022-01-01 12:00:00 ┆ null                  ┆ null                  │
#> └─────────────────────┴─────────────────────┴───────────────────────┴───────────────────────┘

# provide a custom "end" value
df$with_columns(
  dt_range_lit = pl$datetime_ranges(
    "start", pl$lit(as.POSIXct("2022-01-01 11:00")),
    interval = "1h"
  )
)

#> shape: (3, 3)
#> ┌─────────────────────┬─────────────────────┬─────────────────────────────────┐
#> │ start               ┆ end                 ┆ dt_range_lit                    │
#> │ ---                 ┆ ---                 ┆ ---                             │
#> │ datetime[ms]        ┆ datetime[ms]        ┆ list[datetime[ms]]              │
#> ╞═════════════════════╪═════════════════════╪═════════════════════════════════╡
#> │ 2022-01-01 10:00:00 ┆ 2022-01-01 12:00:00 ┆ [2022-01-01 10:00:00, 2022-01-… │
#> │ 2022-01-01 11:00:00 ┆ 2022-01-01 12:00:00 ┆ [2022-01-01 11:00:00]           │
#> │ null                ┆ 2022-01-01 12:00:00 ┆ null                            │
#> └─────────────────────┴─────────────────────┴─────────────────────────────────┘