Implement date_start() and date_end()

Author: DavisVaughan

NAMESPACE

@@ -221,6 +221,8 @@ S3method(calendar_widen,clock_year_month_weekday)
 S3method(calendar_widen,clock_year_quarter_day)
 S3method(date_ceiling,Date)
 S3method(date_ceiling,POSIXt)
+S3method(date_end,Date)
+S3method(date_end,POSIXt)
 S3method(date_floor,Date)
 S3method(date_floor,POSIXt)
 S3method(date_format,Date)
@@ -239,6 +241,8 @@ S3method(date_set_zone,Date)
 S3method(date_set_zone,POSIXt)
 S3method(date_shift,Date)
 S3method(date_shift,POSIXt)
+S3method(date_start,Date)
+S3method(date_start,POSIXt)
 S3method(date_weekday_factor,Date)
 S3method(date_weekday_factor,POSIXt)
 S3method(date_zone,Date)
@@ -588,6 +592,7 @@ export(clock_labels_lookup)
 export(clock_locale)
 export(date_build)
 export(date_ceiling)
+export(date_end)
 export(date_floor)
 export(date_format)
 export(date_group)
@@ -599,6 +604,7 @@ export(date_round)
 export(date_seq)
 export(date_set_zone)
 export(date_shift)
+export(date_start)
 export(date_time_build)
 export(date_time_parse)
 export(date_time_parse_abbrev)

R/date.R

