Offset by `n` business days.

Description

Offset by n business days.

Usage

<Expr>$dt$add_business_days(
  n,
  ...,
  week_mask = c(TRUE, TRUE, TRUE, TRUE, TRUE, FALSE, FALSE),
  holidays = as.Date(integer(0)),
  roll = c("raise", "backward", "forward")
)

Arguments

n An integer value or a polars expression representing the number of business days to offset by.

… These dots are for future extensions and must be empty.

week_mask Non-NA logical vector of length 7, representing the days of the week to count. The default is Monday to Friday (c(TRUE, TRUE, TRUE, TRUE, TRUE, FALSE, FALSE)). If you wanted to count only Monday to Thursday, you would pass c(TRUE, TRUE, TRUE, TRUE, FALSE, FALSE, FALSE).

holidays A Date class vector, representing the holidays to exclude from the count.

roll

What to do when the start date lands on a non-business day. Options are:

“raise”: raise an error;
“forward”: move to the next business day;
“backward”: move to the previous business day.

Value

A polars expression

Examples

library("polars")

df <- pl$DataFrame(start = as.Date(c("2020-1-1", "2020-1-2")))
df$with_columns(result = pl$col("start")$dt$add_business_days(5))

#> shape: (2, 2)
#> ┌────────────┬────────────┐
#> │ start      ┆ result     │
#> │ ---        ┆ ---        │
#> │ date       ┆ date       │
#> ╞════════════╪════════════╡
#> │ 2020-01-01 ┆ 2020-01-08 │
#> │ 2020-01-02 ┆ 2020-01-09 │
#> └────────────┴────────────┘

# You can pass a custom weekend - for example, if you only take Sunday off:
week_mask <- c(TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, FALSE)
df$with_columns(
  result = pl$col("start")$dt$add_business_days(5, week_mask = week_mask)
)

#> shape: (2, 2)
#> ┌────────────┬────────────┐
#> │ start      ┆ result     │
#> │ ---        ┆ ---        │
#> │ date       ┆ date       │
#> ╞════════════╪════════════╡
#> │ 2020-01-01 ┆ 2020-01-07 │
#> │ 2020-01-02 ┆ 2020-01-08 │
#> └────────────┴────────────┘

# You can also pass a list of holidays:
holidays <- as.Date(c("2020-1-3", "2020-1-6"))
df$with_columns(
  result = pl$col("start")$dt$add_business_days(5, holidays = holidays)
)

#> shape: (2, 2)
#> ┌────────────┬────────────┐
#> │ start      ┆ result     │
#> │ ---        ┆ ---        │
#> │ date       ┆ date       │
#> ╞════════════╪════════════╡
#> │ 2020-01-01 ┆ 2020-01-10 │
#> │ 2020-01-02 ┆ 2020-01-13 │
#> └────────────┴────────────┘

# Roll all dates forwards to the next business day:
df <- pl$DataFrame(start = as.Date(c("2020-1-5", "2020-1-6")))
df$with_columns(
  rolled_forwards = pl$col("start")$dt$add_business_days(0, roll = "forward")
)

#> shape: (2, 2)
#> ┌────────────┬─────────────────┐
#> │ start      ┆ rolled_forwards │
#> │ ---        ┆ ---             │
#> │ date       ┆ date            │
#> ╞════════════╪═════════════════╡
#> │ 2020-01-05 ┆ 2020-01-06      │
#> │ 2020-01-06 ┆ 2020-01-06      │
#> └────────────┴─────────────────┘

Offset by n business days.