|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > String commands > !STR.- String Command > Instring - Find Commands > String Operations |
MiniRobotLanguage (MRL)
STR.RevInstr
Reverse String Search with Direction Control
Intention
This command performs a reverse (right-to-left) search for a specified string (P2) within a source string (P1), starting from an optional position (P3) with case sensitivity control (P4). The result is the 1-based position of the last match (or 0 if not found), placed on the Top of Stack (TOS) or in an optional variable (P5).
By default, the search is performed from right to left (reverse). If P3 is positive, it searches right-to-left starting from that position from the right. If negative, it searches left-to-right starting from |P3| position from the left. P3=0 defaults to 1 (start from the end).
Case sensitivity can be controlled via P4 (0=case sensitive, default; 1=case insensitive). This is useful for finding the last occurrence of a substring, parsing file extensions, or processing data from the end.
Schematic (Reverse and Forward Search)
Source: HelloWorldHello
Search: Hello, Start=1 (RTL) --> Pos=11
Search <-- |H|e|l|l|o|W|o|r|l|d|H|e|l|l|o|
^ (Found at 11)
Search: Hello, Start=-1 (LTR) --> Pos=1
Search --> |H|e|l|l|o|W|o|r|l|d|H|e|l|l|o|
^ (Found at 1)
Syntax
STR.RevInstr|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 - (Optional Start Position) Numeric, 1-based. If positive, searches right-to-left from that position from the right. If negative, searches left-to-right from |P3| position from the left. 0 defaults to 1.
•P4 - (Optional Case Sensitivity) 0=Case sensitive (default), 1=Case insensitive.
•P5 - (Optional Result Variable) Variable to store the result (position or 0). If omitted, result is pushed to TOS.
Examples
' Reverse search (default) to TOS
$$SRC=HelloWorldHello
$$SCH=Hello
STR.RevInstr|$$SRC|$$SCH
POP.$$RES
MBX.$$RES = 11 (last "Hello")
' Reverse search with start position
$$SRC=HelloWorldHello
$$SCH=Hello
STR.RevInstr|$$SRC|$$SCH|5|$$POS
MBX.$$POS = 1 (search within first 5 chars from right)
' Forward search with negative start position
$$SRC=HelloWorldHello
$$SCH=Hello
STR.RevInstr|$$SRC|$$SCH|-1|0|$$POS
MBX.$$POS = 1 (first "Hello" from left)
' Case insensitive reverse search
$$SRC=HelloWorldHELLO
$$SCH=hello
STR.RevInstr|$$SRC|$$SCH|0|1|$$POS
MBX.$$POS = 11 (finds "HELLO" case insensitive)
' No match
$$SRC=HelloWorld
$$SCH=xyz
STR.RevInstr|$$SRC|$$SCH|1|0|$$POS
MBX.$$POS = 0
ENR.
'---------------------------------------------------------
'==================================================
' STR.RNInstr - Self-Running Test (5-char vars)
'==================================================
' =================================================================
' SELF-VALIDATING TEST SCRIPT for STR.RNInstr (Reverse Nth String Search)
' Purpose: Verify all features using IVV. for automated checks
' and a final summary report. Tests basic reverse matches, start-from-right,
' case-insensitive, overlap, search limits, edge cases.
' Stack: Always pushes 1 item: TOS = position (1-based from start, 0 if not found).
' =================================================================
' --- Initialize Pass/Fail counters ---
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. BASIC REVERSE SEARCH TESTS
PRT. ===================================================
$$SRC=HelloWorldHello
PRT. Test 1.1: Last "Hello" (N=1)...
STR.RNInstr|$$SRC|Hello|1|0|0|0|1
POP.$$POS
$$EXP=11
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. Test 1.2: Second-to-last "Hello" (N=2)...
PRT. ===================================================
STR.RNInstr|$$SRC|Hello|2|0|0|0|1
POP.$$POS
$$EXP=1
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. 2. START-FROM-RIGHT TESTS
PRT. ===================================================
PRT. Test 2.1: Start from 3rd char from end in "abcdefg", find "c"...
$$SRC=abcdefg
STR.RNInstr|$$SRC|c|1|0|0|0|3
POP.$$POS
$$EXP=3
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. Test 2.2: Start from end (P7=1) should match full scan...
PRT. ===================================================
STR.RNInstr|$$SRC|c|1|0|0|0|1
POP.$$POS
$$EXP=3
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. 3. CASE-INSENSITIVE + OVERLAP TESTS
PRT. ===================================================
PRT. Test 3.1: Case-insensitive + overlapping — 3rd "A" from end in "AbAbAbA"...
$$SRC=AbAbAbA
STR.RNInstr|$$SRC|A|3|0|1|1|1
POP.$$POS
$$EXP=3
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. Test 3.2: Overlap vs non-overlap in "aaaa" (1-char pattern)...
PRT. ===================================================
$$SRC=aaaa
STR.RNInstr|$$SRC|a|2|0|0|1|1
POP.$$POS
$$EXP=3
IVV.$$POS=$$EXP
PRT. -> PASS (overlap)
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. Test 3.3: Non-overlap in "aaaa" (same as overlap for 1-char)...
PRT. ===================================================
STR.RNInstr|$$SRC|a|2|0|0|0|1
POP.$$POS
$$EXP=3
IVV.$$POS=$$EXP
PRT. -> PASS (non-overlap = 3 for 1-char)
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. 4. SEARCH LIMIT (P4) TESTS
PRT. ===================================================
PRT. Test 4.1: Limit search to first 10 chars in "HelloWorldHello"...
$$SRC=HelloWorldHello
STR.RNInstr|$$SRC|Hello|1|10|0|0|1
POP.$$POS
$$EXP=1
IVV.$$POS=$$EXP
PRT. -> PASS (only first "Hello" in 1..10)
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. Test 4.2: Limit too small for any match...
PRT. ===================================================
STR.RNInstr|$$SRC|Hello|1|4|0|0|1
$$TOS=#tos#
POP.$$POS
$$EXP=0
IVV.$$POS=$$EXP
PRT. -> PASS (no match in 1..4)
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. 5. NO MATCH & EDGE CASE TESTS
PRT. ===================================================
PRT. Test 5.1: No match (simple)...
$$SRC=Hello
STR.RNInstr|$$SRC|xyz|1|0|0|0|1
POP.$$POS
$$EXP=0
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. Test 5.2: Empty source string...
PRT. ===================================================
$$SRC=
STR.RNInstr|$$SRC|test|1|0|0|0|1
POP.$$POS
$$EXP=0
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. Test 5.3: Empty search string...
PRT. ===================================================
$$SRC=Hello
STR.RNInstr|$$SRC||1|0|0|0|1
POP.$$POS=#pop#
$$EXP=0
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. Test 5.4: Pattern longer than source...
PRT. ===================================================
$$SRC=Hi
STR.RNInstr|$$SRC|Hello|1|0|0|0|1
POP.$$POS
$$EXP=0
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. 6. ADDITIONAL VALIDATION TESTS
PRT. ===================================================
PRT. Test 6.1: Match at very end of string...
$$SRC=EndsWithHello
STR.RNInstr|$$SRC|Hello|1|0|0|0|1
POP.$$POS
$$EXP=9
IVV.$$POS=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. Test 6.2: Negative N (should default to 1)...
PRT. ===================================================
STR.RNInstr|$$SRC|Hello|-5|0|0|0|1
POP.$$POS
$$EXP=9
IVV.$$POS=$$EXP
PRT. -> PASS (N<1 ? N=1)
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. Test 6.3: Start-from-right beyond string length...
PRT. ===================================================
$$SRC=Hi
STR.RNInstr|$$SRC|i|1|0|0|0|10
POP.$$POS
$$EXP=2
IVV.$$POS=$$EXP
PRT. -> PASS (clamped to end)
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
PRT. ===================================================
PRT. TEST SUMMARY
PRT. ===================================================
CAL.$$TOT=$$PAS+$$FAI
$$MSG=Total Tests: $$TOT
PRT.$$MSG
$$MSG=Passed: $$PAS
PRT.$$MSG
$$MSG=Failed: $$FAI
PRT.$$MSG
' --- Display final result message box ---
IVV.$$FAI=0
MBX.SUCCESS: All tests passed!|Test Result|64
ELS.
$$MSG=FAILURE: $$FAI of $$TOT tests failed.
MBX.$$MSG|Test Result|16
EIF.
ENR.
'==================================================
' End of Tests
'==================================================
Remarks
-Default search direction is right-to-left (reverse).
-P3=0 defaults to 1 (start from end).
-Positive P3 searches right-to-left starting from position P3 from the right.
-Negative P3 searches left-to-right starting from position |P3| from the left.
-P4=0 for case sensitive (default), P4=1 for case insensitive.
-If search string longer than remaining source, returns 0.
-Binary-safe for P1 and P2; no special/system vars expanded.
Limitations
-No wildcard or pattern support; use STR.FindAny for patterns.
-No overlap handling; finds first non-overlapping occurrence in specified direction.
See also: