TPUHELP.HLB  —  SCAN
  SCAN

     Returns a pattern matching the longest string that does not contain any
     of the characters in the specified string, range, or buffer.  The
     pattern matches characters until it reaches the end of the line being
     searched or until it finds one of the characters in the string, range,
     or buffer used as a parameter.  SCAN fails if it finds no characters
     other than those present in its argument.  SCAN succeeds if it finds at
     least one character not specified in the first parameter.

  Syntax

     pattern := SCAN ({string | range | buffer} [, {FORWARD | REVERSE}])

  Parameters

     string               A string containing the characters that cause
                          TPU to stop matching characters in the searched
                          text.

     range                A range containing the characters that cause
                          TPU to stop matching characters in the searched
                          text.

     buffer               A buffer containing the characters that cause
                          TPU to stop matching characters in the searched
                          text.

     FORWARD              A keyword directing TPU to match characters in
                          the forward direction.

     REVERSE              A keyword directing TPU to match characters as
                          follows:  First, match characters in the forward
                          direction until TPU finds a character that is a
                          member of the set of characters in the specified
                          buffer, range, or string.  Next, return to the
                          first character that SCAN matched and start
                          matching characters in the reverse direction until
                          TPU finds a character in the specified buffer,
                          range, or string.  You can specify REVERSE only if
                          you are using SCAN in the first element of a
                          pattern being used in a reverse search.  In all
                          other contexts, specifying REVERSE has no effect.

                          The behavior enabled by REVERSE allows an
                          alternate form of reverse search.  By default, a
                          reverse search stops as soon as a successful match
                          occurs, even if there might have been a longer
                          successful match in the reverse direction.  By
                          specifying REVERSE with SCAN, you direct TPU
                          not to stop matching in either direction until it
                          has matched as many characters as possible.

  Examples

     1.  pat1 := SCAN ('abc');

         This assignment statement stores in "pat1" a pattern that matches
         the longest string of characters that does not contain an a, b, or
         c.

     2.  pat1 := SCAN ('abc', FORWARD);

         This statement has exactly the same effect as Example 1.

     3.  word := SCAN (' ', REVERSE);

         This statement defines the variable "word" to mean the longest
         consecutive string of characters that does not include a space
         character.  If you use the following statement:

         the_range := SEARCH (word, REVERSE);

         when the cursor is on the "n" in Xanadu in the following text:

         "In Xanadu did Kublai Khan a stately pleasure dome decree"

         then the variable "the_range" contains the word "Xanadu".  This is
         because when you use SCAN with REVERSE as the first element of a
         pattern, and then use that pattern in a reverse search, SCAN
         matches as many characters as possible in both the forward and
         reverse directions.

         If the cursor is on "n" but you define the variable "word" without
         the REVERSE keyword, like this:

         word := SCAN (' ');

         and then do a reverse search, "the_range" contains the characters
         "nadu".

  Related Topics

  ANCHOR    ANY             ARB       MATCH      NOTANY     SCANL
  SEARCH    SEARCH_QUIETLY  SPAN      SPANL      UNANCHOR
Close Help