|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > String commands > !BLO.-Block-Commands > Utility-Commands > Block Operations |
MiniRobotLanguage (MRL)
BLO.FindNthL
Find Nth Occurrence (Left-to-Right or Right-to-Left based on N)
Intention
This command finds the 1-based position of the Nth occurrence of a search string (P2) within a source string (P1). By default, the search is performed from left to right (from the beginning of the string to the end). However, if N (P3) is negative, the search direction reverses to right-to-left, counting |N| occurrences from the end.
The resulting position is placed on the Top of Stack (TOS) if no result variable is specified, or in an optional variable (P6). If the occurrence is not found, the result is 0.
The command supports optional flags for case-insensitivity (P4) and overlap skipping (P5). Overlap skipping is useful for patterns that can overlap, such as searching for "aa" in "aaaa": without skipping, the second occurrence starts immediately after the first (position 2); with skipping, it starts after the full match (position 3).
Schematic (Left-to-Right)
Source: "one two one three one four"
Search: "one" N = 2 (Find the 2nd occurrence)
Search Direction -->
|o|n|e| |t|w|o| |o|n|e| |t|h|r...
1 2 3 4 5 6 7 8 9^ ^|
1st occurrence 2nd occurrence (Result: 9)
Syntax
BLO.FindNthL|P1|P2|P3[|P4][|P5][|P6]
Parameter Explanation
•P1 - (Source String) The string to search within. Can be a variable or literal string.
•P2 - (Search String) The substring to search for. Can be a variable or literal.
•P3 - (Occurrence N) The occurrence number to find. Positive for left-to-right search; negative for right-to-left search (using |N| as the count from the end). If 0, returns the length of P1.
•P4 - (Optional Case-Insensitive Flag) 0 = Case-Sensitive (default), 1 = Case-Insensitive. Omit or leave empty for default.
•P5 - (Optional Overlap-Skip Flag) 0 = Allow overlaps (default), 1 = Skip past the full match before resuming search. Omit or leave empty for default.
•P6 - (Optional Result Variable) A variable to store the numeric result. If omitted, the result is pushed to TOS.
Examples
' Basic left-to-right search
: $$SRC=one two one three one four
: $$SEA=one
BLO.FindNthL|$$SRC|$$SEA|1|||$$POS
' Result: 1
BLO.FindNthL|$$SRC|$$SEA|2|||$$POS
' Result: 9
BLO.FindNthL|$$SRC|$$SEA|3|||$$POS
' Result: 19
' Case-insensitive search
: $$SRC=This IS a Test. Is it not?
: $$SEA=is
BLO.FindNthL|$$SRC|$$SEA|3|1||$$POS
' Result: 17 (matches 'is' in "This", "IS", "Is")
' Overlap handling
: $$SRC=aaaa
: $$SEA=aa
BLO.FindNthL|$$SRC|$$SEA|2||0|$$POS
' Result: 2 (allows overlap)
BLO.FindNthL|$$SRC|$$SEA|2||1|$$POS
' Result: 3 (skips overlap)
' Edge cases
: $$SRC=one two one
: $$SEA=one
BLO.FindNthL|$$SRC|$$SEA|10|||$$POS
' Result: 0 (not found)
BLO.FindNthL|$$SRC|$$SEA|0|||$$POS
' Result: 11 (source length)
BLO.FindNthL|$$SRC|$$SEA|-1|||$$POS
' Result: 9 (first from right, RTL search)
' Result to TOS
: $$SRC=one two one three one four
: $$SEA=one
BLO.FindNthL|$$SRC|$$SEA|3
' TOS: 19
Remarks
-If P3 (Occurrence N) is 0, the command returns the total length of the source string (P1), regardless of the search string.
-If P3 is negative, the search direction changes to right-to-left, and it finds the |P3|th occurrence from the end of the string.
-The Overlap-Skip (P5) flag affects how overlapping matches are handled. For example, in "aaaa" searching for "aa", without skip (0), the second match starts at position 2 (overlapping); with skip (1), it starts at position 3 (non-overlapping).
-If parameters are omitted, use consecutive pipes (e.g., BLO.FindNthL|$$SRC|$$SEA|3|1||$$POS for CI=1, OverlapSkip default, result in $$POS).
-This command is case-sensitive by default. Use P4=1 for case-insensitive searches, which can match variations like "Is" and "is".
-For purely right-to-left searches with positive N counting from the end, use BLO.FindNthR. For automatic direction based on N sign, use BLO.FindNthX.
See also: