update docs and code

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"]]

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
       "("

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

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.}

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