\HeaderA{strutils}{Low-level string utilities}{strutils}
\aliasA{safeExplode}{strutils}{safeExplode}
\aliasA{strsplitAsListOfIntegerVectors}{strutils}{strsplitAsListOfIntegerVectors}
\aliasA{svn.time}{strutils}{svn.time}
\keyword{utilities}{strutils}
\begin{Description}\relax
Some low-level string utilities that operate on ordinary
character vectors. For more advanced string manipulations,
see the Biostrings package.
\end{Description}
\begin{Usage}
\begin{verbatim}
  strsplitAsListOfIntegerVectors(x, sep=",")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A character vector where each element is a string containing
comma-separated decimal integer values.

\item[\code{sep}] The value separator character.

\end{ldescription}
\end{Arguments}
\begin{Value}
A list of integer vectors. The list is of the same length as the input.
\end{Value}
\begin{Note}\relax
\code{strsplitAsListOfIntegerVectors} is similar to the
\code{strsplitAsListOfIntegerVectors2} function shown in the
Examples section below, except that the former generally raises
an error where the latter would have inserted an \code{NA} in
the returned object. More precisely:
\Itemize{
\item The latter accepts NAs in the input,
the former doesn't (raises an error).
\item The latter introduces NAs by coercion (with a warning),
the former doesn't (raises an error).
\item The latter supports "inaccurate integer conversion in coercion"
when the value to coerce is > INT_MAX (then it's coerced to INT_MAX),
the former doesn't (raises an error).
\item The latter coerces non-integer values (e.g. 10.3) to an
int by truncating them, the former doesn't (raises an error).
}
When it fails, \code{strsplitAsListOfIntegerVectors} will print
an informative error message.
Finally, \code{strsplitAsListOfIntegerVectors} is faster and uses
much less memory than \code{strsplitAsListOfIntegerVectors2}.
\end{Note}
\begin{Author}\relax
H. Pages
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{strsplit}{strsplit}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  x <- c("1116,0,-19",
         " +55291 , 2476,",
         "19184,4269,5659,6470,6721,7469,14601",
         "7778889, 426900, -4833,5659,6470,6721,7096",
         "19184 , -99999")
  y <- strsplitAsListOfIntegerVectors(x)
  y

  ## In normal situations (i.e. when the input is well-formed),
  ## strsplitAsListOfIntegerVectors() does actually the same as the
  ## function below but is faster and much more memory efficient:
  strsplitAsListOfIntegerVectors2 <- function(x, sep=",")
  {
    tmp <- strsplit(x, sep, fixed = TRUE)
    lapply(tmp, as.integer)
  }
  y2 <- strsplitAsListOfIntegerVectors2(x)
  stopifnot(identical(y, y2))
\end{ExampleCode}
\end{Examples}

