STRMATCH Function

Matches a specified string to an existing regular expression.

Usage

result = STRMATCH(string, expr [, registers])

Input Parameters

string—A string or array of strings to be compared to a regular expression.

expr—A regular expression describing the pattern of matching strings for comparison.

Output Parameters

registers—(optional) A string array containing the text of string, and matching the regular expression and sub-expressions. The first part of string that matches the regular expression is stored in element 0, and any additional matching sub-expressions are stored in elements 1 – 9. If string is an array of strings, registers only returns the matches for the first element of string.

Returned Value

result—A byte value indicating the success or failure of the match.

1—Indicates the string matches the regular expression.

0—Indicates no match.

If string is an array of strings, result is an array with the same structure. Each element in the result array contains a value of 1 or 0 (indicating a match, or no match respectively) for the corresponding string element.

Keywords

Grep—If nonzero, the regular expression follows the syntax used by the UNIX command grep. Using Grep is equivalent to specifying a Syntax value of 20.

Egrep—If nonzero, the regular expression follows the syntax used by the UNIX command egrep. Using Egrep is equivalent to specifying a Syntax value of 51.

Exact—If nonzero, the string must match the regular expression exactly.

Length—Specifies a named variable in which to store the number of characters in string that match the regular expression. If Exact is used with Length, the resulting operation is equivalent to STRLEN(string).

Position—If nonzero, specifies a named variable into which the position in string where the match occurred is stored. If Exact is used with Position, the position of the matched string will be zero.

If string is an array of strings, the return values of Length and Position are arrays with the same structure as string.

Syntax—The regular expression syntax encoded as bits in a longword. The table in the Discussion section provides the syntax details.

Discussion

A regular expression is a string that uses special characters to represent patterns.

Note:

STRMATCH uses regular expressions, not wildcard characters, for pattern matching. To use STRMATCH, it is crucial that you understand regular expressions. For a detailed discussion of regular expressions, see the PV‑WAVE Programmer’s Guide.

By default, STRMATCH uses a regular expression syntax compatible with the UNIX command awk. This is equivalent to specifying a Syntax value of 35. Keywords are used so STRMATCH uses a syntax compatible with the UNIX commands grep or egrep; or a completely arbitrary syntax can be specified using Syntax.

Note:

One difference between STRMATCH and awk regular expressions is in the representation of the TAB character. Where '\t' is used in awk, STRMATCH uses an actual TAB keystroke entry.

Syntax Bit Values lists information pertinent to Syntax.

Syntax Bit Values
Bit	Value	Function
0	1	If this bit is set, then ‘(’ and ‘)’ are used for grouping. Otherwise, ‘$’ and ‘$’ are used for grouping.
1	2	If this bit it set, then ‘\|’ is used as the OR operator. Otherwise, ‘\\|’ is used as the OR operator.
2	4	If this bit is set, then ‘\+’ and ‘\?’ are operators. Otherwise, ‘+’ and ‘?’ are operators.
3	8	If this bit is set, then ‘\|’ binds tighter than ‘^’ and ‘$’. Otherwise, the opposite is true.
4	16	If this bit is set, then newline is treated as an OR operator. Otherwise, newline is treated as a normal character.
5	32	If this bit is set, then certain characters (‘^’, ‘$’, ‘*’, ‘+’ and ‘?’) only have special meaning in certain contexts. Otherwise, they always have their special meaning, regardless of the surrounding context.

Example 1

This example uses STRMATCH to determine if a user’s response to a prompt was valid.

; Prompt the user for a response.

x = '' & READ, 'Enter a letter or number: ', x

; If response is not a single letter or number, error message is

; issued.

IF NOT STRMATCH(x, '[a-zA-Z0-9]', /Exact) THEN $

   PRINT, 'Invalid response.'

Example 2

In this example, STRMATCH is used to ensure that names entered by a user are always in “First name, Last name” order.

name = 'Smith, Bill J.'

; If two parts of name are separated by a comma, store two parts

; in register and concatenate them back together to form new name.

IF STRMATCH(name, '^(.*), *(.*)$', reg) THEN $

   name = reg(2) + ' ' + reg(1)

PRINT, name

; PV-WAVE prints the following:

; Bill J. Smith

Example 3

This example demonstrates how to use the STRMATCH function in conjunction with WHERE to perform data subsetting.

; The two string arrays associate the owners with their pets.

owners = ['Bill', 'Kathy', 'Janis', 'Ken']

pets = ['cat', 'rabbit', 'fish', 'dog']

w = STRMATCH(pets, 'cat|dog')

; Print the names of any owners of a cat or dog.

PRINT, owners(WHERE(w)), Format='(A)'

; PV-WAVE prints the following:

; Bill

; Ken