Update compiled documentation

DESCRIPTION

@@ -12,5 +12,5 @@ Description: stringr is a set of simple wrappers that make R's string
     matches the input data structures of other functions.
 Depends: plyr
 License: GPL-2
-Collate: 'detect.r' 'dup.r' 'extract.r' 'fixed.r' 'join.r' 'length.r'
-    'locate.r' 'match.r' 'replace.r' 'split.r' 'sub.r'
+Collate: 'checks.r' 'detect.r' 'dup.r' 'extract.r' 'fixed.r' 'join.r'
+    'length.r' 'locate.r' 'match.r' 'replace.r' 'split.r' 'sub.r'

R/join.r

@@ -18,7 +18,7 @@
 #'   NULL, a character vector of length 1.
 #' @keywords character
 #' @seealso \code{\link{paste}} which this function wraps
-#' @alias str_c str_c
+#' @aliases str_c str_join
 #' @examples
 #' str_c("Letter: ", letters)
 #' str_c("Letter", letters, sep = ": ")

man/check_pattern.Rd

@@ -0,0 +1,12 @@
+\name{check_pattern}
+\alias{check_pattern}
+\title{Check that pattern is of the correct type for stringr functions...}
+\usage{check_pattern(pattern)}
+
+\description{
+  Check that pattern is of the correct type for stringr functions
+}
+\keyword{internal}
+\arguments{
+  \item{string}{input vector}
+}

man/check_string.Rd

@@ -0,0 +1,12 @@
+\name{check_string}
+\alias{check_string}
+\title{Check that stringr is of the correct type for stringr functions...}
+\usage{check_string(string)}
+
+\description{
+  Check that stringr is of the correct type for stringr functions
+}
+\keyword{internal}
+\arguments{
+  \item{string}{input vector}
+}

man/invert_match.Rd

@@ -0,0 +1,23 @@
+\name{invert_match}
+\alias{invert_match}
+\title{Invert a matrix of locations...}
+\usage{invert_match(loc)}
+
+\description{
+  Invert a matrix of locations
+}
+
+\details{
+  Invert a matrix of match locations to match the opposite of what was
+  previously matched.
+}
+\value{numeric match giving locations of non-matches}
+\arguments{
+  \item{loc}{matrix of match locations, as from \code{\link{str_locate_all}}}
+}
+\examples{numbers <- "1 and 2 and 4 and 456"
+num_loc <- str_locate_all(numbers, "[0-9]+")[[1]]
+str_sub(numbers, num_loc[, "start"], num_loc[, "end"])
+
+text_loc <- invert_match(num_loc)
+str_sub(numbers, text_loc[, "start"], text_loc[, "end"])}

man/str_join.Rd → man/str_c.Rd

@@ -1,16 +1,27 @@
 \name{str_c}
-\alias{str_c}
 \title{Join multiple strings into a single string.}
 \usage{str_c(..., sep="", collapse)}
 
 \description{
   Join multiple strings into a single string.
 }
+
+\details{
+  To understand how \code{str_c} works, you need to imagine that you
+  are building up a matrix of strings.  Each input argument forms a
+  column, and is expanded to the length of the longest argument, using
+  the usual recyling rules.  The \code{sep} string is inserted between
+  each column. If collapse is \code{NULL} each row is collapsed into a
+  single string.  If non-\code{NULL} that string is inserted at the end
+  of each row, and the entire matrix collapsed to a single string.
+}
 \value{If \code{collapse = NULL} (the default) a character vector with 
 length equal to the longest input string.  If \code{collapse} is non-
 NULL, a character vector of length 1.}
 \keyword{character}
 \seealso{\code{\link{paste}} which this function wraps}
