From 1f364b19123dbf0d86a0b1c54fea71b17096178a Mon Sep 17 00:00:00 2001
From: Toby Dylan Hocking <toby.dylan.hocking@usherbrooke.ca>
Date: Tue, 17 Dec 2024 08:54:35 -0500
Subject: [PATCH] update docs and code

---
 R/capture_first_vec.R    |  8 ++++++--
 R/var_args_list.R        | 15 ++++++++++-----
 man/capture_first_vec.Rd |  8 ++++++--
 man/subject_var_args.Rd  |  3 +--
 man/var_args_list.Rd     |  8 ++++++--
 5 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/R/capture_first_vec.R b/R/capture_first_vec.R
index 80d5dc3..f19e3fe 100644
--- a/R/capture_first_vec.R
+++ b/R/capture_first_vec.R
@@ -29,8 +29,12 @@ capture_first_vec <- structure(function # Capture first match in each character
   engine=getOption("nc.engine", "PCRE"),
 ### character string, one of PCRE, ICU, RE2
   type.convert=getOption("nc.type.convert", FALSE)
-### If TRUE, use utils::type.convert instead of base::identity for the
-### default conversion.
+### Default conversion function, which will be used on each capture
+### group, unless a specific conversion is specified for that
+### group. If TRUE, use utils::type.convert; if FALSE, use
+### base::identity; otherwise must be a function of at least one
+### argument (character), returning an atomic vector of the same
+### length.
 ){
   L <- subject_var_args(..., type.convert=type.convert)
   subject.vec <- L[["subject"]]
diff --git a/R/var_args_list.R b/R/var_args_list.R
index 4c01dca..989ac12 100644
--- a/R/var_args_list.R
+++ b/R/var_args_list.R
@@ -3,8 +3,7 @@ subject_var_args <- function
 (...,
 ### subject, regex/conversion.
   type.convert=getOption("nc.type.convert", FALSE)
-### If TRUE, use utils::type.convert instead of base::identity for the
-### default conversion.
+### passed to var_args_list.
 ){
   all.arg.list <- list(...)
   first.name <- names(all.arg.list[1])
@@ -36,8 +35,12 @@ var_args_list <- structure(function
 ### pattern. Patterns may also be lists, which are parsed recursively
 ### for convenience.
   type.convert=getOption("nc.type.convert", FALSE)
-### If TRUE, use utils::type.convert instead of base::identity for the
-### default conversion.
+### Default conversion function, which will be used on each capture
+### group, unless a specific conversion is specified for that
+### group. If TRUE, use utils::type.convert; if FALSE, use
+### base::identity; otherwise must be a function of at least one
+### argument (character), returning an atomic vector of the same
+### length.
 ){
   var.arg.list <- list(...)
   fun.list <- list()
@@ -58,7 +61,9 @@ var_args_list <- structure(function
       group.i <- length(fun.list)+1L
       fun.list[[group.i]] <- if(isTRUE(type.convert)){
         function(x)utils::type.convert(x,as.is=TRUE)
-      }else identity
+      }else if(isFALSE(type.convert)){
+        identity
+      }else type.convert
       names(fun.list)[[group.i]] <- pattern.name
       has.name <- TRUE
       "("
diff --git a/man/capture_first_vec.Rd b/man/capture_first_vec.Rd
index 94eaa75..49df928 100644
--- a/man/capture_first_vec.Rd
+++ b/man/capture_first_vec.Rd
@@ -34,8 +34,12 @@ recursively using these rules.}
 match; otherwise subjects that do not match are reported as
 missing/NA rows of the result.}
   \item{engine}{character string, one of PCRE, ICU, RE2}
-  \item{type.convert}{If TRUE, use \code{\link[utils]{type.convert}} instead of \code{\link[base]{identity}} for the
-default conversion.}
+  \item{type.convert}{Default conversion function, which will be used on each capture
+\code{\link{group}}, unless a specific conversion is specified for that
+\code{\link{group}}. If TRUE, use \code{\link[utils]{type.convert}}; if FALSE, use
+\code{\link[base]{identity}}; otherwise must be a function of at least one
+argument (character), returning an atomic vector of the same
+length.}
 }
 
 \value{data.table with one row for each subject, and one column for each
diff --git a/man/subject_var_args.Rd b/man/subject_var_args.Rd
index a78378d..10a8eb6 100644
--- a/man/subject_var_args.Rd
+++ b/man/subject_var_args.Rd
@@ -7,8 +7,7 @@
         FALSE))}
 \arguments{
   \item{\dots}{subject, regex/conversion.}
-  \item{type.convert}{If TRUE, use \code{\link[utils]{type.convert}} instead of \code{\link[base]{identity}} for the
-default conversion.}
+  \item{type.convert}{passed to \code{\link{var_args_list}}.}
 }
 
 \value{Result of \code{\link{var_args_list}} plus subject.}
diff --git a/man/var_args_list.Rd b/man/var_args_list.Rd
index a98dabd..ec833e4 100644
--- a/man/var_args_list.Rd
+++ b/man/var_args_list.Rd
@@ -17,8 +17,12 @@ pattern used for matching. Each named pattern may be followed by
 at most one function which is used to convert the previous named
 pattern. Patterns may also be lists, which are parsed recursively
 for convenience.}
-  \item{type.convert}{If TRUE, use \code{\link[utils]{type.convert}} instead of \code{\link[base]{identity}} for the
-default conversion.}
+  \item{type.convert}{Default conversion function, which will be used on each capture
+\code{\link{group}}, unless a specific conversion is specified for that
+\code{\link{group}}. If TRUE, use \code{\link[utils]{type.convert}}; if FALSE, use
+\code{\link[base]{identity}}; otherwise must be a function of at least one
+argument (character), returning an atomic vector of the same
+length.}
 }
 
 \value{a list with two named elements