|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > String commands > !BLO.-Block-Commands > Utility-Commands > Block Operations |
MiniRobotLanguage (MRL)
BLO.FindNthR
Find Nth Occurrence (Right-to-Left)
Intention
This command finds the 1-based position of the Nth occurrence of a search string (P2) within a source string (P1). The search is always performed from right to left (from the end of the string to the beginning).
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 finding adjacent repeating patterns from the right.
Schematic (Right-to-Left)
Source: "one two one three one four"
Search: "one" N = 2 (Find the 2nd occurrence from right)
Search Direction <-- +--------------------------------+
| ... r|h|t| |e|n|o| |e|e|r|h|t| |e|n|o| |o|w|t| |e|n|o|
^ ^ 19 18 17 ... 10 9 8 ... 3 2 1|
1st from right 2nd from right (Result: 9)
Syntax
BLO.FindNthR|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 (or negative treated as positive) for right-to-left search, counting 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 right-to-left search
: $$SRC=one two one three one four
: $$SEA=one
BLO.FindNthR|$$SRC|$$SEA|1|||$$POS
' Result: 19 (1st from right)
BLO.FindNthR|$$SRC|$$SEA|2|||$$POS
' Result: 9 (2nd from right)
BLO.FindNthR|$$SRC|$$SEA|3|||$$POS
' Result: 1 (3rd from right)
' Case-insensitive search
: $$SRC=This IS a Test. Is it not?
: $$SEA=is
BLO.FindNthR|$$SRC|$$SEA|3|1||$$POS
' Result: 3 (3rd from right: positions 17,6,3 -> 3)
' Overlap handling
: $$SRC=aaaa
: $$SEA=aa
BLO.FindNthR|$$SRC|$$SEA|2||0|$$POS
' Result: 2 (allows overlap)
BLO.FindNthR|$$SRC|$$SEA|2||1|$$POS
' Result: 1 (skips overlap)
' Edge cases
: $$SRC=one two one
: $$SEA=one
BLO.FindNthR|$$SRC|$$SEA|10|||$$POS
' Result: 0 (not found)
BLO.FindNthR|$$SRC|$$SEA|0|||$$POS
' Result: 11 (source length)
BLO.FindNthR|$$SRC|$$SEA|-1|||$$POS
' Result: 9 (treats as positive, 1st from right)
' Result to TOS
: $$SRC=one two one three one four
: $$SEA=one
BLO.FindNthR|$$SRC|$$SEA|2
' TOS: 9 (2nd from right)
Remarks
-If P3 (Occurrence N) is 0, the command returns the total length of the source string (P1), regardless of the search string.
-Negative values for P3 are treated as their absolute positive equivalents for right-to-left searching (e.g., -1 is treated as 1, finding the last occurrence).
-The Overlap-Skip (P5) flag affects how overlapping matches are handled from the right. For example, in "aaaa" searching for "aa", without skip (0), the second match from right is at position 2; with skip (1), at position 1.
-If parameters are omitted, use consecutive pipes (e.g., BLO.FindNthR|$$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 left-to-right searches, use BLO.FindNthL. For automatic direction based on N sign, use BLO.FindNthX.
See also: