documenting parse_iso8601_as_timespan (#29)

DESCRIPTION

@@ -33,4 +33,4 @@ Suggests:
     rmarkdown
 VignetteBuilder: knitr
 Roxygen: list(markdown = TRUE)
-URL: https://dgkf.github.io/parttime
+URL: https://dgkf.github.io/parttime/, https://github.com/dgkf/parttime

R/class_partial_time_compat_lubridate.R

@@ -136,7 +136,7 @@ tz <- function(x) UseMethod("tz")
 year.partial_time <- gen_get_field_fn("year")
 
 #' @rdname parttime_access_and_assign
-#' @usage \\method{year}{partial_time}(x) <- value
+#' @usage \method{year}{partial_time}(x) <- value
 #' @export
 `year<-.partial_time` <- gen_set_field_fn("year")
 
@@ -157,7 +157,7 @@ methods::setMethod(
 month.partial_time <- gen_get_field_fn("month")
 
 #' @rdname parttime_access_and_assign
-#' @usage \\method{month}{partial_time}(x) <- value
+#' @usage \method{month}{partial_time}(x) <- value
 #' @export
 `month<-.partial_time` <- gen_set_field_fn("month")
 
@@ -178,7 +178,7 @@ methods::setMethod(
 mday.partial_time <- gen_get_field_fn("day")
 
 #' @rdname parttime_access_and_assign
-#' @usage \\method{day}{partial_time}(x) <- value
+#' @usage \method{day}{partial_time}(x) <- value
 #' @export
 `day<-.partial_time` <- gen_set_field_fn("day")
 
@@ -199,7 +199,7 @@ methods::setMethod(
 hour.partial_time <- gen_get_field_fn("hour")
 
 #' @rdname parttime_access_and_assign
-#' @usage \\method{hour}{partial_time}(x) <- value
+#' @usage \method{hour}{partial_time}(x) <- value
 #' @export
 `hour<-.partial_time` <- gen_set_field_fn("hour")
 
@@ -220,7 +220,7 @@ methods::setMethod(
 minute.partial_time <- gen_get_field_fn("min")
 
 #' @rdname parttime_access_and_assign
-#' @usage \\method{minute}{partial_time}(x) <- value
+#' @usage \method{minute}{partial_time}(x) <- value
 #' @export
 `minute<-.partial_time` <- gen_set_field_fn("min")
 
@@ -243,7 +243,7 @@ second.partial_time <- function(x) {
 }
 
 #' @rdname parttime_access_and_assign
-#' @usage \\method{second}{partial_time}(x) <- value
+#' @usage \method{second}{partial_time}(x) <- value
 #' @export
 `second<-.partial_time` <- function(x, value) {
   sec <- trunc(value)
@@ -272,7 +272,7 @@ tz.partial_time <- function(x) {
 }
 
 #' @rdname parttime_access_and_assign
-#' @usage \\method{tz}{partial_time}(x) <- value
+#' @usage \method{tz}{partial_time}(x) <- value
 #' @export
 `tz<-.partial_time` <- function(x, value) {
   set_field(x, c("tzhour", "tzmin"), cbind(tzhour = value %/% 60, tzmin = value %% 60))

R/parse_iso8601.R

@@ -1,6 +1,7 @@
 #' slightly modified from parsedate - added 'secfrac' capture group
 #'
 #' @keywords internal
+#'
 re_iso8601 <- paste0(
   "^\\s*",
   "(?<year>[\\+-]?\\d{4}(?!\\d{2}\\b))",
@@ -74,6 +75,16 @@ parse_iso8601 <- function(x, warn = TRUE, ...) {
 }
 
 
+
+#' Parse iso8601 datetime strings as timespan array
+#'
+#' @note A timespan array is an internal data structure used as the backend
+#' representation of timespan objects. It consists of two parttime-like matrices
+#' (with the addition of an "inclusive" column), one for the lower- and
+#' upper-bounds of the timespan. Collectively, this amounts to a three
+#' dimensional array.
+#'
+#' @inheritParams parse_iso8601
 #'
 #' @keywords internal
 #' @rdname parse_timespan
@@ -144,40 +155,80 @@ parse_iso8601_matrix <- function(dates) {
   match_m
 }
 
+
+
+#' Inspecting and manipulating intermediate iso8601 matrices
+#'
+#' An "iso8601 matrix" is a matrix of the various capture groups extraced from a
+#' an iso8601 datetime string. These groups represent a superset of the fields
+#' used by partial time objects, including representation for less common
+#' datetime formats like yeardays, yearweeks or weekdays. Because the standard
+#' provides a number of different combinations of fields that represent valid
+#' strings, these functions serves to provide convenience functions for testing
+#' or manipulating these less canonical representations.
+#'
+#' @param x A \code{numeric} matrix of possible iso8601 fields
+#' @param fields A \code{character} vector of fields
+#'
+#' @section is_iso8601_* functions:
+#' Test whether rows of the matrix represent a specific form, as evident by
+#' non-missing values in specific fields.
+#'
+#' @keywords internal
+#'
+#' @name parse_iso8601_helpers
+#' @rdname parse_iso8601_helpers
+#'
 is_iso8601_form <- function(x, fields) {
   apply(!is.na(x[, fields, drop = FALSE]), 1, all)
 }
 
+#' @keywords internal
+#' @rdname parse_iso8601_helpers
 is_iso8601_weekday <- function(x) {
   is_iso8601_form(x, c("year", "week", "weekday"))
 }
 
+#' @keywords internal
+#' @rdname parse_iso8601_helpers
 is_iso8601_yearday <- function(x) {
   is_iso8601_form(x, c("year", "yearday"))
 }
 
+#' @keywords internal
+#' @rdname parse_iso8601_helpers
 is_iso8601_minfrac <- function(x) {
   is_iso8601_form(x, "frac")
 }
 
+#' @section recalc_* functions:
+#' Calculate canonical datetime fields from alternative representations
+#'
+#' @keywords internal
+#' @rdname parse_iso8601_helpers
+#'
 recalc_md_from_weekday <- function(x) {
   dates <- strptime(
-    paste(x[,"year"], x[,"week"], x[,"weekday"] - 1L, sep = "-"),
+    paste(x[, "year"], x[, "week"], x[, "weekday"] - 1L, sep = "-"),
     format = "%Y-%U-%w"
   )
 
   cbind(month = dates$mon + 1L, day = dates$mday)
 }
 
+#' @keywords internal
+#' @rdname parse_iso8601_helpers
 recalc_md_from_yearday <- function(x) {
   dates <- strptime(
-    paste(x[,"year"], x[,"yearday"], sep = "-"),
+    paste(x[, "year"], x[, "yearday"], sep = "-"),
     format = "%Y-%j"
   )
 
   cbind(month = dates$mon + 1L, day = dates$mday)
 }
 
+#' @keywords internal
+#' @rdname parse_iso8601_helpers
 recalc_sec_from_minfrac <- function(x) {
   cbind(sec = (x[, "frac"] * 60) %/% 1, secfrac = (x[, "frac"] * 60) %% 1)
 }

README.Rmd

@@ -12,9 +12,9 @@ knitr::opts_chunk$set(collapse = TRUE)
 # parttime
 
 <!-- badges: start -->
-[![status](https://img.shields.io/static/v1?label=status&message=experimental&color=red)]()
+[![status](https://img.shields.io/static/v1?label=status&message=developing&color=orange)]()
 [![R-CMD-check](https://github.com/dgkf/parttime/workflows/R-CMD-check/badge.svg)](https://github.com/dgkf/parttime/actions)
-[![Coverage](https://codecov.io/gh/dgkf/parttime/branch/master/graph/badge.svg)](https://app.codecov.io/gh/dgkf/parttime?branch=master)
+[![Coverage](https://codecov.io/gh/dgkf/parttime/branch/main/graph/badge.svg)](https://app.codecov.io/gh/dgkf/parttime?branch=main)
 <!-- badges: end -->
 
 A package for a partial datetime class and generics

README.md

@@ -3,9 +3,9 @@
 
 <!-- badges: start -->
 
-[![status](https://img.shields.io/static/v1?label=status&message=experimental&color=red)]()
+[![status](https://img.shields.io/static/v1?label=status&message=developing&color=orange)]()
 [![R-CMD-check](https://github.com/dgkf/parttime/workflows/R-CMD-check/badge.svg)](https://github.com/dgkf/parttime/actions)
-[![Coverage](https://codecov.io/gh/dgkf/parttime/branch/master/graph/badge.svg)](https://app.codecov.io/gh/dgkf/parttime?branch=master)
+[![Coverage](https://codecov.io/gh/dgkf/parttime/branch/main/graph/badge.svg)](https://app.codecov.io/gh/dgkf/parttime?branch=main)
 <!-- badges: end -->
 
 A package for a partial datetime class and generics
@@ -163,10 +163,13 @@ iso8601_dates <- c(
 )
 
 as.parttime(iso8601_dates)
+## Warning in warn_repr_data_loss(x, includes = "week", excludes = "weekday"):   Date strings including week and excluding weekday can not be fully
+## represented. To avoid loss of datetime resolution, such partial dates
+## are best represented as timespans. See `?timespan`.
 ## <partial_time<YMDhms+tz>[15]> 
 ##  [1] NA                             "2001"                        
 ##  [3] "2002-01-01"                   "2004-09-01"                  
-##  [5] "2005"                         "2006-01-13"                  
+##  [5] "2005"                         "2006-01-12"                  
 ##  [7] "2007-10-01 08"                "2008-09-20 08:35"            
 ##  [9] "2009-08-12 08:35:02.880"      "2010-07-22 08:35:32.000"     
 ## [11] "2011-06-13 08:35:32.123"      "2012-05-23 08:35:32.123"     
@@ -253,6 +256,9 @@ tibble(dates = iso8601_dates) %>%
     parttimes = as.parttime(dates),
     imputed_times = impute_time_min(parttimes)
   )
+## Warning in warn_repr_data_loss(x, includes = "week", excludes = "weekday"):   Date strings including week and excluding weekday can not be fully
+## represented. To avoid loss of datetime resolution, such partial dates
+## are best represented as timespans. See `?timespan`.
 ## # A tibble: 15 × 3
 ##    dates               parttimes                    imputed_times               
 ##    <chr>               <pttm>                       <pttm>                      
@@ -261,7 +267,7 @@ tibble(dates = iso8601_dates) %>%
 ##  3 2002-01-01          2002-01-01                   2002-01-01 00:00:00.000-1200
 ##  4 2004-245            2004-09-01                   2004-09-01 00:00:00.000-1200
 ##  5 2005-W13            2005                         2005-01-01 00:00:00.000-1200
-##  6 2006-W02-5          2006-01-13                   2006-01-13 00:00:00.000-1200
+##  6 2006-W02-5          2006-01-12                   2006-01-12 00:00:00.000-1200
 ##  7 2007-10-01T08       2007-10-01 08                2007-10-01 08:00:00.000-1200
 ##  8 2008-09-20T08:35    2008-09-20 08:35             2008-09-20 08:35:00.000-1200
 ##  9 2009-08-12T08:35.0… 2009-08-12 08:35:02.880      2009-08-12 08:35:02.880-1200