Syntax
MASK(str1{,str2}{,ERR=lineref})
Description
For BBj-specific information, see the MASK() Function - BBj.
The MASK() function scans a string for a matching substring. This differs from the POS() function because str2 may contain pattern matching specifications similar to the UNIX operating system "grep" command.
|
Parameter |
Description |
|---|---|
|
str1 |
String to be scanned |
|
str2 |
Substring to be located. |
|
ERR=lineref |
Branch to be taken if an error occurs during execution. |
The value returned is the starting position instr1 fitting the mask. A returned value of zero indicates that no matching areas were found. If a match was made, the TCB(16) function returns the length of the string matched. If str2 is not given, the prior mask is reused. This is important to program performance because a certain amount of time is spent "compiling" the mask string. Repeated use of the same mask string should specify the mask only once.
Most characters in the mask string must simply match themselves. For example, a mask of "abc" only matches the string "abc". In this case, MASK(A$,"abc") and POS("abc"=A$) return the same result. Note that $00$ is not a valid value for either str1 or str2.
Mask String Operators
|
Operator |
Description |
|---|---|
|
"?" (question mark) |
Indicates that something is optional. For example, a mask of "ab?c" indicates that the "b" is optional. This mask matches "abc" or "ac". Use parentheses for grouping. A mask of "(ab)?c" considers the sequence "ab" optional and matches either "abc" or just "c". |
|
"*" (asterisk) |
Zero or more occurrences of the preceding item. |
|
"+" (plus) |
One or more occurrences of the preceding item. |
|
"|" (pipe) |
Alternate choices. The "|" is lower in precedence than the above operations |
|
"." (period) |
Matches any character. |
|
"[]" (brackets) |
Match the contained character(s). |
|
"-" (hyphen |
Matches a range in a character list. |
|
"^" (caret) |
Excludes characters or matches only those at the beginning of the target string. |
|
"\" (backslash) |
Forces the next character in the mask to be taken literally. For example, a backslash must be used to match a plus sign. |
|
"$" (dollar sign) |
Added at the end of the mask. Matches only characters at the end of the target string. |
Operator Examples
|
String Example |
Matches |
|---|---|
|
"ab*c" |
Any string beginning with "a", ending with "c", and having any number of b's in between. |
|
"ab+c" |
Any string beginning with "a", ending with "c", and having at least one "b" in between. |
|
"(ab)*c" |
Any string with any number of occurrences of "ab" finally ending with a "c". For example, "c", "abc", "ababababc". |
|
"abc|def" |
Either "abc" or "def". |
|
"a(b|c)" |
Either "ab" or "ac". |
|
"a(b|c)*" |
A string beginning with "a", followed by any number of "b" and "c" (in any combination). |
|
"a.c" |
A string beginning with "a", ending with "c", and with any character in the middle. |
|
"a.*c" |
Any string beginning with "a" and ending with "c". |
|
"[abc]" |
Either "a", "b", or "c". |
|
"[abc]+" |
Any string containing only a's, b's, and c's. |
|
"[abc][0123456789]" |
Any string consisting of an "a", "b", or "c" followed by any digit. |
|
"[0-9]" |
Characters 0-9. This is the same as "[0123456789]". |
|
"[a-zA-Z]" |
Any string consisting of upper- and lower-case characters. |
|
"[^0-9]" |
Any character that is not a digit. |
|
"^abc" |
"abc" only if it occurs at the beginning of the string. |
|
"a\+c" |
Only "a+c" |
|
"a+c" |
Any sequence of a's ending with a "c". |
|
"abc$" |
"abc" only if it occurs at the end of the string. |
|
"^a[0-9]*c$" |
A string that begins with an "a", ends with a "c", and contains only digits in between. |
PRO/5 always matches the longest string possible. For example, "a.*c" matches any string beginning with "a" and ending with "c". It does not stop when the first "c" following the "a" is encountered. It stops when the last "c" following the "a" is encountered.
Example 1
1000 PRINT STR(MASK("config.bbx",".*bbx"))+" "+STR(TCB(16))
Example 2
The following displays all file names matching a particular pattern:
1000 INPUT "MASK: ",M$
1010 LET A=MASK("",M$,ERR=1000); REM - establish mask
1020 LET CHAN=UNT; OPEN (CHAN)DIR("")
1030 READ RECORD (CHAN,END=1200)F$
1040 IF MASK(F$)=1 THEN PRINT F$
1050 GOTO 1030
1200 end