+\alias{str_c}
+\alias{str_join}
 \arguments{
   \item{...}{one or more character vectors.  Zero length arguments 
 are removed}

man/str_detect.Rd

@@ -6,13 +6,19 @@
 \description{
   Detect the presence or absence of a pattern in a string.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} should be a single
+  pattern, i.e. a character vector of length one.
+}
 \value{boolean vector}
 \seealso{\code{\link{grepl}} which this function wraps}
 \keyword{character}
 \arguments{
   \item{string}{input character vector}
-  \item{pattern}{pattern to look for.  See \code{\link{regex}} for
-description.}
+  \item{pattern}{pattern to look for, as defined by a POSIX regular
+expression.  See the ``Extended Regular Expressions'' section of 
+\code{\link{regex}} for details.}
 }
 \examples{fruit <- c("apple", "banana", "pear", "pinapple")
 str_detect(fruit, "a")

man/str_dup.Rd

@@ -1,14 +1,22 @@
 \name{str_dup}
 \alias{str_dup}
-\title{Duplicate strings within a character vector.}
+\title{Duplicate and concatenate strings within a character vector.}
 \usage{str_dup(string, times)}
 
 \description{
-  Duplicate strings within a character vector.
+  Duplicate and concatenate strings within a character vector.
+}
+
+\details{
+  Vectorised over \code{string} and \code{times}.
 }
 \value{character vector}
-\keyword{internal}
+\keyword{character}
 \arguments{
   \item{string}{input character vector}
   \item{times}{number of times to duplicate each string}
 }
+\examples{fruit <- c("apple", "pear", "banana")
+str_dup(fruit, 2)
+str_dup(fruit, 1:3)
+str_c("ba", str_dup("na", 0:5))}

man/str_extract.Rd

@@ -6,13 +6,19 @@
 \description{
   Extract first piece of a string that matches a pattern.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} should be a single
+  pattern, i.e. a character vector of length one.
+}
 \value{character vector.}
 \keyword{character}
 \seealso{\code{\link{str_extract_all}} to extract all matches}
 \arguments{
   \item{string}{input character vector}
-  \item{pattern}{pattern to look for.  See \code{\link{regex}} for
-description.}
+  \item{pattern}{pattern to look for, as defined by a POSIX regular
+expression.  See the ``Extended Regular Expressions'' section of 
+\code{\link{regex}} for details.}
 }
 \examples{shopping_list <- c("apples x4", "flour", "sugar", "milk x2")
 str_extract(shopping_list, "\\\\d")

man/str_extract_all.Rd

@@ -6,13 +6,19 @@
 \description{
   Extract all pieces of a string that match a pattern.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} should be a single
+  pattern, i.e. a character vector of length one.
+}
 \value{list of character vectors.}
 \keyword{character}
 \seealso{\code{\link{str_extract}} to extract the first match}
 \arguments{
   \item{string}{input character vector}
-  \item{pattern}{pattern to look for.  See \code{\link{regex}} for
-description.}
+  \item{pattern}{pattern to look for, as defined by a POSIX regular
+expression.  See the ``Extended Regular Expressions'' section of 
+\code{\link{regex}} for details.}
 }
 \examples{shopping_list <- c("apples x4", "bag of flour", "bag of sugar", "milk x2")
 str_extract_all(shopping_list, "[a-z]+")

man/str_locate.Rd

@@ -6,6 +6,11 @@
 \description{
   Locate the position of the first occurence of a pattern in a string.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} should be a single
+  pattern, i.e. a character vector of length one.
+}
 \value{numeric matrix.  First column gives start postion of match, and
 second column gives end position.}
 \keyword{character}

man/str_locate_all.Rd

@@ -6,6 +6,11 @@
 \description{
   Locate the position of all occurences of a pattern in a string.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} should be a single
+  pattern, i.e. a character vector of length one.
+}
 \keyword{character}
 \value{list of numeric matrices.  First column gives start postion of
 match, and second column gives end position.}
@@ -16,9 +21,10 @@ match, and second column gives end position.}
 \code{\link{str_locate}} to locate position of first match}
 \arguments{
   \item{string}{input character vector}
-  \item{pattern}{pattern to look for.  See \code{\link{regex}} for
-description.}
+  \item{pattern}{pattern to look for, as defined by a POSIX regular
+expression.  See the ``Extended Regular Expressions'' section of 
+\code{\link{regex}} for details.}
 }
-\examples{fruit <- c("apple", "banana", "pear", "pinapple")
+\examples{fruit <- c("apple", "banana", "pear", "pineapple")
 str_locate_all(fruit, "a")
 str_locate_all(fruit, "e")}

man/str_match.Rd

@@ -6,10 +6,18 @@
 \description{
   Extract first matched group from a string.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} should be a single
+  pattern, i.e. a character vector of length one.
+}
 \value{character matrix. First column is the complete match, followed by 
 one for each capture group}
 \keyword{character}
 \arguments{
   \item{string}{input character vector}
-  \item{pattern}{with groups}
+  \item{pattern}{pattern to look for, as defined by a POSIX regular
+expression.  Pattern should contain groups, defined by ().  See the
+``Extended Regular Expressions'' section of \code{\link{regex}} for
+details.}
 }

