Implement as_date() and as_date_time() (#215)

Author: DavisVaughan

NAMESPACE

@@ -93,6 +93,17 @@ S3method(as.character,clock_year_quarter_day)
 S3method(as.character,clock_zoned_time)
 S3method(as.double,clock_duration)
 S3method(as.integer,clock_duration)
+S3method(as_date,Date)
+S3method(as_date,POSIXt)
+S3method(as_date,clock_calendar)
+S3method(as_date,clock_time_point)
+S3method(as_date,clock_zoned_time)
+S3method(as_date_time,Date)
+S3method(as_date_time,POSIXt)
+S3method(as_date_time,clock_calendar)
+S3method(as_date_time,clock_naive_time)
+S3method(as_date_time,clock_sys_time)
+S3method(as_date_time,clock_zoned_time)
 S3method(as_duration,clock_duration)
 S3method(as_duration,clock_time_point)
 S3method(as_iso_year_week_day,Date)
@@ -536,6 +547,8 @@ export(add_quarters)
 export(add_seconds)
 export(add_weeks)
 export(add_years)
+export(as_date)
+export(as_date_time)
 export(as_duration)
 export(as_iso_year_week_day)
 export(as_naive_time)

NEWS.md

@@ -27,6 +27,11 @@
     a direct conversion impossible, `nonexistent` and `ambiguous` can be used
     to resolve any issues.
 
+* New `as_date()` and `as_date_time()` for converting to Date and POSIXct
+  respectively. Unlike `as.Date()` and `as.POSIXct()`, these functions always
+  treat Date as a naive-time type, which results in more consistent and
+  intuitive conversions (#209).
+
 * Added two new convenient helpers (#197):
 
   * `date_today()` for getting the current date (Date)

R/date.R

@@ -127,6 +127,72 @@ as.Date.clock_zoned_time <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
+#' Convert to a date
+#'
+#' @description
+#' `as_date()` is a generic function that converts its input to a date (Date).
+#'
+#' There are methods for converting date-times (POSIXct), calendars,
+#' time points, and zoned-times to dates.
+#'
+#' @details
+#' Note that clock always assumes that R's Date class is naive, so converting
+#' a POSIXct to a Date will always retain the printed year, month, and day
+#' value.
+#'
+#' @param x `[vector]`
+#'
+#'   A vector.
+#'
+#' @export
+#' @examples
+#' x <- date_time_parse("2019-01-01 23:02:03", "America/New_York")
+#'
+#' # R's `as.Date.POSIXct()` method defaults to changing the printed time
+#' # to UTC before converting, which can result in odd conversions like this:
+#' as.Date(x)
+#'
+#' # `as_date()` will never change the printed time before converting
+#' as_date(x)
+#'
+#' # Can also convert from other clock types
+#' as_date(year_month_day(2019, 2, 5))
+as_date <- function(x) {
+  UseMethod("as_date")
+}
+
+#' @rdname as_date
+#' @export
+as_date.Date <- function(x) {
+  date_standardize(x)
+}
+
+#' @rdname as_date
+#' @export
+as_date.POSIXt <- function(x) {
+  as.Date(as_naive_time(x))
+}
+
+#' @rdname as_date
+#' @export
+as_date.clock_calendar <- function(x) {
+  as.Date(x)
+}
+
+#' @rdname as_date
+#' @export
+as_date.clock_time_point <- function(x) {
+  as.Date(x)
+}
+
+#' @rdname as_date
+#' @export
+as_date.clock_zoned_time <- function(x) {
+  as.Date(x)
+}
+
+# ------------------------------------------------------------------------------
+
 #' Getters: date
 #'
 #' @description

R/posixt.R

@@ -158,6 +158,109 @@ as.POSIXlt.clock_zoned_time <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
+#' Convert to a date-time
+#'
+#' @description
+#' `as_date_time()` is a generic function that converts its input to a date-time
+#' (POSIXct).
+#'
+#' There are methods for converting dates (Date), calendars, time points, and
+#' zoned-times to date-times.
+#'
+#' @details
+#' Note that clock always assumes that R's Date class is naive, so converting
+#' a Date to a POSIXct will always attempt to retain the printed year, month,
+#' and day. Where possible, the resulting time will be at midnight (`00:00:00`),
+#' but in some rare cases this is not possible due to daylight saving time. If
+#' that issue ever arises, an error will be thrown, which can be resolved by
+#' explicitly supplying `nonexistent` or `ambiguous`.
+#'
+#' @inheritParams as-zoned-time-naive-time
+#'
+#' @param x `[vector]`
+#'
+#'   A vector.
+#'
+#' @export
+#' @examples
+#' x <- as.Date("2019-01-01")
+#'
+#' # `as.POSIXct()` will always treat Date as UTC, but will show the result
+#' # of the conversion in your system time zone, which can be somewhat confusing
+#' if (rlang::is_installed("withr")) {
+#'   withr::with_timezone("UTC", print(as.POSIXct(x)))
+#'   withr::with_timezone("Europe/Paris", print(as.POSIXct(x)))
+#'   withr::with_timezone("America/New_York", print(as.POSIXct(x)))
+#' }
+#'
+#' # `as_date_time()` will treat Date as naive, which means that the original
+#' # printed date will attempt to be kept wherever possible, no matter the
+#' # time zone. The time will be set to midnight.
+#' as_date_time(x, "UTC")
+#' as_date_time(x, "Europe/Paris")
+#' as_date_time(x, "America/New_York")
+#'
+#' # In some rare cases, this is not possible.
+#' # For example, in Asia/Beirut, there was a DST gap from
+#' # 2021-03-27 23:59:59 -> 2021-03-28 01:00:00,
+#' # skipping the 0th hour entirely.
+#' x <- as.Date("2021-03-28")
+#' try(as_date_time(x, "Asia/Beirut"))
+#'
+#' # To resolve this, set a `nonexistent` time resolution strategy
+#' as_date_time(x, "Asia/Beirut", nonexistent = "roll-forward")
+#'
+#'
+#' # You can also convert to date-time from other clock types
+#' as_date_time(year_month_day(2019, 2, 3, 03), "America/New_York")
+as_date_time <- function(x, ...) {
+  UseMethod("as_date_time")
+}
+
+#' @rdname as_date_time
+#' @export
+as_date_time.POSIXt <- function(x, ...) {
+  check_dots_empty()
+  to_posixct(x)
+}
+
+#' @rdname as_date_time
+#' @export
+as_date_time.Date <- function(x, zone, ..., nonexistent = NULL, ambiguous = NULL) {
+  check_dots_empty()
+  as.POSIXct(as_naive_time(x), tz = zone, nonexistent = nonexistent, ambiguous = ambiguous)
+}
+
+#' @rdname as_date_time
+#' @export
+as_date_time.clock_calendar <- function(x, zone, ..., nonexistent = NULL, ambiguous = NULL) {
+  check_dots_empty()
+  as.POSIXct(x, tz = zone, nonexistent = nonexistent, ambiguous = ambiguous)
+}
+
+#' @rdname as_date_time
+#' @export
+as_date_time.clock_sys_time <- function(x, zone, ...) {
+  check_dots_empty()
+  as.POSIXct(x, tz = zone)
+}
+
+#' @rdname as_date_time
+#' @export
+as_date_time.clock_naive_time <- function(x, zone, ..., nonexistent = NULL, ambiguous = NULL) {
+  check_dots_empty()
+  as.POSIXct(x, tz = zone, nonexistent = nonexistent, ambiguous = ambiguous)
+}
+
+#' @rdname as_date_time
+#' @export
+as_date_time.clock_zoned_time <- function(x, ...) {
+  check_dots_empty()
+  as.POSIXct(x)
+}
+
+# ------------------------------------------------------------------------------
+
 #' Getters: date-time
 #'
 #' @description

R/utils.R

@@ -33,6 +33,18 @@ to_posixct_from_posixlt <- function(x) {
   as.POSIXct.POSIXlt(x)
 }
 
+date_standardize <- function(x) {
+  if (identical(typeof(x), "double")) {
+    return(x)
+  }
+
+  # Convert somewhat rare integer Date to double.
+  # Preserves names.
+  storage.mode(x) <- "double"
+
+  x
+}
+
 # ------------------------------------------------------------------------------
 
 ones_along <- function(x, na_propagate = FALSE) {

_pkgdown.yml

@@ -24,6 +24,8 @@ reference:
   - date_weekday_factor
   - date_month_factor
   - date_leap_year
+  - as_date
+  - as_date_time
   - get_year.Date
   - get_year.POSIXt
   - set_year.Date