MiniRobotLanguage (MRL)
STR.Instr
Case-Sensitive String Search
Intention
This command performs a case-sensitive search for a specified string (P2) within a source string (P1), starting from an optional position (P3). The result is the 1-based position of the first match (or 0 if not found), placed on the Top of Stack (TOS) or in an optional variable (P4).
The search is case-sensitive (e.g., "Hello" does not match "hello"). If P3 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 |P3| bytes from end), but the result is always a 1-based position from the start of the string.
This is useful for text processing tasks requiring precise, case-sensitive substring searches, such as parsing structured data or validating user input, without modifying the source string.
Schematic (Forward and Reverse Search)
Source: HelloWorld
Search: World, Start=1 (LTR) --> Pos=6
Search --> |H|e|l|l|o|W|o|r|l|d|
^ (Found at 6)
Search: World, Start=-1 (RTL) --> Pos=6
Search <-- |d|l|r|o|W|o|l|l|e|H|
^ (Found at 6)
Syntax
STR.Instr|P1|P2[|P3][|P4]
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 (default 1). If negative, searches right-to-left from end or |P3| bytes from end; result is 1-based from start.
•P4 - (Optional Result Variable) Variable to store the result (position or 0). If omitted, result is pushed to TOS.
Examples
' Forward search to TOS
$$SRC=HelloWorld
$$SCH=World
STR.Instr|$$SRC|$$SCH|1
POP.$$RES
MBX.$$RES = 6
' Reverse search to variable
$$SRC=HelloWorldHello
$$SCH=Hello
STR.Instr|$$SRC|$$SCH|-1|$$POS
MBX.$$POS = 11 (last "Hello")
' No match
$$SRC=HelloWorld
$$SCH=xyz
STR.Instr|$$SRC|$$SCH|1|$$POS
MBX.$$POS = 0
ENR.
'---------------------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for STR.Instr (Case-Sensitive String Search)
' Purpose: Verify all features with JIV. for automated checks and a summary report.
' Tests forward/reverse searches, start positions (positive/negative), result to TOS/variable,
' edge cases (empty, no match, invalid start). Returns 1-based position or 0.
' Stack: TOS=position (1-based or 0) if P4 omitted.
' Uses short jumps (JIV.) and clear PRT. for readability.
' =================================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. FORWARD SEARCH TESTS
PRT. ===================================================
PRT. Test 1.1: Forward search for World in HelloWorld (pos=1, to TOS)
$$SRC=HelloWorld
$$SCH=World
STR.Instr|$$SRC|$$SCH|1
$$TOS=#tos#
JIV.$$TOS!1|Lab_Error1
POV.$$RES
$$EXP=6
JIV.$$RES!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
$$MSG= -> FAIL - Pos: $$RES (exp: $$EXP), Stack: $$TOS (exp: 1)
PRT.$$MSG
VIC.$$FAI
:Lab_Next1
STS.CLEAR
PRT. Test 1.2: Forward search for Hello in HelloWorld (pos=3, to variable)
$$SRC=HelloWorld
$$SCH=Hello
STR.Instr|$$SRC|$$SCH|3|$$POS
$$TOS=#tos#
JIV.$$TOS!0|Lab_Error2
$$EXP=0
JIV.$$POS!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
$$MSG= -> FAIL - Pos: $$POS (exp: $$EXP), Stack: $$TOS (exp: 0)
PRT.$$MSG
VIC.$$FAI
:Lab_Next2
STS.CLEAR
PRT. ===================================================
PRT. 2. REVERSE SEARCH TESTS
PRT. ===================================================
PRT. Test 2.1: Reverse search for Hello in HelloWorldHello (pos=-1, to variable)
$$SRC=HelloWorldHello
$$SCH=Hello
STR.Instr|$$SRC|$$SCH|-1|$$POS
$$TOS=#tos#
JIV.$$TOS!0|Lab_Error3
$$EXP=11
JIV.$$POS!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
$$MSG= -> FAIL - Pos: $$POS (exp: $$EXP), Stack: $$TOS (exp: 0)
PRT.$$MSG
VIC.$$FAI
:Lab_Next3
STS.CLEAR
PRT. Test 2.2: Reverse search for Hello in HelloWorldHello (pos=-5, to TOS)
$$SRC=HelloWorldHello
$$SCH=Hello
STR.Instr|$$SRC|$$SCH|-5
$$TOS=#tos#
JIV.$$TOS!1|Lab_Error4
POV.$$RES
$$EXP=1
JIV.$$RES!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
$$MSG= -> FAIL - Pos: $$RES (exp: $$EXP), Stack: $$TOS (exp: 1)
PRT.$$MSG
VIC.$$FAI
:Lab_Next4
STS.CLEAR
PRT. ===================================================
PRT. 3. NO MATCH TEST
PRT. ===================================================
PRT. Test 3.1: No match for xyz in HelloWorld (pos=1, to variable)
$$SRC=HelloWorld
$$SCH=xyz
STR.Instr|$$SRC|$$SCH|1|$$POS
$$TOS=#tos#
JIV.$$TOS!0|Lab_Error5
$$EXP=0
JIV.$$POS!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
$$MSG= -> FAIL - Pos: $$POS (exp: $$EXP), Stack: $$TOS (exp: 0)
PRT.$$MSG
VIC.$$FAI
:Lab_Next5
STS.CLEAR
PRT. Test 3.2: Case mismatch for hello in HelloWorld (pos=1, to TOS)
$$SRC=HelloWorld
$$SCH=hello
STR.Instr|$$SRC|$$SCH|1
$$TOS=#tos#
JIV.$$TOS!1|Lab_Error6
POV.$$RES
$$EXP=0
JIV.$$RES!$$EXP|Lab_Error6
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next6
:Lab_Error6
$$MSG= -> FAIL - Pos: $$RES (exp: $$EXP), Stack: $$TOS (exp: 1)
PRT.$$MSG
VIC.$$FAI
:Lab_Next6
STS.CLEAR
PRT. ===================================================
PRT. 4. EDGE CASE TESTS
PRT. ===================================================
PRT. Test 4.1: Empty source string (pos=1, to TOS)
$$SRC=
$$SCH=Hello
STR.Instr|$$SRC|$$SCH|1
$$TOS=#tos#
JIV.$$TOS!1|Lab_Error7
POV.$$RES
$$EXP=0
JIV.$$RES!$$EXP|Lab_Error7
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next7
:Lab_Error7
$$MSG= -> FAIL - Pos: $$RES (exp: $$EXP), Stack: $$TOS (exp: 1)
PRT.$$MSG
VIC.$$FAI
:Lab_Next7
STS.CLEAR
PRT. Test 4.2: Empty search string (pos=1, to variable)
$$SRC=HelloWorld
$$SCH=
STR.Instr|$$SRC|$$SCH|1|$$POS
$$TOS=#tos#
JIV.$$TOS!0|Lab_Error8
$$EXP=0
JIV.$$POS!$$EXP|Lab_Error8
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next8
:Lab_Error8
$$MSG= -> FAIL - Pos: $$POS (exp: $$EXP), Stack: $$TOS (exp: 0)
PRT.$$MSG
VIC.$$FAI
:Lab_Next8
STS.CLEAR
PRT. Test 4.3: Start position beyond source length (pos=20, to TOS)
$$SRC=Hello
$$SCH=Hello
STR.Instr|$$SRC|$$SCH|20
$$TOS=#tos#
JIV.$$TOS!1|Lab_Error9
POV.$$RES
$$EXP=0
JIV.$$RES!$$EXP|Lab_Error9
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next9
:Lab_Error9
$$MSG= -> FAIL - Pos: $$RES (exp: $$EXP), Stack: $$TOS (exp: 1)
PRT.$$MSG
VIC.$$FAI
:Lab_Next9
STS.CLEAR
PRT. Test 4.4: Negative start position beyond source length (pos=-20, to variable)
$$SRC=Hello
$$SCH=Hello
STR.Instr|$$SRC|$$SCH|-20|$$POS
$$TOS=#tos#
JIV.$$TOS!0|Lab_Error10
$$EXP=0
JIV.$$POS!$$EXP|Lab_Error10
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next10
:Lab_Error10
$$MSG= -> FAIL - Pos: $$POS (exp: $$EXP), Stack: $$TOS (exp: 0)
PRT.$$MSG
VIC.$$FAI
:Lab_Next10
STS.CLEAR
PRT. Test 4.5: Binary data search (pos=1, to TOS)
$$SRC=$crlf$Hello$sp$World$tab$
$$SCH=World
STR.Instr|$$SRC|$$SCH|1
$$TOS=#tos#
JIV.$$TOS!1|Lab_Error11
POV.$$RES
$$EXP=9
JIV.$$RES!$$EXP|Lab_Error11
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next11
:Lab_Error11
$$MSG= -> FAIL - Pos: $$RES (exp: $$EXP), Stack: $$TOS (exp: 1)
PRT.$$MSG
VIC.$$FAI
:Lab_Next11
STS.CLEAR
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
JIV.$$FAI=0|Lab_Success
$$MSG=FAILURE: $$FAI of $$TOT tests failed.
MBX.$$MSG|Test Result|16
JMP.Lab_End
:Lab_Success
MBX.SUCCESS: All tests passed!|Test Result|64
:Lab_End
ENR.
Remarks
-Case-sensitive search; "Hello" does not match "hello".
-P3=0 defaults to 1 (LTR start).
-Negative P3 inserts right-to-left from end or |P3| bytes from end; -1 would be Insert after last character, -2 insert after pre-last character.
-If search string longer than remaining source, returns 0.
-Binary-safe for P1 and P2; no special/system vars expanded.
-For case-insensitive search, use STR.CiInstr.
Limitations
-No wildcard or pattern support; use STR.FindAny for patterns.
-No overlap handling; finds first non-overlapping occurrence.
See also: