MiniRobotLanguage (MRL)
STR.SICiReplace
Performs Case-Insensitive Single Occurrence Replacement or Removal in a String Starting from a Specified Position
After execution, $$SRC is modified in place. On TOS you will find the starting position of the match (1-based) where replacement occurred, or 0 if no match found.
Intention
This command performs a case-insensitive search and replace operation for a single occurrence within a source string, starting from a specified position. The search for the substring to replace is case-insensitive (e.g., "Hello" matches "hello", "HELLO", or mixed cases via internal UCASE conversion before INSTR), but the replacement preserves the original casing of both the non-matching parts of the source string and the replacement string itself. It replaces only the first matching occurrence after the starting position.
The command modifies the source string variable (P1) directly in place. After execution, it pushes a single value to the stack: the 1-based starting position in the source where the match was found and replaced (or 0 if no match found).
If the optional replacement string (P4) is omitted, the command removes the first matching occurrence from the source (equivalent to replacing with an empty string). This is useful for targeted editing or cleaning of strings based on keywords without regard to case, starting from a specific point, and handling only one instance at a time.
Syntax
STR.SICiReplace|P1|P2|P3[|P4]
Parameter Explanation
•P1 - (Source String Variable) The variable containing the string to modify. Must be a variable (e.g., $$SRC). The command updates this variable in place with the result.
•P2 - (Starting Position) The 1-based position in the source string from which to start the search. Can be a variable (e.g., $$STA) or literal integer.
•P3 - (Search String) The substring to search for and replace/remove. Can be a variable (e.g., $$SEA) or literal. Search is case-insensitive.
•P4 - (Replacement String, Optional) The string to insert in place of the match. Can be a variable (e.g., $$REP) or literal. If omitted, the match is removed (replaced with empty string). The casing of P4 is preserved in the result.
Examples
' Basic example with replacement
: $$SRC=Hello World hello
: $$STA=1
: $$SEA=hello
: $$REP=Hi
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
DMP.6
MBX. $$SRC is now "Hi World hello" | Stack (TOS): 1 (position of replacement)
ENR.
'--------------------------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for STR.SICiReplace (Case-Insensitive Single Replace/Remove)
' Purpose: Verify all features using IVV. for automated checks
' and a final summary report. Tests basic replace, remove, starting pos, case-insens,
' no match, edge cases (empty strings, invalid start, long search).
' Behavior: Modifies P1 in place, pushes position of replacement (TOS, 0 if none).
' =================================================================
' --- Initialize Pass/Fail counters ---
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. BASIC REPLACE TEST
PRT. ===================================================
$$SRC=Hello World
$$STA=1
$$SEA=hello
$$REP=Hi
PRT. Test 1.1: Basic case-insensitive single replace from start...
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=1
IVV.$$POS=$$EXP
$$EXP=Hi World
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 2. SINGLE OCCURRENCE WITH START POS TEST
PRT. ===================================================
$$SRC=Hello hello HELLO
$$STA=7
$$SEA=hello
$$REP=Hi
PRT. Test 2.1: Replace single occurrence after start pos...
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=7
IVV.$$POS=$$EXP
$$EXP=Hello Hi HELLO
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 3. REMOVE (NO P4) TEST
PRT. ===================================================
$$SRC=Hello World Hello
$$STA=1
$$SEA=hello
PRT. Test 3.1: Remove single occurrence (no REP)...
STR.SICiReplace|$$SRC|$$STA|$$SEA
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=1
IVV.$$POS=$$EXP
$$EXP= World Hello
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 4. NO MATCH TEST
PRT. ===================================================
$$SRC=Hello World
$$STA=1
$$SEA=Zebra
$$REP=Animal
PRT. Test 4.1: No match (replace)...
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=0
IVV.$$POS=$$EXP
$$EXP=Hello World
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 4.2: No match (remove)...
STR.SICiReplace|$$SRC|$$STA|$$SEA
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=0
IVV.$$POS=$$EXP
$$EXP=Hello World
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 5. EDGE CASE TESTS
PRT. ===================================================
PRT. Test 5.1: Empty source string...
$$SRC=
$$STA=1
$$SEA=hello
$$REP=Hi
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=0
IVV.$$POS=$$EXP
$$EXP=
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 5.2: Empty search string...
$$SRC=Hello World
$$STA=1
$$SEA=
$$REP=Hi
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=0
IVV.$$POS=$$EXP
$$EXP=Hello World
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 5.3: Search longer than source...
$$SRC=Hi
$$STA=1
$$SEA=ThisIsVeryLongString
$$REP=Short
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=0
IVV.$$POS=$$EXP
$$EXP=Hi
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 5.4: Empty replacement (explicit)...
$$SRC=Hello World Hello
$$STA=7
$$SEA=world
$$REP=
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=7
IVV.$$POS=$$EXP
$$EXP=Hello Hello
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 5.5: Invalid start position (beyond length)...
$$SRC=Hello
$$STA=10
$$SEA=hello
$$REP=Hi
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=0
IVV.$$POS=$$EXP
$$EXP=Hello
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. Test 5.6: Match at exact start position...
$$SRC=hello World
$$STA=1
$$SEA=HELLO
$$REP=Hi
STR.SICiReplace|$$SRC|$$STA|$$SEA|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$POS
$$EXP=1
IVV.$$POS=$$EXP
$$EXP=Hi World
IVV.$$SRC=$$EXP
PRT. -> PASS
VIC.$$PAS
ELS.
$$MSG= -> FAIL - Expected SRC: $$EXP, Actual: $$SRC
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected pos: $$EXP, Actual: $$POS
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
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 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.
Remarks
-The search is always case-insensitive (via internal UCASE on source and search before finding position), but replacements preserve original casing.
-Replaces only the first occurrence after the starting position; for multiple, use loops or STR.CIReplace.
-Stack pushes: Position of match (TOS, 1-based, 0 if none).
-If P4 is omitted or empty, acts as remove operation for single match.
-Starting position is 1-based; if > length of source or invalid, returns 0 with no change.
-For case-sensitive replacement, use custom macros with STR.Find.
Limitations
-Limited to single occurrence; for all occurrences, use STR.CIReplace.
-Does not support wildcards, regex; for advanced patterns, combine with STR.FindNthX.
-Always case-insensitive; no flag for case-sensitive mode. Uses PowerBASIC INSTR after UCASE for position, then MID$ for replacement in original.
See also: