match                  package:base                  R Documentation

_V_a_l_u_e _M_a_t_c_h_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

     `match' returns a vector of the positions of (first) matches of
     its first argument in its second.

     `%in%' is a more intuitive interface as a binary operator, which
     returns a logical vector indicating if there is a match or not for
     its left operand.

_U_s_a_g_e:

     match(x, table, nomatch = NA, incomparables = FALSE)
     x %in% table

_A_r_g_u_m_e_n_t_s:

       x: the values to be matched.

   table: the values to be matched against.

 nomatch: the value to be returned in the case when no match is found.

incomparables: a vector of values that cannot be matched.  Any value in
          `x' matching a value in this vector is assigned the `nomatch'
          value.  Currently, `FALSE' is the only possible value,
          meaning that all values can be matched.

_D_e_t_a_i_l_s:

     `%in%' is currently defined as 
     `"%in%" <- function(x, table) match(x, table, nomatch = 0) > 0'

     Factors are converted to character vectors, and then `x' and
     `table' are coerced to a common type (the later of the two types
     in R's ordering, logical < integer < numeric < complex <
     character) before matching.

_V_a_l_u_e:

     In both cases, a vector of the same length as `x'.

     `match': A numeric vector giving the position in `table' of the
     first match if there is a match, otherwise `nomatch'.

     If `x[i]' is found to equal `table[j]' then the value returned in
     the `i'-th position of the return value is `j', for the smallest
     possible `j'.  If no match is found, the value is `nomatch'.

     `%in%': A logical vector, indicating if a match was located for
     each element of `x'.

_S_e_e _A_l_s_o:

     `pmatch' and `charmatch' for (partial) string matching,
     `match.arg', etc for function argument matching.

     `is.element' for an S-compatible equivalent of `%in%'.

_E_x_a_m_p_l_e_s:

     ## The intersection of two sets :
     intersect <- function(x, y) y[match(x, y, nomatch = 0)]
     intersect(1:10,7:20)

     1:10 %in% c(1,3,5,9)
     sstr <- c("c","ab","B","bba","c","@","bla","a","Ba","%")
     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)

