mv & unhide %notin% from {tools} to {base}

git-svn-id: https://svn.r-project.org/R/trunk@89099 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: maechler

doc/NEWS.Rd

@@ -141,6 +141,12 @@
       \code{tools::Rd2txt_options(descStyle=NULL)} to get the old
       behaviour with a simple space; a \code{"colon"} variant is also
       available.
+
+      \item \code{x \%notin\% table} newly in \pkg{base} is an idiom
+      for \code{!(x \%in\% table)} and provided almost entirely for
+      convenience and code readability, from an R-devel suggestion, after
+      many years of private definitions mostly hidden in packages,
+      including in \R's \pkg{tools} package.
     }
   }
 

src/library/base/R/match.R

@@ -36,7 +36,8 @@ pmatch <- function(x, table, nomatch = NA_integer_, duplicates.ok = FALSE)
 
 # "utils::hasName(x, name)" is defined to be the same as "name %in% names(x)",
 # so change it if this changes.
-`%in%`  <- function(x, table) match(x, table, nomatch = 0L) > 0L
+`%in%`    <- function(x, table) match(x, table, nomatch = 0L) > 0L
+`%notin%` <- function(x, table) match(x, table, nomatch = 0L) == 0L
 
 match.arg <- function (arg, choices, several.ok = FALSE)
 {

src/library/base/man/match.Rd

@@ -4,21 +4,23 @@
 % Distributed under GPL 2 or later
 
 \name{match}
+\title{Value Matching}
 \alias{match}
 \alias{\%in\%}
-\title{Value Matching}
+\alias{\%notin\%}
 \description{
   \code{match} returns a vector of the positions of (first) matches of
   its first argument in its second.
 
-  \code{\%in\%} is a more intuitive interface as a binary operator,
-  which returns a logical vector indicating if there is a match or not
+  \code{\%in\%} and \code{\%notin\%} are more intuitive interfaces as binary operators,
+  returning a logical vector indicating if there is a match or not
   for its left operand.
 }
 \usage{
 match(x, table, nomatch = NA_integer_, incomparables = NULL)
 
-x \%in\% table
+x  \%in\%   table
+x \%notin\% table
 }
 \arguments{
   \item{x}{vector or \code{NULL}: the values to be matched.
@@ -35,21 +37,30 @@ x \%in\% table
 \value{
   A vector of the same length as \code{x}.
 
-  \code{match}: An integer vector giving the position in \code{table} of
+ \describe{
+    \item{\code{match}:}{An integer vector giving the position in \code{table} of
   the first match if there is a match, otherwise \code{nomatch}.
 
   If \code{x[i]} is found to equal \code{table[j]} then the value
   returned in the \code{i}-th position of the return value is \code{j},
   for the smallest possible \code{j}.  If no match is found, the value
   is \code{nomatch}.
-
-  \code{\%in\%}: A logical vector, indicating if a match was located for
-  each element of \code{x}: thus the values are \code{TRUE} or
-  \code{FALSE} and never \code{NA}.
+  }
+  \item{\code{\%in\%}:}{A logical vector, indicating if a match was located for
+    each element of \code{x}: thus the values are \code{TRUE} or
+    \code{FALSE} and never \code{NA}.}
+
+  \item{\code{\%notin\%}:}{A logical vector, simply the negation of the
+    corresponding \code{\%in\%} call.}
+  }
 }
 \details{
   \code{\%in\%} is currently defined as \cr
-  \code{"\%in\%" <- function(x, table) match(x, table, nomatch = 0) > 0}
+  \code{`\%in\%` <- function(x, table) match(x, table, nomatch = 0L) > 0L}
+
+  \code{\%notin\%} could succinctly be defined as \code{\link{Negate}(`\%in\%`)},
+  but for symmetry and efficiency is \cr
+  \code{`\%notin\%` <- function(x, table) match(x, table, nomatch = 0L) == 0L}
 
   Factors, raw vectors and lists are converted to character vectors,
   internally classed objects are transformed via \code{\link{mtfrm}}, and
@@ -79,7 +90,8 @@ x \%in\% table
   in different encodings but would agree when translated to UTF-8 (see
   \code{\link{Encoding}}).
 
-  That \code{\%in\%} never returns \code{NA} makes it particularly
+  That \code{\%in\%} and \code{\%notin\%} never return \code{NA} makes them
+  particularly
   useful in \code{if} conditions.
 }
 \references{
@@ -107,16 +119,16 @@ x \%in\% table
 intersect # the R function in base is slightly more careful
 intersect(1:10, 7:20)
 
-1:10 \%in\% c(1,3,5,9)
+1:10 \%in\% c(1,3,5,9) %
 sstr <- c("c","ab","B","bba","c",NA,"@","bla","a","Ba","\%")
-sstr[sstr \%in\% c(letters, LETTERS)]
+sstr[sstr \%in\% c(letters, LETTERS)] %
 
-"\%w/o\%" <- function(x, y) x[!x \%in\% y] #--  x without y
-(1:10) \%w/o\% c(3,7,12)
+"\%w/o\%" <- function(x, y) x[x \%notin\% y] #--  x without y
+(1:10) \%w/o\% c(3,7,12) %
 ## Note that setdiff() is very similar and typically makes more sense:
         c(1:6,7:2) \%w/o\% c(3,7,12)  # -> keeps duplicates
 setdiff(c(1:6,7:2),      c(3,7,12)) # -> unique values
-
+%
 ## Illuminating example about NA matching in complex values
 r <- c(1, NA, NaN)
 zN <- c(complex(real = NA , imaginary =  r ),

src/library/tools/R/utils.R

@@ -593,18 +593,13 @@ filtergrep <-
 function(pattern, x, ...)
     grep(pattern, x, invert = TRUE, value = TRUE, ...)
 
-### ** %notin%
-
-`%notin%` <-
-function(x, y)
-    is.na(match(x, y))
 
 ### ** %w/o%
 
 ## x without y, as in the examples of ?match.
 `%w/o%` <-
 function(x, y)
-    x[is.na(match(x, y))]
+    x[x %notin% y]
 
 ### ** .OStype
 
@@ -903,7 +898,7 @@ function(funnames, pkgnames = character(), colons = c("::", ":::"))
     ## Use pkgnames = NA_character_ to match *any* PKG::FUN call with
     ## FUN in funnames.  Strange but why not?  Or better to use "*"?
     function(e) {
-        (is.call(e) &&        
+        (is.call(e) &&
          ((is.name(x <- e[[1L]]) &&
            as.character(x) %in% funnames)) ||
          ((is.call(x <- e[[1L]]) &&