MiniRobotLanguage (MRL)
STR.SetMidTo
Replace a Substring in a String from a Start to an End Position, Adjusting String Length
Replace a substring from a specified start to end position, modifying the source string's length as needed.
Intention
The STR.SetMidTo command replaces a substring within a source string (P1) from a start position (P2) to an optional end position (P3) with a new string (P4).
Unlike BASIC's MID$ statement, which preserves the original string length, this command adjusts the length of the source string based on the length of P4.
This is useful for editing text, modifying data segments, or handling binary data where precise control over string length is needed.
The command is binary-safe, resolving variables in P1 and P4 only once to prevent unwanted substitutions.
•Positions are 1-based; negative values count backwards from the end of the string (-1 is the last character).
•If P3 is omitted, the replacement extends to the end of the string.
•Invalid positions (e.g., zero or beyond string length) or equal positions (P2 = P3) result in no change to the source string.
Visual Example
Replacing a Substring with Length Adjustment
Source String: ABCDEFGHIJK
|A|B|C|D|E|F|G|H|I|J|K|
^ ^
P2=5 P3=8
Replacement: WXYZ
Result String: ABCDWXYZIJK
Syntax
STR.SetMidTo|P1|P2[|P3]|P4
Parameter Explanation
•P1 - (Source and Destination Variable, Text) The string to modify. Updated with the result.
•P2 - (Start Position, Numeric) The 1-based position where replacement begins. Negative values count from the end (-1 is the last character).
•P3 - (Optional End Position, Numeric) The 1-based position where replacement ends. Negative values count from the end. Defaults to string end if omitted.
•P4 - (Replacement String, Text) The string to insert in place of the substring from P2 to P3.
Examples
'***********************************
' Example 1: Replace substring with new string
'***********************************
VAR.$$SRC=ABCDEFGHIJK
STR.SetMidTo|$$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.SetMidTo|$$SRC|7||XYZ
' $$SRC will contain "ABCDEFXYZ" (replaces from position 7 to end with "XYZ")
MBX.$$SRC
ENR.
'***********************************
' Example 3: Negative position from end
'***********************************
VAR.$$SRC=ABCDEFGHIJK
STR.SetMidTo|$$SRC|-5|-2|123
' $$SRC will contain "ABCDEF123K" (replaces "GHIJ" with "123")
MBX.$$SRC
ENR.
'***********************************
' Example 4: Binary data replacement
'***********************************
VAR.$$SRC=$crlf$ABCDEF$crlf$
STR.SetMidTo|$$SRC|3|6|$tab$XYZ
' $$SRC will contain CRLF followed by "XYZ" followed by CRLF
MBX.$$SRC
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for STR.SetMidTo
' 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.SetMidTo|$$SRC|5|8|WXYZ
$$EXP=ABCDWXYZIJK
JIV.$$SRC!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next1
PRT. Test 1.2: Replace to end (P3 omitted)
$$SRC=ABCDEFGHIJK
STR.SetMidTo|$$SRC|7||XYZ
$$EXP=ABCDEFXYZ
JIV.$$SRC!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next2
PRT. Test 1.3: Negative positions
STS.CLEAR
$$SRC=ABCDEFGHIJK
STR.SetMidTo|$$SRC|-5|-2|123
$$EXP=ABCDEF123K
JIV.$$SRC!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next3
PRT. Test 1.4: Empty replacement string
STS.CLEAR
$$SRC=ABCDEFGHIJK
STR.SetMidTo|$$SRC|5|8|
$$EXP=ABCDIJK
JIV.$$SRC!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next4
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.
Remarks
- Variables in P1 and P4 are resolved only once, ensuring safety for binary data (e.g., null characters).
- P2 and P3 are resolved to integers; non-integer values are rounded down.
- If P2 > P3, the positions are swapped to ensure correct replacement.
- Unlike PowerBASIC's MID$ statement, which preserves string length, STR.SetMidTo adjusts the string length based on P4.
- Efficient for modifying large strings or binary data due to direct in-place replacement.
Limitations
- P2 and P3 must be valid positions (non-zero and within string length); invalid values prevent modification.
- If P2 equals P3, the replacement string is inserted at P2, increasing the string length.
- No option to store the result in a separate variable; P1 is always modified.
- Case-sensitive; no case-insensitive variant available.
See also: