New almanac_since/until() and don't override until

NAMESPACE

@@ -47,6 +47,8 @@ export(alma_previous)
 export(alma_search)
 export(alma_seq)
 export(alma_step)
+export(almanac_since)
+export(almanac_until)
 export(daily)
 export(monthly)
 export(new_rschedule)

NEWS.md

@@ -1,5 +1,10 @@
 # almanac (development version)
 
+* `recur_for_count()` no longer overrides `until` (#95).
+
+* New `almanac_since()` and `almanac_until()` helpers to access the default
+  `since` and `until` values used for all rules (#95).
+
 * `alma_events()` has gained a `year` argument to limit the returned set of
   events to specific years.
 

R/defaults.R

@@ -0,0 +1,36 @@
+#' Default values in almanac
+#'
+#' @description
+#' - `almanac_since()` represents the default `since` date used in almanac. It
+#'   defaults to `1900-01-01`, a Monday.
+#'
+#' - `almanac_until()` represents the default `until` date used in almanac. It
+#'   defaults to `2100-01-01`, a Friday.
+#'
+#' The choice of `since` and `until` are somewhat arbitrary, but should generate
+#' a useful event set range for most rschedules. If you need to adjust the
+#' defaults, then you should supply the `since` and `until` arguments directly
+#' to the rrule generators, like [yearly()] and [weekly()].
+#'
+#' The `since` default is particularly important for weekly recurrence rules,
+#' where the `since` date represents the anchor point to begin counting from.
+#' See [recur_on_day_of_week()] for examples of how to adjust this.
+#'
+#' @name almanac-defaults
+#'
+#' @examples
+#' almanac_since()
+#' almanac_until()
+NULL
+
+#' @export
+#' @rdname almanac-defaults
+almanac_since <- function() {
+  almanac_global_default_since
+}
+
+#' @export
+#' @rdname almanac-defaults
+almanac_until <- function() {
+  almanac_global_default_until
+}

R/recur-for-count.R

@@ -2,11 +2,12 @@
 #'
 #' @description
 #' `recur_for_count()` controls the total number of events in the recurrence
-#' set. Using `recur_for_count()` will override the `until` date of the rule.
+#' set.
 #'
 #' @details
 #' Remember that the number of times the occurrence has occurred is counted
-#' from the `since` date! Adjust it as necessary to get your desired results.
+#' from the `since` date and is limited by the `until` date! Adjust them as
+#' necessary to get your desired results.
 #'
 #' @param x `[rrule]`
 #'
@@ -46,6 +47,5 @@ recur_for_count <- function(x, n) {
   check_number_whole(n, min = 1)
   n <- vec_cast(n, to = integer())
 
-  # Override `until`
-  tweak_rrule(x, until = NULL, count = n)
+  tweak_rrule(x, count = n)
 }

R/recur-on-day-of-week.R

@@ -15,7 +15,8 @@
 #'
 #' It is particularly important to pay attention to the `since` date when using
 #' weekly rules. The day of the week to use comes from the `since` date, which,
-#' by default, is a Monday (`1900-01-01`).
+#' by default, is a Monday (`1900-01-01`). See [almanac_since()] for more
+#' information.
 #'
 #' @inheritParams rlang::args_dots_empty
 #'
@@ -45,7 +46,7 @@
 #' start <- "1999-01-01" # <- a Friday
 #' end <- "1999-03-01"
 #'
-#' # This finds the first Thursday, and then continues from there
+#' # This finds the first Monday, and then continues from there
 #' alma_search(start, end, on_weekly_mondays)
 #'
 #' # We start counting from a Friday here

R/rrule-print.R

@@ -12,8 +12,7 @@ format_body <- function(x) {
 
   info <- c(
     format_frequency(x),
-    format_since(x),
-    format_until(x),
+    format_range(x),
     format_count(x),
     format_interval(x),
     format_week_start(x),
@@ -33,19 +32,8 @@ format_frequency <- function(x) {
   cli::format_inline("frequency: {x$frequency}")
 }
 
-format_since <- function(x) {
-  cli::format_inline("since: {x$since}")
-}
-
-format_until <- function(x) {
-  until <- x$until
-
-  if (is.null(until)) {
-    # Can be overriden when setting `count`
-    character()
-  } else {
-    cli::format_inline("until: {until}")
-  }
+format_range <- function(x) {
+  cli::format_inline("range: [{x$since}, {x$until}]")
 }
 
 format_count <- function(x) {
@@ -172,4 +160,5 @@ format_easter <- function(x) {
   } else {
     cli::format_inline("easter: offset = {easter}")
   }
+
 }

R/rrule.R

@@ -16,7 +16,8 @@
 #' @details
 #' By default, `since == "1900-01-01"` and `until == "2100-01-01"`, which should
 #' capture most use cases well while still being performant. You may need to
-#' adjust these dates if you want events outside this range.
+#' adjust these dates if you want events outside this range. See
+#' [almanac_since()] and [almanac_until()] for more information.
 #'
 #' In terms of speed, it is generally more efficient if you adjust the `since`
 #' and `until` date to be closer to the first date in the sequence of dates
@@ -83,25 +84,25 @@ NULL
 
 #' @rdname rrule
 #' @export
-daily <- function(since = "1900-01-01", until = "2100-01-01") {
+daily <- function(since = NULL, until = NULL) {
   rrule(since, until, frequency = "daily")
 }
 
 #' @rdname rrule
 #' @export
-weekly <- function(since = "1900-01-01", until = "2100-01-01") {
+weekly <- function(since = NULL, until = NULL) {
   rrule(since, until, frequency = "weekly")
 }
 
 #' @rdname rrule
 #' @export
-monthly <- function(since = "1900-01-01", until = "2100-01-01") {
+monthly <- function(since = NULL, until = NULL) {
   rrule(since, until, frequency = "monthly")
 }
 
 #' @rdname rrule
 #' @export
-yearly <- function(since = "1900-01-01", until = "2100-01-01") {
+yearly <- function(since = NULL, until = NULL) {
   rrule(since, until, frequency = "yearly")
 }
 
@@ -115,6 +116,13 @@ rschedule_events.almanac_rrule <- function(x) {
 # ------------------------------------------------------------------------------
 
 rrule <- function(since, until, frequency, ..., call = caller_env()) {
+  if (is_null(since)) {
+    since <- almanac_since()
+  }
+  if (is_null(until)) {
+    until <- almanac_until()
+  }
+
   since <- vec_cast_date(since, call = call)
   vec_check_size(since, size = 1L, call = call)
   check_no_missing(since, call = call)
@@ -138,8 +146,8 @@ rrule <- function(since, until, frequency, ..., call = caller_env()) {
   )
 }
 
-new_rrule <- function(since = as.Date("1900-01-01"),
-                      until = as.Date("2100-01-01"),
+new_rrule <- function(since = almanac_since(),
+                      until = almanac_until(),
                       frequency = "yearly",
                       count = NULL,
                       interval = NULL,

R/stepper.R

@@ -117,7 +117,7 @@ stepper <- function(rschedule) {
 
 #' @rdname stepper
 #' @export
-workdays <- function(n, since = "1900-01-01", until = "2100-01-01") {
+workdays <- function(n, since = NULL, until = NULL) {
   rschedule <- weekly(since = since, until = until)
   rschedule <- recur_on_weekends(rschedule)
   workdays_stepper <- stepper(rschedule)

README.md

@@ -48,8 +48,7 @@ on_thanksgiving <- yearly() %>%
 on_thanksgiving
 #> <rrule>
 #> • frequency: yearly
-#> • since: 1900-01-01
-#> • until: 2100-01-01
+#> • range: [1900-01-01, 2100-01-01]
 #> • month of year: Nov
 #> • day of week: Thu[4]
 ```
@@ -126,19 +125,16 @@ bundle
 #> <runion[3]>
 #>  <rrule>
 #>  • frequency: weekly
-#>  • since: 1900-01-01
-#>  • until: 2100-01-01
+#>  • range: [1900-01-01, 2100-01-01]
 #>  • day of week: Sat, and Sun
 #>  <rrule>
 #>  • frequency: yearly
-#>  • since: 1900-01-01
-#>  • until: 2100-01-01
+#>  • range: [1900-01-01, 2100-01-01]
 #>  • month of year: Dec
 #>  • day of month: 25
 #>  <rrule>
 #>  • frequency: yearly
-#>  • since: 1900-01-01
-#>  • until: 2100-01-01
+#>  • range: [1900-01-01, 2100-01-01]
 #>  • month of year: Nov
 #>  • day of week: Thu[4]
 ```

_pkgdown.yml

@@ -37,6 +37,7 @@ reference:
 - title: Developer tools
   contents:
   - new_rschedule
+  - starts_with("almanac_")
 
 - title: Compatibility
   contents:

tests/testthat/_snaps/radjusted.md

@@ -40,13 +40,11 @@
        adjust:
        <rrule>
        * frequency: daily
-       * since: 1900-01-01
-       * until: 2100-01-01
+       * range: [1900-01-01, 2100-01-01]
        adjust on:
        <rrule>
        * frequency: daily
-       * since: 1900-01-01
-       * until: 2100-01-01
+       * range: [1900-01-01, 2100-01-01]
     Code
       # # with runions
       rrule <- recur_on_day_of_week(weekly(), "Wed")
@@ -57,13 +55,11 @@
        adjust:
        <rrule>
        * frequency: weekly
-       * since: 1900-01-01
-       * until: 2100-01-01
+       * range: [1900-01-01, 2100-01-01]
        * day of week: Wed
        adjust on:
        <runion[1]>
         <rrule>
         * frequency: weekly
-        * since: 1900-01-01
-        * until: 2100-01-01
+        * range: [1900-01-01, 2100-01-01]
 

tests/testthat/_snaps/rcustom.md

@@ -38,8 +38,7 @@
        * and 95 more
        <rrule>
        * frequency: yearly
-       * since: 1900-01-01
-       * until: 2100-01-01
+       * range: [1900-01-01, 2100-01-01]
 
 # `events` can't be missing