INSTR()

Updated October 2016; see History

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 standard A-BASIC 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.

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 REGEX.SBR 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 REGEX. (See REGEX.SBR'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 REGEX.SBR: 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.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 INSTR(), and thus you could use REGEX.SBR 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 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.