Skip to content

Create polars Duration from distinct time components

Description

A Duration represents a fixed amount of time. For example, pl$duration(days = 1) means "exactly 24 hours". By contrast, <expr>$dt$offset_by("1d") means "1 calendar day", which could sometimes be 23 hours or 25 hours depending on Daylight Savings Time. For non-fixed durations such as "calendar month" or "calendar day", please use <expr>$dt$offset_by() instead.

Usage

pl$duration(
  ...,
  weeks = NULL,
  days = NULL,
  hours = NULL,
  minutes = NULL,
  seconds = NULL,
  milliseconds = NULL,
  microseconds = NULL,
  nanoseconds = NULL,
  time_unit = NULL
)

Arguments

… These dots are for future extensions and must be empty.
weeks Something can be coerced to an polars expression by as_polars_expr() which represents a column or literal number of weeks, or NULL (default).
days Something can be coerced to an polars expression by as_polars_expr() which represents a column or literal number of days, or NULL (default).
hours Something can be coerced to an polars expression by as_polars_expr() which represents a column or literal number of hours, or NULL (default).
minutes Something can be coerced to an polars expression by as_polars_expr() which represents a column or literal number of minutes, or NULL (default).
seconds Something can be coerced to an polars expression by as_polars_expr() which represents a column or literal number of seconds, or NULL (default).
milliseconds Something can be coerced to an polars expression by as_polars_expr() which represents a column or literal number of milliseconds, or NULL (default).
microseconds Something can be coerced to an polars expression by as_polars_expr() which represents a column or literal number of microseconds, or NULL (default).
nanoseconds Something can be coerced to an polars expression by as_polars_expr() which represents a column or literal number of nanoseconds, or NULL (default).
time_unit One of NULL, “us” (microseconds), “ns” (nanoseconds) or “ms”(milliseconds). Representing the unit of time. If NULL (default), the time unit will be inferred from the other inputs: “ns” if nanoseconds was specified, “us” otherwise.

Value

A polars expression

Examples

library("polars")

df <- pl$DataFrame(
  dt = as.POSIXct(c("2022-01-01", "2022-01-02")),
  add = c(1, 2)
)
df

#> shape: (2, 2)
#> ┌─────────────────────┬─────┐
#> │ dt                  ┆ add │
#> │ ---                 ┆ --- │
#> │ datetime[ms]        ┆ f64 │
#> ╞═════════════════════╪═════╡
#> │ 2022-01-01 00:00:00 ┆ 1.0 │
#> │ 2022-01-02 00:00:00 ┆ 2.0 │
#> └─────────────────────┴─────┘

df$select(
  add_weeks = pl$col("dt") + pl$duration(weeks = pl$col("add")),
  add_days = pl$col("dt") + pl$duration(days = pl$col("add")),
  add_seconds = pl$col("dt") + pl$duration(seconds = pl$col("add")),
  add_millis = pl$col("dt") + pl$duration(milliseconds = pl$col("add")),
  add_hours = pl$col("dt") + pl$duration(hours = pl$col("add"))
)

#> shape: (2, 5)
#> ┌──────────────┬──────────────┬─────────────────────┬──────────────┬─────────────────────┐
#> │ add_weeks    ┆ add_days     ┆ add_seconds         ┆ add_millis   ┆ add_hours           │
#> │ ---          ┆ ---          ┆ ---                 ┆ ---          ┆ ---                 │
#> │ datetime[ms] ┆ datetime[ms] ┆ datetime[ms]        ┆ datetime[ms] ┆ datetime[ms]        │
#> ╞══════════════╪══════════════╪═════════════════════╪══════════════╪═════════════════════╡
#> │ 2022-01-08   ┆ 2022-01-02   ┆ 2022-01-01 00:00:01 ┆ 2022-01-01   ┆ 2022-01-01 01:00:00 │
#> │ 00:00:00     ┆ 00:00:00     ┆                     ┆ 00:00:00.001 ┆                     │
#> │ 2022-01-16   ┆ 2022-01-04   ┆ 2022-01-02 00:00:02 ┆ 2022-01-02   ┆ 2022-01-02 02:00:00 │
#> │ 00:00:00     ┆ 00:00:00     ┆                     ┆ 00:00:00.002 ┆                     │
#> └──────────────┴──────────────┴─────────────────────┴──────────────┴─────────────────────┘