SAS/C Library Reference, Vol. 1

stcpm -- Unanchored Pattern Match

SYNOPSIS

 #include <lcstring.h>

 int stcpm(char *str, const char *pat, char **substr);

DESCRIPTION

stcpm scans the input string addressed by str for the first occurrence of a substring matching the pattern addressed by pat. The substr function points to a word in which the first match to the search pattern is stored (if a match is found). This pointer is not used if no match is found. (See RETURN VALUE.)

You can specify the search pattern in several ways, possibly including the special characters *, ?, and +, as follows:

*: matches zero or more occurrences of the preceding character.
+: matches one or more occurrences of the preceding character.
?: matches any character.

To scan for an exact match to a pattern, specify the pattern character for character. For example, to locate William A. Tell, specify William A. Tell as follows:
```
 stcpm(str, "William A. Tell", substr);
 
```
To match some elements of a pattern exactly, with other elements free to vary, use the question mark (?) for the elements that can vary:
```
 stcpm(str, "William ?. Tell", substr);
 
```
This statement matches any pattern with William as the first item, any character as the middle initial, a period, and Tell as the last item. (If the middle initial is a question mark, it matches as well. More on this situation is discussed in the next item.)
To match 0 or more occurrences of a character, use an asterisk (*) in the search pattern. The asterisk should follow the character that may occur several times or not occur at all:
```
 stcpm(str, "William A*. Tell", substr);
 
```
This statement matches the following list with any number of occurrences
of A:
```
 William . Tell
 William A. Tell
 William AAAAA. Tell
 
```
Similarly, this statement matches the list items that follow it:
```
 stcpm(str, "William A*.* *Tell", substr);
 
```
- a character sequence that contains a blank and no A (" "); a blank and one A (" A"); or a blank and several A's (" AAA"):
```
 William  . Tell
 William A. Tell
 William AAAAA. Tell
 
```
- no period, one period, or several periods:
```
 William A Tell
 William A. Tell
 William ..... Tell
 
```
- no blank, one blank, or several blanks before Tell:
```
 William A.Tell
 William A. Tell
 William A.     Tell
 
```
- a combination of the possible variations:
```
 William AAATell
 William ...   Tell
 William    Tell
 
```
As another example, the following statement matches a character sequence beginning with William and ending with Tell, with no middle initial character, or with any middle-initial character, including a question mark:
```
 stcpm(str, "William ?*.* *Tell", substr);
 
```
To match only on a question mark, use a question mark preceded by a backslash. (Recall that the backslash is used as an escape character in string literals as well, so you must use two backslashes in a string literal to get one backslash in the pattern.)
For an exact match with William ?. Tell, use this statement:
```
 stcpm(str, "William \\?. Tell", substr);
 
```
By comparison, no match is found for William A. Tell or for William . Tell when you use the search pattern in this statement.
To match one or more occurrences of a character, use a plus sign (+) following the character in the search pattern:
```
 stcpm(str, "William A. T+e+l+l+", substr);
 
```
The search pattern in the above statement matches the following:
```
 William A. Tell
 William A. TTTeeelll
 
```
The matching continues with multiple occurrences of T, e, and l. Note that the plus sign matches one or more occurrences, but not zero occurrences of the character. (To find a match where there may be no occurrence of a character, use an asterisk (*) following the character.)
To exactly match a plus sign (+) or asterisk (*), precede the + or * symbol in the search pattern with a backslash.
You can combine the +, *, and ? symbols in the search pattern when various combinations of characters are to be matched. Consider these examples:
```
    /* ?+ matches one or more question marks  */ 
 char *pat1 = "William \\?+.* *Tell";

    /* ?* matches zero or more question marks */ 
 char *pat2 = "William \\?*.* *Tell";
 
```

RETURN VALUE

stcpm returns the length of the character sequence that matches the search pattern, if successful, or 0 if no match is found. The character pointer that substr addresses points to the first match to the search pattern if a match is found.

CAUTION

The value returned by stcpm (str, pat, substr), the length of the character sequence that matches the search pattern, is not necessarily the same as the value returned by strlen(*substr) because strlen(*substr) returns the length of the input string from the beginning of the match to the null character that terminates the string. The length, in this case, may include characters that were not matched.

IMPLEMENTATION

For stcpm, the scan is not anchored. If no match occurs at the first position in the input string str, the next position is checked until a match is found, and so on until the input string is exhausted.

EXAMPLE

  #include <lcstring.h>
  #include <stdio.h>

  main()
  {
     static char *sps[ ]  = {
        "----William Tell----",    /* no middle initial         */
        "(((William A Tell)))",    /* middle initial            */
        "...William AAA. Teller",  /* middle initial and period */
        "As William S. Tell Jr"    /* wrong initial             */
     };

     char *reslt;
     char **q;
     int length, i;

     q = &reslt;

        /* Find William Tell, whether or not he used his        */
        /*  middle initial.                                     */
     for (i = 0; i < 4; i++) {
        if (length = stcpm(sps[i] , "William A*.* *Tell", q)){
           printf("n%d. Match result =  ",i);
           fwrite(reslt, 1, length, stdout);
        }
        else
           printf("n%d. No match for string = %sn", i, sps[i] );
     }
  }

RELATED FUNCTIONS

stcpma, strchr, strstr