roll_by: Roll scheduled events

In jameslairdsmith/scheduler: A grammar of recurring calendar events

Roll scheduled events

Description

Given a schedule of events, create a new schedule where the events are adjusted according to some rule.

• roll_by() adjusts the events of a schedule by some incremental period.

• roll_forward() and roll_backward() adjust the events of a schedule to the nth previous/next occurrence of some other scheduled event.

Usage

roll_by(x, n, unit, .p = NULL)

roll_forward(x, to_schedule, n = 1, .p = NULL)

roll_backward(x, to_schedule, n = 1, .p = NULL)

Arguments

x	The schedule of events to adjust.
n	The increment of the event adjustment. For roll_by() this is the increment of the unit period to adjust the events by. Eg. 2 to adjust the events two unit periods into the future or -3 to adjust the events three unit periods into the past. For roll_forward() and roll_backward(), n defaults to 1, indicating the schedule should be adjusted to the to_schedule event immediately preceding/following the events of x. If more than 1, will skip n-1 occurrences.
unit	A character shortcut for a period object. Eg. "year", "years", "month", "months", "week", "weeks" etc. Can be any value accepted by lubridate::period().
.p	Optionally, a schedule to use for limiting the adjustment performed on x. Events falling on .p will be adjusted. Events not falling on .p will be returned unadjusted in the output schedule. Leave NULL (the default) to adjust all the events of x. Eg. roll_forward(x, to_schedule = on_wday("Sun")) rolls the events of x to the next Sunday.
to_schedule	A schedule to which events can be rolled.

Value

A schedule object.

Examples

library(lubridate, warn.conflicts = FALSE)
library(magrittr, warn.conflicts = FALSE)

# Imagine you get paid on the 25th of the month

on_payday <- on_mday(25)

schedule_days(on_payday, during = 2000)

# Except if your payday falls on a weekend, in which case it moves to the
# next weekday

on_payday %>%
  roll_forward(to = on_weekday(), .p = on_weekend()) %>%
  schedule_days(during = 2000)

# For some people payday may adjust to the previous weekday if it falls on
# a weekend

on_payday %>%
  roll_backward(to = on_weekday(), .p = on_weekend()) %>%
  schedule_days(during = 2000)

# Imagine the garbage truck normally comes every Monday, but if
# Monday is a state holiday, then it comes on Tuesday instead.

on_labor_day <-
  on_first(on_wday("Mon"), within_given = "month") %>%
  only_occur(in_month("Sep"))

on_christmas_day <- only_occur(in_month("Dec"), on_mday(25))

on_non_working_day <-
  on_weekend() %>%
  also_occur(on_labor_day) %>%
  also_occur(on_christmas_day)

on_my_business_day <- dont_occur(on_non_working_day)

on_normal_trash_day <- on_wday("Mon")

on_trash_day <-
  on_normal_trash_day %>%
  roll_forward(to_schedule = on_my_business_day, .p = on_non_working_day)

# A Monday in September
happen(on_normal_trash_day, ymd("2019-09-09"))
happen(on_trash_day, ymd("2019-09-09"))

# Labor Day Monday should not be trash day
happen(on_normal_trash_day, ymd("2019-09-02"))
happen(on_trash_day, ymd("2019-09-02"))

# The day after Labor Day Monday is trash day
happen(on_normal_trash_day, ymd("2019-09-03"))
happen(on_trash_day, ymd("2019-09-03"))

# Say that a trash inspector always comes the day after trash day, whatever
# day that happens to be.

on_inspection_day <-
  on_trash_day %>%
  roll_by(1, "day")

# Inspector comes on a Tuesday in September
happen(on_inspection_day, ymd("2019-09-10"))

# Inspector doesn't come on that Wednesday
happen(on_inspection_day, ymd("2019-09-11"))

# Inspector doesn't come on the Tuesday after Labor Day Monday
happen(on_inspection_day, ymd("2019-09-03"))

# Inspector does come on that Wednesday
happen(on_inspection_day, ymd("2019-09-04"))

jameslairdsmith/scheduler documentation built on July 27, 2023, 6:06 p.m.