man/str_match_all.Rd

@@ -6,9 +6,17 @@
 \description{
   Extract all matched groups from a string.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} should be a single
+  pattern, i.e. a character vector of length one.
+}
 \value{list of character matrices, as given by \code{\link{str_match}}}
 \keyword{character}
 \arguments{
   \item{string}{input character vector}
-  \item{pattern}{with groups}
+  \item{pattern}{pattern to look for, as defined by a POSIX regular
+expression.  Pattern should contain groups, defined by ().  See the
+``Extended Regular Expressions'' section of \code{\link{regex}} for
+details.}
 }

man/str_pad.Rd

@@ -6,13 +6,18 @@
 \description{
   Pad a string.
 }
+
+\details{
+  Vectorised over \code{string}.  All other inputs should be of length
+  1.
+}
 \value{character vector}
 \keyword{character}
 \arguments{
   \item{string}{input character vector}
   \item{width}{pad strings to this minimum width}
   \item{side}{side on which padding character is added}
-  \item{pad}{padding character (default is a space)}
+  \item{pad}{single padding character (default is a space)}
 }
 \examples{rbind(
 str_pad("hadley", 30, "left"),

man/str_replace.Rd

@@ -6,13 +6,20 @@
 \description{
   Replace replaced occurences of a matched pattern in a string.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} and \code{replacement}
+  should both be single strings, i.e. a character vectors of length
+  one.
+}
 \value{character vector.}
 \keyword{character}
 \seealso{\code{\link{gsub}} which this function wraps}
 \arguments{
   \item{string}{input character vector}
-  \item{pattern}{pattern to look for.  See \code{\link{regex}} for
-description.}
+  \item{pattern}{pattern to look for, as defined by a POSIX regular
+expression.  See the ``Extended Regular Expressions'' section of 
+\code{\link{regex}} for details.}
   \item{replacement}{replacement string.  References of the form \code{\1}, 
 \code{\2} will be replaced with the contents of the respective matched
 group (created by \code{()}) within the pattern.}

man/str_split.Rd

@@ -6,14 +6,20 @@
 \description{
   Split up a string into a variable number of pieces.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} should be a single
+  pattern, i.e. a character vector of length one.
+}
 \value{a list of character vectors.}
 \keyword{character}
 \seealso{\code{\link{str_split_fixed}} for fixed number of splits}
 \arguments{
   \item{string}{input character vector}
-  \item{pattern}{pattern to split up string by.  See \code{\link{regex}} for
-description.  If \code{NA}, returns original string.  If \code{""} splits
-into individual characters.}
+  \item{pattern}{pattern to split up by, as defined by a POSIX regular
+expression.  See the ``Extended Regular Expressions'' section of 
+\code{\link{regex}} for details. If \code{NA}, returns original string. 
+If \code{""} splits into individual characters.}
   \item{n}{maximum number of pieces to return.  Default (Inf) uses all
 possible split positions.}
 }

man/str_split_fixed.Rd

@@ -6,14 +6,20 @@
 \description{
   Split up a string into a fixed number of pieces.
 }
+
+\details{
+  Vectorised over \code{string}.  \code{pattern} should be a single
+  pattern, i.e. a character vector of length one.
+}
 \value{character matrix with \code{n} columns.}
 \keyword{character}
 \seealso{\code{\link{str_split}} for variable number of splits}
 \arguments{
   \item{string}{input character vector}
-  \item{pattern}{pattern to split up string by.  See \code{\link{regex}} for
-description.  If \code{NA}, returns original string.  If \code{""} splits
-into individual characters.}
+  \item{pattern}{pattern to split up by, as defined by a POSIX regular
+expression.  See the ``Extended Regular Expressions'' section of 
+\code{\link{regex}} for details. If \code{NA}, returns original string. 
+If \code{""} splits into individual characters.}
   \item{n}{number of pieces to return.  Default (Inf) uses all
 possible split positions.  If n is greater than the number of pieces, 
 the result will be padded with empty strings.}