@@ -1229,6 +1229,122 @@ date_today <- function(zone) {
 
 # ------------------------------------------------------------------------------
 
+#' Boundaries: date and date-time
+#'
+#' @description
+#' - `date_start()` computes the date at the start of a particular
+#'   `precision`, such as the "start of the year".
+#'
+#' - `date_end()` computes the date at the end of a particular
+#'   `precision`, such as the "end of the month".
+#'
+#' There are separate help pages for computing boundaries for dates and
+#' date-times:
+#'
+#' - [dates (Date)][date-boundary]
+#'
+#' - [date-times (POSIXct/POSIXlt)][posixt-boundary]
+#'
+#' @inheritParams date_group
+#'
+#' @param x `[Date / POSIXct / POSIXlt]`
+#'
+#'   A date or date-time vector.
+#'
+#' @param precision `[character(1)]`
+#'
+#'   A precision. Allowed precisions are dependent on the input used.
+#'
+#' @return `x` but with some components altered to be at the boundary value.
+#'
+#' @name date-and-date-time-boundary
+#'
+#' @examples
+#' # See type specific documentation for more examples
+#'
+#' x <- date_build(2019, 2:4)
+#'
+#' date_end(x, "month")
+#'
+#' x <- date_time_build(2019, 2:4, 3:5, 4, 5, zone = "America/New_York")
+#'
+#' # Note that the hour, minute, and second components are also adjusted
+#' date_end(x, "month")
+NULL
+
+#' @rdname date-and-date-time-boundary
+#' @export
+date_start <- function(x, precision, ...) {
+  UseMethod("date_start")
+}
+
+#' @rdname date-and-date-time-boundary
+#' @export
+date_end <- function(x, precision, ...) {
+  UseMethod("date_end")
+}
+
+
+#' Boundaries: date
+#'
+#' @description
+#' This is a Date method for the [date_start()] and [date_end()] generics.
+#'
+#' @inheritParams date_group
+#' @inheritParams invalid_resolve
+#'
+#' @param x `[Date]`
+#'
+#'   A date vector.
+#'
+#' @param precision `[character(1)]`
+#'
+#'   One of:
+#'
+#'   - `"year"`
+#'
+#'   - `"month"`
+#'
+#'   - `"day"`
+#'
+#' @return `x` but with some components altered to be at the boundary value.
+#'
+#' @name date-boundary
+#'
+#' @examples
+#' x <- date_build(2019:2021, 2:4, 3:5)
+#' x
+#'
+#' # Last day of the month
+#' date_end(x, "month")
+#'
+#' # Last day of the year
+#' date_end(x, "year")
+#'
+#' # First day of the year
+#' date_start(x, "year")
+NULL
+
+#' @rdname date-boundary
+#' @export
+date_start.Date <- function(x, precision, ..., invalid = NULL) {
+  check_dots_empty()
+  x <- as_year_month_day(x)
+  x <- calendar_start(x, precision)
+  as.Date(x, invalid = invalid)
+}
+
+#' @rdname date-boundary
+#' @export
+date_end.Date <- function(x, precision, ..., invalid = NULL) {
+  check_dots_empty()
+  x <- as_year_month_day(x)
+  x <- calendar_end(x, precision)
+  as.Date(x, invalid = invalid)
+}
+
+# ------------------------------------------------------------------------------
+
 #' Sequences: date and date-time
 #'
 #' @description

R/posixt.R

@@ -1427,6 +1427,91 @@ date_now <- function(zone) {
 
 # ------------------------------------------------------------------------------
 
+#' Boundaries: date-time
+#'
+#' @description
+#' This is a POSIXct/POSIXlt method for the [date_start()] and [date_end()]
+#' generics.
+#'
+#' @inheritParams date_group
+#' @inheritParams invalid_resolve
+#' @inheritParams as-zoned-time-naive-time
+#'
+#' @param x `[POSIXct / POSIXlt]`
+#'
+#'   A date-time vector.
+#'
+#' @param precision `[character(1)]`
+#'
+#'   One of:
+#'
+#'   - `"year"`
+#'
+#'   - `"month"`
+#'
+#'   - `"day"`
+#'
+#'   - `"hour"`
+#'
+#'   - `"minute"`
+#'
+#'   - `"second"`
+#'
+#' @return `x` but with some components altered to be at the boundary value.
+#'
+#' @name posixt-boundary
+#'
+#' @examples
+#' x <- date_time_build(2019:2021, 2:4, 3:5, 4, 5, 6, zone = "America/New_York")
+#' x
+#'
+#' # Last moment of the month
+#' date_end(x, "month")
+#'
+#' # Notice that this is different from just setting the day to `"last"`
+#' set_day(x, "last")
+#'
+#' # Last moment of the year
+#' date_end(x, "year")
+#'
+#' # First moment of the hour
+#' date_start(x, "hour")
+NULL
+
+#' @rdname posixt-boundary
+#' @export
+date_start.POSIXt <- function(x,
+                              precision,
+                              ...,
+                              invalid = NULL,
+                              nonexistent = NULL,
+                              ambiguous = x) {
+  check_dots_empty()
+  force(ambiguous)
+  zone <- date_zone(x)
+  x <- as_year_month_day(x)
+  x <- calendar_start(x, precision)
+  as.POSIXct(x, zone, invalid = invalid, nonexistent = nonexistent, ambiguous = ambiguous)
+}
+
+#' @rdname posixt-boundary
+#' @export
+date_end.POSIXt <- function(x,
+                            precision,
+                            ...,
+                            invalid = NULL,
+                            nonexistent = NULL,
+                            ambiguous = x) {
+  check_dots_empty()
+  force(ambiguous)
+  zone <- date_zone(x)
+  x <- as_year_month_day(x)
+  x <- calendar_end(x, precision)
+  as.POSIXct(x, zone, invalid = invalid, nonexistent = nonexistent, ambiguous = ambiguous)
+}
+
+# ------------------------------------------------------------------------------
+
 #' Sequences: date-time
 #'
 #' @description

_pkgdown.yml

@@ -15,6 +15,7 @@ reference:
   - date_time_build
   - date-today
   - date_group
+  - date-and-date-time-boundary
   - date-and-date-time-rounding
   - date-and-date-time-shifting
   - date_seq
@@ -197,6 +198,8 @@ reference:
   contents:
   - date-group
   - posixt-group
+  - date-boundary
+  - posixt-boundary
   - date-formatting
   - posixt-formatting
   - date-rounding