Name

---

      MATCH

Purpose

---

      Routine to match values in two vectors.

Calling Sequence

---

      match, a, b, suba, subb, [ COUNT =, /SORT, EPSILON = ]

Inputs

---

      a,b - two vectors to match elements, numeric or string data types

Outputs

---

      suba - subscripts of elements in vector a with a match
              in vector b
      subb - subscripts of the positions of the elements in
              vector b with matchs in vector a.
      suba and subb are ordered such that a[suba] equals b[subb]

Optional Input Keyword

---

      /SORT - By default, MATCH uses two different algorithm: (1) the
              /REVERSE_INDICES keyword to HISTOGRAM is used for integer data,
              while (2) a sorting algorithm is used for non-integer data. The
              histogram algorithm is usually faster, except when the input
              vectors are sparse and contain very large numbers, possibly
              causing memory problems. Use the /SORT keyword to always use
              the sort algorithm.
      epsilon - if values are within epsilon, they are considered equal. Used only
              only for non-integer matching. Note that input vectors should
              be unique to within epsilon to provide one-to-one mapping..
              Default=0.

Optional Keyword Output

---

      COUNT - set to the number of matches, integer scalar

Side Effects

---

      The obsolete system variable !ERR is set to the number of matches;
      however, the use !ERR is deprecated in favor of the COUNT keyword

Restrictions

---

      The vectors a and b should not have duplicate values within them.
      You can use rem_dup function to remove duplicate values
      in a vector

Example

---

      If a = [3,5,7,9,11] & b = [5,6,7,8,9,10]
      then
              IDL> match, a, b, suba, subb, COUNT = count
      will give suba = [1,2,3], subb = [0,2,4], COUNT = 3
      and a[suba] = b[subb] = [5,7,9]

Method

---

      For non-integer data types, the two input vectors are combined and
      sorted and the consecutive equal elements are identified. For integer
      data types, the /REVERSE_INDICES keyword to HISTOGRAM of each array
      is used to identify where the two arrays have elements in common.

History

---

      D. Lindler Mar. 1986.
      Fixed "indgen" call for very large arrays W. Landsman Sep 1991
      Added COUNT keyword W. Landsman Sep. 1992
      Fixed case where single element array supplied W. Landsman Aug 95
      Use a HISTOGRAM algorithm for integer vector inputs for improved
            performance W. Landsman March 2000
      Work again for strings W. Landsman April 2000
      Use size(/type) W. Landsman December 2002
      Work for scalar integer input W. Landsman June 2003
      Assume since V5.4, use COMPLEMENT to WHERE() W. Landsman Apr 2006
      Added epsilon keyword Kim Tolbert March 14, 2008