|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > String commands > !STR.- String Command > Instring - Find Commands > String Operations |
MiniRobotLanguage (MRL)
STR.NInstr
Case-Sensitive Nth String Search
Intention
This command searches for the nth occurrence of a specified string (P2) within a source string (P1), starting from an optional position (P4).
The occurrence number is specified by P3. The result is the 1-based position of the nth match (or 0 if not found), placed on the Top of Stack (TOS) and optionally in a variable (P5).
The search is case-sensitive (e.g., "Hello" does not match "hello"). If P4 is positive (or 0, defaults to 1), it searches left-to-right from that position. If negative (e.g., -1), it searches right-to-left from the end (or |P4| bytes from end), counting occurrences in reverse order, but the result is always a 1-based position from the start of the string.
This command is useful for finding specific instances of a substring in text processing tasks, such as parsing logs or structured data, without modifying the source string.
Schematic (Forward and Reverse Nth Search)
Source: HelloWorldHello
Search: Hello, N=2, Start=1 (LTR) --> Pos=11
Search --> |H|e|l|l|o|W|o|r|l|d|H|e|l|l|o|
^ (2nd Hello at 11)
Search: Hello, N=2, Start=-1 (RTL) --> Pos=1
Search <-- |o|l|l|e|H|d|l|r|o|W|o|l|l|e|H|
^ (2nd Hello at 1)
Syntax
STR.NInstr|P1|P2|P3[|P4][|P5]
Parameter Explanation
•P1 - (Source String) The main string to search within. Variable or literal.
•P2 - (Search String) The string to search for. Variable or literal.
•P3 - (Occurrence Number) Numeric, the nth occurrence to find (1-based, e.g., 1 for first, 2 for second).
•P4 - (Optional Start Position) Numeric, 1-based (default 1). If negative, searches right-to-left from end or |P4| bytes from end, counting occurrences in reverse; result is 1-based from start.
•P5 - (Optional Result Variable) Variable to store the result (position or 0). Result is always pushed to TOS.
Examples
' Forward search for 2nd occurrence to TOS
$$TXT=HelloWorldHello
$$SEA=Hello
STR.NInstr|$$TXT|$$SEA|2|1
POP.$$RES
' $$RES = 11 (2nd "Hello")
' Reverse search for 2nd occurrence to variable
$$TXT=HelloWorldHello
$$SEA=Hello
STR.NInstr|$$TXT|$$SEA|2|-1|$$POS
' $$POS = 1 (2nd "Hello" from end)
' No match for nth occurrence
$$TXT=HelloWorld
$$SEA=Hello
STR.NInstr|$$TXT|$$SEA|2|1|$$POS
' $$POS = 0 (no 2nd "Hello")
Remarks
-Case-sensitive search; "Hello" does not match "hello".
-P3 must be positive (1-based); non-positive or non-numeric values may cause undefined behavior.
-P4=0 defaults to 1 (LTR start). Negative P4 searches right-to-left, counting occurrences in reverse order.
-Result is always pushed to TOS, even if P5 is specified.
-If search string longer than remaining source or nth occurrence not found, returns 0.
-Binary-safe for P1 and P2; no special/system vars expanded.
-For case-insensitive search, use STR.CiInstr; for pattern-based search, use STR.FindAny.
Limitations
-No wildcard or pattern support; use STR.FindAny for patterns.
-No overlap handling; finds nth non-overlapping occurrence.
-P3 must be positive; negative values may cause undefined behavior.
See also: