time_point_shift: Shifting: time point

In clock: Date-Time Types and Tools

Shifting: time point

Description

time_point_shift() shifts x to the target weekday. You can shift to the next or previous weekday. If x is currently on the target weekday, you can choose to leave it alone or advance it to the next instance of the target.

Weekday shifting is one of the easiest ways to floor by week while controlling what is considered the first day of the week. You can also accomplish this with the origin argument of time_point_floor(), but this is slightly easier.

Usage

time_point_shift(x, target, ..., which = "next", boundary = "keep")

Arguments

x	⁠[clock_time_point]⁠ A time point.
target	⁠[weekday]⁠ A weekday created from weekday() to target. Generally this is length 1, but can also be the same length as x.
...	These dots are for future extensions and must be empty.
which	⁠[character(1)]⁠ One of: "next": Shift to the next instance of the target weekday. ⁠"previous⁠: Shift to the previous instance of the target weekday.
boundary	⁠[character(1)]⁠ One of: "keep": If x is currently on the target weekday, return it. "advance": If x is currently on the target weekday, advance it anyways.

Value

x shifted to the target weekday.

Examples

x <- as_naive_time(year_month_day(2019, 1, 1:2))

# A Tuesday and Wednesday
as_weekday(x)

monday <- weekday(clock_weekdays$monday)

# Shift to the next Monday
time_point_shift(x, monday)

# Shift to the previous Monday
# This is an easy way to "floor by week" with a target weekday in mind
time_point_shift(x, monday, which = "previous")

# What about Tuesday?
tuesday <- weekday(clock_weekdays$tuesday)

# Notice that the day that was currently on a Tuesday was not shifted
time_point_shift(x, tuesday)

# You can force it to `"advance"`
time_point_shift(x, tuesday, boundary = "advance")

clock documentation built on Sept. 11, 2024, 8:39 p.m.