|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > String commands > !BLO.-Block-Commands > Utility-Commands > Block Operations |
MiniRobotLanguage (MRL)
BLO.FindNthX
Find Nth Occurrence (Flexible Direction)
Intention
This command finds the 1-based position of the Nth occurrence of a search string (P2) within a source string (P1). The search direction is automatically determined by the sign of N (P3): positive for left-to-right (from beginning to end), negative for right-to-left (from end to beginning, using |N| as the count).
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). This flexible direction makes it convenient for bidirectional searches without separate commands.
Schematic (Flexible Direction)
Source: "one two one three one four"
Search: "one"
Positive N=2 (L->R): --> ... |o|n|e| |t|w|o| |o|n|e| ... (Result: 9)
Negative N=-1 (R->L): <-- ... |o|n|e| |e|e|r|h|t| |e|n|o| ... (Result: 19)
Syntax
BLO.FindNthX|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 (LTR) search; negative for right-to-left (RTL) search (using |N| 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
' Positive N: Left-to-Right search
: $$SRC=one two one three one four
: $$SEA=one
BLO.FindNthX|$$SRC|$$SEA|1|||$$POS
' Result: 1 (1st from left)
BLO.FindNthX|$$SRC|$$SEA|2|||$$POS
' Result: 9 (2nd from left)
' Negative N: Right-to-Left search
BLO.FindNthX|$$SRC|$$SEA|-1|||$$POS
' Result: 19 (1st from right)
BLO.FindNthX|$$SRC|$$SEA|-2|||$$POS
' Result: 9 (2nd from right)
' Case-insensitive search (positive N)
: $$SRC=This IS a Test. Is it not?
: $$SEA=is
BLO.FindNthX|$$SRC|$$SEA|3|1||$$POS
' Result: 17 (LTR, 3rd match)
' Case-insensitive search (negative N)
BLO.FindNthX|$$SRC|$$SEA|-3|1||$$POS
' Result: 3 (RTL, 3rd from right)
' Overlap handling (positive N)
: $$SRC=aaaa
: $$SEA=aa
BLO.FindNthX|$$SRC|$$SEA|2||0|$$POS
' Result: 2 (LTR, allows overlap)
BLO.FindNthX|$$SRC|$$SEA|2||1|$$POS
' Result: 3 (LTR, skips overlap)
' Overlap handling (negative N)
BLO.FindNthX|$$SRC|$$SEA|-2||1|$$POS
' Result: 1 (RTL, skips overlap)
' Edge cases
: $$SRC=one two one
: $$SEA=one
BLO.FindNthX|$$SRC|$$SEA|10|||$$POS
' Result: 0 (not found, LTR)
BLO.FindNthX|$$SRC|$$SEA|0|||$$POS
' Result: 11 (source length)
BLO.FindNthX|$$SRC|$$SEA|-10|||$$POS
' Result: 0 (not found, RTL)
' Result to TOS
: $$SRC=one two one three one four
: $$SEA=one
BLO.FindNthX|$$SRC|$$SEA|3
' TOS: 19 (LTR, 3rd from left)
BLO.FindNthX|$$SRC|$$SEA|-2
' TOS: 9 (RTL, 2nd from right)
Remarks
-If P3 (Occurrence N) is 0, the command returns the total length of the source string (P1), regardless of direction or search string.
-For positive P3, behaves like BLO.FindNthL (LTR); for negative, like BLO.FindNthR (RTL, using |P3|).
-The Overlap-Skip (P5) flag applies in the chosen direction. For example, in "aaaa" searching for "aa" with positive N=2 and skip=1, result is 3 (LTR non-overlap); with negative N=-2 and skip=1, result is 1 (RTL non-overlap).
-If parameters are omitted, use consecutive pipes (e.g., BLO.FindNthX|$$SRC|$$SEA|3|1||$$POS for positive N=3, 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".
-This is the most flexible variant; use BLO.FindNthL for always LTR or BLO.FindNthR for always RTL.
See also: