|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > String commands > !STR.- String Command > String Replace Commands > String Operations |
MiniRobotLanguage (MRL)
STR.CIReplace
Performs Case-Insensitive Replacement or Removal in a String
After execution, $$SRC is modified in place. On TOS you will find the number of replacements made (0 if none).
Intention
This command performs a case-insensitive search and replace operation within a source string. 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 all occurrences of the search string in the source.
The command modifies the source string variable (P1) directly in place. After execution, it pushes a single value to the stack: the number of replacements made (0 if no matches found or if the search string is empty).
If the optional replacement string (P3) is omitted, the command removes all occurrences of the search string from the source (equivalent to replacing with an empty string). This is useful for cleaning or filtering strings based on keywords without regard to case, while maintaining efficiency for multiple replacements in a single call.
Syntax
STR.CIReplace|P1|P2[|P3]
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 - (Search String) The substring to search for and replace/remove. Can be a variable (e.g., $$REP) or literal. Search is case-insensitive.
•P3 - (Replacement String, Optional) The string to insert in place of each match. Can be a variable (e.g., $$WIT) or literal. If omitted, matches are removed (replaced with empty string). The casing of P3 is preserved in the result.
Examples
' Basic example with replacement
: $$SRC=Hello World hello
: $$REP=hello
: $$WIT=Hi
STR.CIReplace|$$SRC|$$REP|$$WIT
DMP.6
MBX. $$SRC is now "Hi World Hi" | Stack (TOS): 2 (replacements made)
ENR.
'--------------------------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for STR.CIReplace (Case-Insensitive Replace/Remove)
' Purpose: Verify all features using IVV. for automated checks
' and a final summary report. Tests basic replace, remove, multiple occurrences, case-insens,
' no match, edge cases (empty strings, long search).
' Behavior: Modifies P1 in place, pushes count of replacements (TOS).
' =================================================================
' --- Initialize Pass/Fail counters ---
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. BASIC REPLACE TEST
PRT. ===================================================
$$SRC=Hello World
$$REP=hello
$$WIT=Hi
PRT. Test 1.1: Basic case-insensitive replace...
STR.CIReplace|$$SRC|$$REP|$$WIT
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=1
IVV.$$CNT=$$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 count: $$EXP, Actual: $$CNT
PRT.$$MSG
VIC.$$FAI
EIF.
ELS.
$$MSG= -> FAIL - Expected stack size: 1, Actual: $$TOS
PRT.$$MSG
VIC.$$FAI
EIF.
STS.CLEAR
PRT. ===================================================
PRT. 2. MULTIPLE OCCURRENCES TEST
PRT. ===================================================
$$SRC=Hello hello HELLO
$$REP=hello
$$WIT=Hi
PRT. Test 2.1: Replace all occurrences...
STR.CIReplace|$$SRC|$$REP|$$WIT
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=3
IVV.$$CNT=$$EXP
$$EXP=Hi Hi 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 count: $$EXP, Actual: $$CNT
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 P3) TEST
PRT. ===================================================
$$SRC=Hello World Hello
$$REP=hello
PRT. Test 3.1: Remove occurrences (no WIT)...
STR.CIReplace|$$SRC|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=2
IVV.$$CNT=$$EXP
$$EXP= 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 count: $$EXP, Actual: $$CNT
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
$$REP=Zebra
$$WIT=Animal
PRT. Test 4.1: No match (replace)...
STR.CIReplace|$$SRC|$$REP|$$WIT
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=0
IVV.$$CNT=$$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 count: $$EXP, Actual: $$CNT
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.CIReplace|$$SRC|$$REP
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=0
IVV.$$CNT=$$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 count: $$EXP, Actual: $$CNT
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=
$$REP=hello
$$WIT=Hi
STR.CIReplace|$$SRC|$$REP|$$WIT
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=0
IVV.$$CNT=$$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 count: $$EXP, Actual: $$CNT
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
$$REP=
$$WIT=Hi
STR.CIReplace|$$SRC|$$REP|$$WIT
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=0
IVV.$$CNT=$$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 count: $$EXP, Actual: $$CNT
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
$$REP=ThisIsVeryLongString
$$WIT=Short
STR.CIReplace|$$SRC|$$REP|$$WIT
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=0
IVV.$$CNT=$$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 count: $$EXP, Actual: $$CNT
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
$$REP=hello
$$WIT=
STR.CIReplace|$$SRC|$$REP|$$WIT
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=2
IVV.$$CNT=$$EXP
$$EXP= 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 count: $$EXP, Actual: $$CNT
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: Mixed case and punctuation...
$$SRC=Hello, WORLD! hello.
$$REP=hello
$$WIT=Hi
STR.CIReplace|$$SRC|$$REP|$$WIT
$$TOS=#tos#
IVV.$$TOS=1
POV.$$CNT
$$EXP=1
IVV.$$CNT=$$EXP
$$EXP=Hi, 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 count: $$EXP, Actual: $$CNT
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 positions), but replacements preserve original casing.
-Replaces all occurrences from left to right; overlapping matches are not supported (e.g., replacing "xx" in "xxx" replaces first "xx" to leave "x").
-Stack pushes: Number of replacements (TOS, 0 if none).
-If P3 is omitted or empty, acts as remove operation.
-If source or search is empty, no changes occur, pushes 0.
-For case-sensitive replacement, use STR.Replace or custom macros.
Limitations
-Does not support wildcards, regex, or limiting to N replacements; for advanced patterns, combine with STR.FindNthX or loops.
-Always case-insensitive; no flag for case-sensitive mode. Uses PowerBASIC INSTR after UCASE conversion for positions, then MID$ for replacement in original.
-Modifies variable in place; to preserve original, copy to temp variable first.
See also: