Updated December 2023
INSTR (spos, subject, pattern, {flags})
Returns position of first occurrence of pattern in source.
Searches the subject string for the specified pattern, starting at position spos. Returns the position (base 1) of the first match, or 0 if no match is found. Negative values indicate Regex errors; see comments.
The A-Shell version of INSTR() is equivalent to the original AlphaBASIC version except for the optional flags argument, which, if specified, causes the pattern to be treated as a regular expression (see below).
Parameters
spos (Num) [in]
Position within the subject string to begin search. 1 is the first position. 0 and negative values are invalid and will return 0 as the result.
subject (String) [in]
String to be searched
pattern (String) [in]
Substring or pattern to search for. Treated as case-sensitive literal text unless flags specified. Note that a single character ASCII value may be interpreted as a precompiled pattern index rather than a literal pattern. See Using Precompiled Patterns under Comments below.
flags (Num) [in]
If specified (even if 0), causes pattern to be treated as a Perl-compatible regular expression. The values for flags are the same as those for the Xcall REGEX options flags plus these two additional flags:
Flag |
Value |
Description |
|---|---|---|
INSTRF_ANY |
&h01000000 |
Treat pattern as set of characters; match first one that appears in subject. |
INSTRF_ANYQT |
&h02000000 |
Same as INSTRF_ANY but ignores characters in subject between matching quotes. |
These are based on the standard C function strpbrk(). For example:
PRINT INSTR(1, "DSK0:ABC.RUN /X", ";/ ", INSTRF_ANY)
Of the three characters in the pattern (";/ "), the first to occur in the subject is the space at position 13.
The above is equivalent to the REGEX character set pattern "[;/ ]"; it simply eliminates any doubts about REGEX syntax for special characters. But the INSTRF_ANYQT version is much harder to implement using REGEX.
Comments
Error Conditions: Any of the following conditions are considered invalid and will return 0 (no match):
| • | null pattern |
| • | null subject |
| • | spos < 0 |
| • | spos > length of string |
Errors relating to regular expressions will be returned as negative values, matching those returned by Xcall REGEX. See REGEX's Pattern Complilation Errors and Matching Errors.
Case Sensitivity: For a case-insensitive search, you can either use the regular expression mode with PCRE_CASELESS (&h0001) flag, or you can just apply the String Functions LCS$() or UCS$() to the subject and pattern strings.
INSTR() versus Xcall REGEX: The function and subroutine version reference the same internal logic, and have the same parameter semantics. The INSTR() version has less overhead and is easier to use, while the REGEX subroutine version offers additional power (mainly in the advanced area of sub-expression matching, although it also returns the actual matched substring, which is often handy and not obvious).
Precompiling Patterns: Five numbered precompiled patterns (1-5) may be shared between REGEXxs and INSTR(), and thus you could use REGEXxs to pre-compile patterns later used with INSTR(), if you prefer to use INSTR() itself to pre-compile patterns, set the PCREX_PRECOMPILE (&h80000000) bit in the flags parameter and set spos to the pattern number, like patno in REGEX. The subject string will be ignored (can be ""). On success, the return value of the function will equal spos; else refer to the status codes listed under Xcall REGEX.
Using Precompiled Patterns: As with REGEX, you can specify a precompiled pattern by setting pattern = CHR$(n) where n is the pattern number (1-5). Whenever the same pattern is used in consecutive calls, the previously compiled version is automatically used, making pre-compilation unnecessary except when alternating between multiple patterns. To prevent a single-character pattern from being accidentally misinterpreted as a precompiled pattern number, specify the PCREX_NOT_PRECOMPILED (&h08000000) bit in flags. See History below for evolution of this feature and OPTIONS=NOINSTRX_PCP for a way to disable it globally.
See Also
| • | EXLIB:[908,46] for sample programs. |
| • | The A-Shell forum topic "Substring search right-to-left" for a discussion on how to implement a last-match (or right-to-left) version of INSTR(). As of 6.3.1527, the doc function .INSTRR() is available right-to-left searching. A general form search on the term "INSTR" will also turn up many threads which might be of related interest |
History
2023 December, A-Shell 7.0.1752.4: PCREX_NOT_PRECOMPILED flag introduced and maximum precompiled pattern number reduced from 127 to 5 to minimize accidental misinterpretation.
2023 June, A-Shell 6.5.1732: Maximum precompiled pattern number increased from 20 to 127.
2016 October: A-Shell 6.3.1530: Add two non-REGEX flags as shown above.
