INSTR() now accepts a fourth parameter:
INSTR(spos, subject, pattern, flags)
When the fourth parameter (flags) is specified (even if 0), the pattern is treated as a regular expression. This replaces the separate function INSTREX() which was initially introduced in 5.1.1108.
As much as possible, both versions of INSTR() offer the same semantics. Both return the position of the located string, with 0 indicating no match. Both fail (returning 0) for each of the following conditions:
| • | null pattern |
| • | null subject string |
| • | stpos < 0 |
| • | stpos > length of string |
The most important difference is that the four-parameter (regular expression) version can return negative values indicating error conditions that go beyond a simple failure to match the pattern. These will be the same errors returned in the STATUS parameter of REGEX.SBR.
Comments
INSTR() versus REGEX.SBR: The function and XCALL 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.SBR 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: Although the 20 numbered precompiled patterns (1-20) may be shared between REGEX.SBR and INSTREX(), and thus you could use REGEX.SBR to pre-compile patterns later used with INSTREX(), if you prefer to use INSTREX() itself to pre-compile patterns, set the PCREX_PRECOMPILE (&h80000000) bit in the FLAGS parameter and set STPOS 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 STPOS; else refer to the STATUS codes listed under REGEX.
Using Precompiled Patterns: As with REGEX.SBR, you can specify a precompiled pattern by setting PATTERN = CHR$(n) where n is the pattern number (1-20). As with REGEX.SBR, 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).
Backward Incompatibility: The new, 4-parameter version of INSTR() is NOT backwards compatible with runtime versions prior to 5.1.1109. However, the RUN file itself may still be used, as long as you never actually try to execute the statement. To prevent that, you would need to test for the A-Shell version (see MX_GETVER) and only execute the new INSTR() function if the A-Shell version is at least 5.1.1109.
See [908,46] in the EXLIB for sample programs.
