Skip to content

Offset By

Source code

Description

Offset this date by a relative time offset. This differs from pl$col(“foo_datetime_tu”) + value_tu in that it can take months and leap years into account. Note that only a single minus sign is allowed in the by string, as the first character.

Usage

<Expr>$dt$offset_by(by)

Arguments

by optional string encoding duration see details.

Details

The by 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
  • 1i \# 1 index count

These strings can be combined:

  • 3d12h4m25s \# 3 days, 12 hours, 4 minutes, and 25 seconds

Value

Date/Datetime expr

Examples

library("polars")

df = pl$DataFrame(
  dates = pl$date_range(
    as.Date("2000-1-1"),
    as.Date("2005-1-1"),
    "1y"
  )
)
df$select(
  pl$col("dates")$dt$offset_by("1y")$alias("date_plus_1y"),
  pl$col("dates")$dt$offset_by("-1y2mo")$alias("date_min")
)

#> shape: (6, 2)
#> ┌──────────────┬────────────┐
#> │ date_plus_1y ┆ date_min   │
#> │ ---          ┆ ---        │
#> │ date         ┆ date       │
#> ╞══════════════╪════════════╡
#> │ 2001-01-01   ┆ 1998-11-01 │
#> │ 2002-01-01   ┆ 1999-11-01 │
#> │ 2003-01-01   ┆ 2000-11-01 │
#> │ 2004-01-01   ┆ 2001-11-01 │
#> │ 2005-01-01   ┆ 2002-11-01 │
#> │ 2006-01-01   ┆ 2003-11-01 │
#> └──────────────┴────────────┘

# the "by" argument also accepts expressions
df = pl$DataFrame(
  dates = pl$datetime_range(
    as.POSIXct("2022-01-01", tz = "GMT"),
    as.POSIXct("2022-01-02", tz = "GMT"),
    interval = "6h", time_unit = "ms", time_zone = "GMT"
  )$to_r(),
  offset = c("1d", "-2d", "1mo", NA, "1y")
)

df

#> shape: (5, 2)
#> ┌─────────────────────────┬────────┐
#> │ dates                   ┆ offset │
#> │ ---                     ┆ ---    │
#> │ datetime[ms, GMT]       ┆ str    │
#> ╞═════════════════════════╪════════╡
#> │ 2022-01-01 00:00:00 GMT ┆ 1d     │
#> │ 2022-01-01 06:00:00 GMT ┆ -2d    │
#> │ 2022-01-01 12:00:00 GMT ┆ 1mo    │
#> │ 2022-01-01 18:00:00 GMT ┆ null   │
#> │ 2022-01-02 00:00:00 GMT ┆ 1y     │
#> └─────────────────────────┴────────┘

df$with_columns(new_dates = pl$col("dates")$dt$offset_by(pl$col("offset")))

#> shape: (5, 3)
#> ┌─────────────────────────┬────────┬─────────────────────────┐
#> │ dates                   ┆ offset ┆ new_dates               │
#> │ ---                     ┆ ---    ┆ ---                     │
#> │ datetime[ms, GMT]       ┆ str    ┆ datetime[ms, GMT]       │
#> ╞═════════════════════════╪════════╪═════════════════════════╡
#> │ 2022-01-01 00:00:00 GMT ┆ 1d     ┆ 2022-01-02 00:00:00 GMT │
#> │ 2022-01-01 06:00:00 GMT ┆ -2d    ┆ 2021-12-30 06:00:00 GMT │
#> │ 2022-01-01 12:00:00 GMT ┆ 1mo    ┆ 2022-02-01 12:00:00 GMT │
#> │ 2022-01-01 18:00:00 GMT ┆ null   ┆ null                    │
#> │ 2022-01-02 00:00:00 GMT ┆ 1y     ┆ 2023-01-02 00:00:00 GMT │
#> └─────────────────────────┴────────┴─────────────────────────┘