47.2. scan

A file or STRING (the “source”) is scanned as directed by scanCtrl and ctrlBits. area specifies the destination area for the resulting STRING if new STRING text is generated; see Section 29.4.

Characters (the “scanned characters”) are removed from the source while or until any of a set of characters (the “scan characters”) is encountered in the source. The scanned characters are returned as the result STRING. Thus, scan allows the programmer to scan up to (or over) any one of a set of characters.

scanCtrl indicates what scan characters are to guide the scan. There are three ways to specify the scan characters:

1. scanCtrl can be a STRING that directly gives the scan characters; every character in the STRING is a scan character.

2. scanCtrl can be a BITS obtained from scanSet. The scan characters are those in the STRING that was used as the argument to scanSet. scanCtrl may also have the value of several such bits IORed together (see Example 47–5), in which case the scan characters are taken from the STRING that is the concatenation of the corresponding arguments to scanSet. There is a limit on the number of such sets in use at the same time equal to one less than the number of bits in a BITS value, so the use of $scanSet is preferred if the values need not be IORed together.

3. scanCtrl can be an INTEGER obtained from $scanSet. The scan characters are those in the STRING that was used as the argument to $scanSet.

The BITS and INTEGER forms of scanCtrl are more efficient for scan characters that are used repeatedly, since the STRING form involves some overhead that depends on the length of scanCtrl.

$cScan is a more efficient version of scan when source is a STRING and scanCtrl consists of a single character; see Section 32.74.

brkChr is the “break character”, the character that causes the scan to terminate (“break”). The break character is often useful for determining the action following a scan.

In the file forms, if the file is opened for PDF I/O, the characters read from the file may be translated from the PDF to the host character set.

The valid predefined BITS constants that may be set in ctrlBits are:

• Bits that specify how to use the scan characters:
  • break: The scan characters are to break the scan. All other characters are proceed characters. This is the default.

  • proceed: The scan characters cause the scan to proceed. All other characters are break characters.

• Bits that specify what to do with the break character (it is always put into brkChr):
  • retain: Stays in source, not put into result STRING. This is the default.

  • append: Becomes last character of result STRING (removed from source).

  • discard: Discarded (removed from source, not put into result STRING).

• Bits that specify characteristics of result STRING:
  • omit: Discard characters instead of putting them into the result STRING (which is the empty STRING, even if append is set). This option may result in a significant savings in execution time and STRING space.

  • upperCase: Source characters (but not scanCtrl characters) are converted to upper case before they are checked for breaking the scan and put into the result. The break character is the original character taken from the STRING (i.e., not converted to upper case). It is more efficient to use the upperCase option with compare (see Section 32.44) than with scan if its only purpose is to provide a caseless comparison.

End-of-source breaks the scan, with the result STRING equal to the STRING scanned up to the end-of-source, and brkChr equal to -1. -1 is not a valid character code.