Adjust date specific documentation and tests

Author: DavisVaughan

R/date.R

@@ -983,9 +983,11 @@ date_set_zone.Date <- function(x, zone) {
 #' _`date_parse()` ignores both the `%z` and `%Z` commands,_ as clock treats
 #' Date as a _naive_ type, with a yet-to-be-specified time zone.
 #'
-#' If parsing a string with sub-daily components, such as hours, minutes or
-#' seconds, note that the conversion to Date will round those components to
-#' the nearest day. See the examples for a way to control this.
+#' Parsing strings with sub-daily components, such as hours, minutes, or
+#' seconds, should be done with [date_time_parse()]. If you only need the date
+#' components, round the result to day precision, and then use [as_date()].
+#' Attempting to directly parse a sub-daily string into a Date is ambiguous and
+#' undefined, and is unlikely to work as you might expect.
 #'
 #' @inheritParams zoned-parsing
 #'
@@ -1012,27 +1014,21 @@ date_set_zone.Date <- function(x, zone) {
 #' date_parse("2020-W01-2", format = "%G-W%V-%u")
 #'
 #' # ---------------------------------------------------------------------------
-#' # Rounding of sub-daily components
+#' # Sub-daily components
 #'
-#' # Note that rounding a string with time components will round them to the
-#' # nearest day if you try and parse them
+#' # If you have a string with sub-daily components, but only require the date,
+#' # first parse them as date-times to fully parse the sub-daily components,
+#' # then round using whatever convention is required for your use case before
+#' # converting to date.
 #' x <- c("2019-01-01 11", "2019-01-01 12")
 #'
-#' # Hour 12 rounds up to the next day
-#' date_parse(x, format = "%Y-%m-%d %H")
-#'
-#' # If you don't like this, one option is to just not parse the time component
-#' date_parse(x, format = "%Y-%m-%d")
-#'
-#' # A more general option is to parse the full string as a naive-time,
-#' # then round manually
-#' nt <- naive_time_parse(x, format = "%Y-%m-%d %H", precision = "hour")
-#' nt
+#' x <- date_time_parse(x, zone = "UTC", format = "%Y-%m-%d %H")
+#' x
 #'
-#' nt <- time_point_floor(nt, "day")
-#' nt
+#' date_floor(x, "day")
+#' date_round(x, "day")
 #'
-#' as.Date(nt)
+#' as_date(date_round(x, "day"))
 date_parse <- function(x, ..., format = NULL, locale = clock_locale()) {
   x <- naive_time_parse(x, ..., format = format, precision = "day", locale = locale)
   as.Date(x)

man/date_parse.Rd

@@ -290,16 +290,16 @@ test_that("formatting Dates with `%z` or `%Z` returns NA with a warning", {
 
 test_that("`%z` and `%Z` commands are ignored", {
   expect_identical(
-    date_parse("2019-12-31 11:59:59-0500", format = "%Y-%m-%d %H:%M:%S%z"),
+    date_parse("2019-12-31 -0500", format = "%Y-%m-%d %z"),
     as.Date("2019-12-31")
   )
   expect_identical(
-    date_parse("2019-12-31 11:59:59[America/New_York]", format = "%Y-%m-%d %H:%M:%S[%Z]"),
+    date_parse("2019-12-31 America/New_York", format = "%Y-%m-%d %Z"),
     as.Date("2019-12-31")
   )
 })
 
-test_that("parsing into a date if you requested to parse time components rounds the time (#207)", {
+test_that("parsing into a date if you requested to parse time components rounds the time (#207) (#230) (undocumented)", {
   expect_identical(
     date_parse("2019-12-31 11:59:59", format = "%Y-%m-%d %H:%M:%S"),
     as.Date("2019-12-31")
@@ -310,6 +310,16 @@ test_that("parsing into a date if you requested to parse time components rounds
   )
 })
 
+test_that("parsing fails when undocumented rounding behavior would result in invalid 60 second component (#230) (undocumented)", {
+  expect_identical(
+    expect_warning(
+      date_parse("2019-01-01 01:01:59.550", format = "%Y-%m-%d %H:%M:%6S"),
+      class = "clock_warning_parse_failures"
+    ),
+    new_date(NA_real_)
+  )
+})
+
 test_that("failure to parse throws a warning", {
   expect_warning(date_parse("foo"), class = "clock_warning_parse_failures")
   expect_snapshot(date_parse("foo"))