[R-gregmisc-commits] r2127 - in pkg/gtools: . R man

[noreply at r-forge.r-project.org]

Author: warnes
Date: 2016-04-22 18:10:15 +0200 (Fri, 22 Apr 2016)
New Revision: 2127

Added:
   pkg/gtools/R/capwords.R
   pkg/gtools/man/capwords.Rd
Modified:
   pkg/gtools/NAMESPACE
Log:
Add capwords() function to properly capatilize strings for use in titles

Modified: pkg/gtools/NAMESPACE
===================================================================
--- pkg/gtools/NAMESPACE	2016-04-22 16:08:24 UTC (rev 2126)
+++ pkg/gtools/NAMESPACE	2016-04-22 16:10:15 UTC (rev 2127)
@@ -9,6 +9,7 @@
        assignEdgewise,
        binsearch,
        capture,
+       capwords,
        chr,
        checkRVersion,
        combinations,

Added: pkg/gtools/R/capwords.R
===================================================================
--- pkg/gtools/R/capwords.R	                        (rev 0)
+++ pkg/gtools/R/capwords.R	2016-04-22 16:10:15 UTC (rev 2127)
@@ -0,0 +1,60 @@
+capwords <- function(s, 
+                     strict=FALSE, 
+                     AP=TRUE, 
+                     onlyfirst=FALSE, 
+                     preserveMixed=FALSE, 
+                     sep=" ") 
+{
+  # worker functions
+  cap <- function(s) 
+    paste(toupper(substring(s, 1, 1)),
+          {
+            s <- substring(s, 2); 
+            if(strict) tolower(s) else s
+          },
+          sep = ""
+    )
+  
+  # test if there is a lowercase letter followed by an uppercase letter
+  isMixedCase <- function(s) 
+    grepl("[a-z][A-Z]", s)
+
+  words <- unlist(strsplit(s, split = sep))
+  mixedCaseFlag <- sapply(words, isMixedCase)
+  
+  # First, capitalize *every* word
+  if(!onlyfirst)
+  {
+    newWords <- sapply(words, 
+               cap, 
+               USE.NAMES = !is.null(names(retval))
+               ) 
+    
+    if(preserveMixed==TRUE)
+      newWords[mixedCaseFlag] <- words[mixedCaseFlag]
+    
+    words <- newWords
+  }
+       
+  # Next (optionally) uncapitalize prepositions and conjunctions
+  # recommended by the Associated Press.
+  AP.nocap <- c("a", "an", "and", "at", "but", "by", "for", "in", 
+                "nor", "of", "on", "or", "so", "the", "to", "up", 
+                "yet")
+  
+  if(AP && !onlyfirst) 
+    for(word in AP.nocap)
+      words <- gsub(paste0("^",word,"$"), 
+                            word, 
+                            words, 
+                            ignore.case=TRUE)
+                
+  
+  # Finally, ensure that the first word is capitalized
+  if(length(words)>0 && mixedCaseFlag[1]==FALSE)
+    words[1] <- cap(words[1])
+  
+  retval <- paste(words, collapse=sep)
+  
+  retval
+}
\ No newline at end of file

Added: pkg/gtools/man/capwords.Rd
===================================================================
--- pkg/gtools/man/capwords.Rd	                        (rev 0)
+++ pkg/gtools/man/capwords.Rd	2016-04-22 16:10:15 UTC (rev 2127)
@@ -0,0 +1,57 @@
+\name{capwords}
+\alias{capwords}
+\title{
+Capitalize Words for Titles
+}
+\description{
+This function capitalizes words for use in titles
+}
+\usage{
+capwords(s, strict=FALSE, AP=TRUE, firstonly=FALSE, 
+         preserveMixed=FALSE, sep=" ")
+}
+\arguments{
+  \item{s}{character string to be processed}
+  \item{strict}{Logical, remove all additional capitalization}
+  \item{AP}{Logical, apply the Associated Press (AP) rules for
+    prepositions and conjunctions that should not be capitalized
+    in titles.}
+  \item{preserveMixed}{Logical, preserve the capitalization
+    mixed-case words containing an upper-case letter after a 
+    lower-case letter.}
+}
+\details{
+This function separates the provided character string into separate words using \code{sep} as the word separator.  If \code{firstonly==TRUE}, it then capitalizes the first letter the first word, otherwise (the default), it capitalizes the first letter of every word.  If \code{AP==TRUE}, it then un-capitalizes words in the Associated Press's (AP) list of prepositions and conjunctions should not be capitalized in titles.  Next, it capitalizes the first word. It then re-joins the words using the specified separator.
+
+If \code{preserveMixed==TRUE}, words with an upper-case letter appearing after a lower-case letter will not be changed (e.g. "iDevice").
+}
+\value{
+A character scalar containing the capitalized words.
+}
+\references{
+Fogarty, Mignon. “Capitalizing Titles: Which words should you capitalize?” Grammar Girl's Quick and Dirty Tips for Better Writing. 9 Jun. 2011. Quick and Dirty Tips Website. Accessed 22 April 2016 \url{http://www.quickanddirtytips.com/education/grammar/capitalizing-titles}
+}
+\author{
+Gregory R. Warnes \email{greg at warnes.net} based on code from the \code{\link[base]{chartr}} manual page, 
+and \code{\link[taxize]{capwords}}
+in the taxize package.
+}
+\seealso{
+\code{\link[base]{chartr}},
+\code{\link[taxize]{capwords}},
+\code{\link[SGP]{capwords}}
+}
+\examples{
+capwords("a function to capitalize words in a title")
+capwords("a function to capitalize words in a title", AP=FALSE)
+
+capwords("testing the iProduct for defects")
+capwords("testing the iProduct for defects", strict=TRUE)
+capwords("testing the iProduct for defects", onlyfirst=TRUE)
+capwords("testing the iProduct for defects", preserveMixed=TRUE)
+
+capwords("title_using_underscores_as_separators", sep="_")
+
+}
+\keyword{utilites}
+\keyword{character}