Adjust date-time specific documentation

Author: DavisVaughan

R/posixt.R

@@ -1164,9 +1164,16 @@ date_set_zone.POSIXt <- function(x, zone) {
 #' `NA`s, or completely fails to parse, then no time zone will be able to be
 #' determined. In that case, the result will use `"UTC"`.
 #'
-#' If manually parsing sub-second components, be aware that they will be
-#' automatically rounded to the nearest second when converting them to POSIXct.
-#' See the examples for a way to control this.
+#' If you have strings with sub-second components, then these date-time parsers
+#' are not appropriate for you. Remember that clock treats POSIXct as a second
+#' precision type, so parsing a string with fractional seconds directly into a
+#' POSIXct is ambiguous and undefined. Instead, fully parse the string,
+#' including its fractional seconds, into a clock type that can handle it, such
+#' as a naive-time with [naive_time_parse()], then round to seconds with
+#' whatever rounding convention is appropriate for your use case, such as
+#' [time_point_floor()], and finally convert that to POSIXct with
+#' [as_date_time()]. This gives you complete control over how the fractional
+#' seconds are handled when converting to POSIXct.
 #'
 #' @inheritParams zoned-parsing
 #' @inheritParams as-zoned-time-naive-time
@@ -1223,28 +1230,21 @@ date_set_zone.POSIXt <- function(x, zone) {
 #' date_time_parse_abbrev(abbrev_times, "America/New_York")
 #'
 #' # ---------------------------------------------------------------------------
-#' # Rounding of sub-second components
+#' # Sub-second components
 #'
-#' # Generally, if you have a string with sub-second components, they will
-#' # be ignored when parsing into a date-time
-#' x <- c("2019-01-01 00:00:01.1", "2019-01-01 00:00:01.7")
+#' # If you have a string with sub-second components, but only require up to
+#' # seconds, first parse them into a clock type that can handle sub-seconds to
+#' # fully capture that information, then round using whatever convention is
+#' # required for your use case before converting to a date-time.
+#' x <- c("2019-01-01 00:00:01.1", "2019-01-01 00:00:01.78")
 #'
-#' date_time_parse(x, "America/New_York")
-#'
-#' # If you manually try and parse those sub-second components with `%4S` to
-#' # read the 2 seconds, 1 decimal point, and 1 fractional component, the
-#' # fractional component will be rounded to the nearest second
-#' date_time_parse(x, "America/New_York", format = "%Y-%m-%d %H:%M:%4S")
-#'
-#' # If you don't like this, parse the full string as a naive-time,
-#' # then round manually and convert to a POSIXct
-#' nt <- naive_time_parse(x, format = "%Y-%m-%d %H:%M:%S", precision = "millisecond")
-#' nt
+#' x <- naive_time_parse(x, precision = "millisecond")
+#' x
 #'
-#' nt <- time_point_floor(nt, "second")
-#' nt
+#' time_point_floor(x, "second")
+#' time_point_round(x, "second")
 #'
-#' as.POSIXct(nt, "America/New_York")
+#' as_date_time(time_point_round(x, "second"), "America/New_York")
 NULL
 
 #' @rdname date-time-parse