MiniRobotLanguage (MRL)
STR.SetMidToB
Replace a Substring in a String from Start to End Position
Replace a specified range of characters in a string with a new substring.
Intention
The STR.SetMidToB command replaces a portion of a source string (P1) from a start position (P2) to an end position (P3) with a replacement string (P4). The source string is modified directly. Positions can be positive (1-based, counting from the start) or negative (counting from the end). If the end position is omitted, the replacement extends to the end of the string. This command is binary-safe, resolving variables in the source and replacement strings only once, making it suitable for text and binary data manipulation.
•Start and end positions are 1-based for positive values; negative values count from the end (e.g., -1 is the last character).
•If P3 is omitted, replacement extends to the end of the string.
•If P2 equals P3, the replacement string is inserted at P2.
•Invalid positions (e.g., P2 = 0 or beyond string length) result in no change to the source string.
Schematic (Substring Replacement)
Source String: ABCDEFGHIJK
Positions: 123456789...
Command: STR.SetMidToB|$$SRC|5|8|WXYZ
Result: ABCDWXYZIJK
^^^^ (replaced EFGH with WXYZ)
Syntax
STR.SetMidToB|P1|P2[|P3]|P4
Parameter Explanation
•P1 - (Source and Destination Variable) The string to modify. Replaced substring is stored back in P1.
•P2 - (Start Position) Numeric value (positive or negative) specifying the 1-based start position. Resolved to an integer.
•P3 - (Optional End Position) Numeric value (positive or negative) specifying the 1-based end position. If omitted, replacement extends to the end of the string. Resolved to an integer.
•P4 - (Replacement String) The string to insert in place of the specified range. Can be empty or shorter/longer than the replaced range.
Examples
'***********************************
' Example 1: Replace substring (positions 5-8)
'***********************************
VAR.$$SRC=ABCDEFGHIJK
STR.SetMidToB|$$SRC|5|8|WXYZ
' $$SRC will contain "ABCDWXYZIJK" (replaces "EFGH" with "WXYZ")
MBX.$$SRC
ENR.
'***********************************
' Example 2: Replace to end of string
'***********************************
VAR.$$SRC=ABCDEFGHIJK
STR.SetMidToB|$$SRC|7||XYZ
' $$SRC will contain "ABCDEFXYZJK" (replaces "GHI" with "XYZ")
MBX.$$SRC
ENR.
'***********************************
' Example 3: Negative positions
'***********************************
VAR.$$SRC=ABCDEFGHIJK
STR.SetMidToB|$$SRC|-5|-2|123
' $$SRC will contain "ABCDEF123JK" (replaces "GHIJ" with "123")
MBX.$$SRC
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for STR.SetMidToB
' Purpose: Verify functionality with JIV. for automated checks.
' Tests positive/negative positions, end omission, edge cases.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Replace substring (positions 5-8)
STS.CLEAR
$$SRC=ABCDEFGHIJK
STR.SetMidToB|$$SRC|5|8|WXYZ
$$EXP=ABCDWXYZIJK
JIV.$$SRC!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'--------------------------------------
:Lab_Next1
PRT. Test 1.2: Replace to end of string
STS.CLEAR
$$SRC=ABCDEFGHIJK
STR.SetMidToB|$$SRC|7||XYZ
$$EXP=ABCDEFXYZJK
JIV.$$SRC!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
GSB.Test
'--------------------------------------
:Lab_Next2
PRT. Test 1.3: Negative positions
STS.CLEAR
$$SRC=ABCDEFGHIJK
STR.SetMidToB|$$SRC|-5|-2|123
$$EXP=ABCDEF123JK
JIV.$$SRC!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
GSB.Test
'--------------------------------------
:Lab_Next3
PRT. Test 1.4: Short replacement string
STS.CLEAR
$$SRC=ABCDEFGHIJK
STR.SetMidToB|$$SRC|5|8|XY
$$EXP=ABCDXYGHIJK
JIV.$$SRC!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
GSB.Test
'--------------------------------------
:Lab_Next4
PRT. Test 1.5: Invalid start position (zero)
STS.CLEAR
$$SRC=ABCDEFGHIJK
STR.SetMidToB|$$SRC|0|5|XYZ
$$EXP=ABCDEFGHIJK
JIV.$$SRC!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
GSB.Test
'--------------------------------------
:Lab_Next5
PRT. Test 1.6: Equal positions (P2 = P3)
STS.CLEAR
$$SRC=ABCDEFGHIJK
STR.SetMidToB|$$SRC|5|5|XYZ
$$EXP=ABCDXFGHIJK
JIV.$$SRC!$$EXP|Lab_Error6
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next6
:Lab_Error6
GSB.Test
:Lab_Next6
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
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.
:Test
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
RET.
Remarks
- Variables in P1 and P4 are resolved only once, ensuring binary safety (e.g., for null characters or special sequences).
- P2 and P3 are resolved to integers; non-integer values are rounded down.
- Negative positions allow flexible manipulation from the string's end.
- Efficient for both text and binary data, with no length restrictions on P4.
Limitations
- P2 must be non-zero; zero or invalid positions prevent replacement.
- No option to store the result in a separate variable; P1 is always modified.
- Case-sensitive; no case-insensitive variant available.
See also: