Contents

match()

Usage:

match(x,Target [,nomatch, exact:F or fuzz:d, ignorecase:T]), x REAL,
  LOGICAL or CHARACTER, Target a variable of the same type as x, nomatch
  and d >= 0 REAL scalars; x and Target can't both be nonvectors

Keywords: ordering, variables, character variables

match(x,Target,noMatch), where x is REAL, LOGICAL or CHARACTER and
noMatch is a REAL scalar, attempts to match each element of array x with
each element of vector Target.  Target must be the same type as x.  The
result is REAL with the same dimensions as x.  When x is REAL or
LOGICAL, it is an error for Target to contain any MISSING values.

Let J represent the subscripts of an element of x.  Then result[J] has
value noMatch, when no element of Target matches x[J], and has value k
when Target[k] is the first value with Target[k] = x[J].  When x is REAL
and x[J] is MISSING, then result[J] is MISSING.

match(x,Target) does the same except that length(Target) + 1 is used as
a value for noMatch and, when there are any non-matching elements, an
advisory message is printed.

When x is a vector, Target can be a matrix or array and the matching is
done for each combination of the second and higher dimension of Target.
The result has dimensions vector(length(x), dims(Target)[-1]).  In this
case, when noMatch is omitted, the value for non-matching elements is
dim(Target)[1] + 1.

@inexact_matching
match(x,Target [,noMatch], fuzz:d), where x is REAL and d >= 0 is a
non-MISSING REAL scalar, does the same, except the match that x[J]
matches Target[k] when abs(x[J] - Target[k]) <= d.

match(x,Target [,noMatch], ignorecase:T) ignores the case, upper or
lower, of any alphabetic characters in elements of CHARACTER variables x
and A.  For example, match("AbC",vector("xYz","abc","def"),
ignorecase:T) has value 2.

match(Pattern,Target [,noMatch], exact:F [,ignorecase:T]), where Pattern
is a CHARACTER scalar containing one or more of the "wild card"
characters '*' and '?', and Target is a CHARACTER vector, does the same,
except that an exact match is not required to 'hit' Target.

                    Wild card characters '*' and '?'
A '*' in Pattern will match 0 or more successive characters of an
element of Target, without regard to what they are.  A '?' in Pattern
will match any single character of an element of Target, without regard
to what it is.  For example, "start*" matches the first element of
Target that begins with "start", "*mid*" matches the first element
containing "mid", "*mid1*mid2*end" matches the first element finishing
with "end" that earlier contains "mid1" and "mid2" in that order, "p?l*"
matches the first element starting with 'p' and whose third letter is
'l', and so on.  As particular cases, "*" always matches Target[1] and
"\"*\"" matches the first element starting and ending with '"'.

Examples:
  match(vector(1.3,2.4,1.3,5,5.1),vector(2.4,1.3),-1) returns
    vector(2,1,2,-1,-1)
  match(vector(1.3,2.4,1.3,5,2.4,?),vector(2.4,1.3)) returns
    vector(2,1,2,3,1,?)
  match(vector(1.3,2.4,1.3,5,2.4),run(3),-99,fuzz:.5) returns
    vector(1,2,1,-99,2)
  match(vector("A","B","A","C","B"),vector("B","A")) yields
    vector(2,1,2,3,1)
  a <- factor(match(x,sort(unique(x)))) transforms a REAL x to a factor
  unique(x)[match(x,unique(x))] yields x when x is a vector.
  match(scalarValue,vec,0) != 0 if and only scalarValue is in vec
  match("*c",vector("abc","ade","gfh"),exact:F) returns 1
  match("*d*",vector("abc","ade","gfh"),exact:F) returns 2
  match("g*",vector("abc","ade","gfh"),exact:F) returns 3
  match("g*h",vector("abc","ade","gfh"),exact:F) returns 3
  match("a*b*c",vector("abc","ade","gfh"),exact:F) returns 1
  match("a*b???",vector("aqbde","bb123", "allbdef"),exact:F) returns 3

In a macro, it can be helpful to know whether an argument is a an
explicit quoted string:
  if (match("\"*\"","$1",0,exact:F) != 0){
    print("arg 1 is a quoted string")
  }

See also unique(), 'macro_syntax'.