MiniRobotLanguage (MRL)
STR.Insert
Insert String at Specified Position
Intention
This command inserts a string (P3) into a source string variable (P1) at a specified position (P2).
The source string is modified in-place, and the command does not return a value to the stack. The insertion increases the length of the source string.
The insert position (P2) is 1-based. If P2 is 1 or less, the string is inserted at the start. If P2 is greater than the source string length, the string is appended to the end.
This command is slower than STR.OVERWRITE for large strings, as it shifts subsequent bytes.
The command is binary-safe for both P1 and P3, with variables resolved only once to prevent unwanted expansion of special folders or system variables.
Schematic
Source: 1234589
Insert: 67 at pos=6 --> 123456789
|1|2|3|4|5|6|7|8|9|
^ (Insert 67 before pos 6)
Syntax
STR.Insert|P1|P2|P3
Parameter Explanation
•P1 - (Source String) Variable containing the string to modify in-place. Must be a variable.
•P2 - (Insert Position) Numeric, 1-based position to insert before. If ≤1, insert counts from right; if > length of P1, appends to end.
•P3 - (Insert String) String to insert into P1. Variable or literal.
Examples
' Insert at position 6
VAR.$$SRC=1234589
VAR.$$NEW=67
STR.Insert|$$SRC|6|$$NEW
PRT. $$SRC = 123456789
' Insert at start (pos=1)
VAR.$$SRC=abc
VAR.$$NEW=xyz
STR.Insert|$$SRC|1|$$NEW
PRT. $$SRC = xyzabc
' Append to end (pos > length)
VAR.$$SRC=abc
VAR.$$NEW=xyz
STR.Insert|$$SRC|10|$$NEW
MBX.$$SRC = abcxyz
ENR.
'-------------------------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for STR.Insert (Insert String at Specified Position)
' Purpose: Verify all features with JIV. for automated checks and a summary report.
' Tests insertion at various positions (start, middle, end), edge cases (empty strings, invalid positions),
' and binary data. Modifies P1 in-place, no stack output.
' Uses short jumps (JIV.) and clear PRT. for readability.
' =================================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. INSERTION POSITION TESTS
PRT. ===================================================
PRT. Test 1.1: Insert 67 at pos=6 in 1234589
VAR.$$SRC=1234589
VAR.$$NEW=67
STR.Insert|$$SRC|6|$$NEW
$$EXP=123456789
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
STS.CLEAR
PRT. Test 1.2: Insert xyz at pos=1 in abc (start)
VAR.$$SRC=abc
VAR.$$NEW=xyz
STR.Insert|$$SRC|1|$$NEW
$$EXP=xyzabc
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
STS.CLEAR
PRT. Test 1.3: Insert xyz at pos=10 in abc (append)
VAR.$$SRC=abc
VAR.$$NEW=xyz
STR.Insert|$$SRC|10|$$NEW
$$EXP=abcxyz
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
STS.CLEAR
PRT. ===================================================
PRT. 2. EDGE CASE TESTS
PRT. ===================================================
PRT. Test 2.1: Insert empty string at pos=3 in abc
VAR.$$SRC=abc
VAR.$$NEW=
STR.Insert|$$SRC|3|$$NEW
$$EXP=abc
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
STS.CLEAR
PRT. Test 2.2: Insert xyz in empty string at pos=1
VAR.$$SRC=
VAR.$$NEW=xyz
STR.Insert|$$SRC|1|$$NEW
$$EXP=xyz
JIV.$$SRC!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next5
STS.CLEAR
PRT. Test 2.3: Insert xyz at pos=0 in abc (start)
VAR.$$SRC=abc
VAR.$$NEW=xyz
STR.Insert|$$SRC|0|$$NEW
$$EXP=abcxyz
JIV.$$SRC!$$EXP|Lab_Error6
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next6
:Lab_Error6
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next6
STS.CLEAR
PRT. Test 2.4: Insert xyz at pos=-1 in abc (count from right)
VAR.$$SRC=abc
VAR.$$NEW=xyz
STR.Insert|$$SRC|-1|$$NEW
$$EXP=abcxyz
JIV.$$SRC!$$EXP|Lab_Error7
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next7
:Lab_Error7
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next7
STS.CLEAR
PRT. ===================================================
PRT. 3. BINARY DATA TEST
PRT. ===================================================
PRT. Test 3.1: Insert $sp$World$tab$ at pos=4 in $crlf$Hello
VAR.$$SRC=$crlf$ *
VAR.$$NEW=$sp$World$tab$
STR.Insert|$$SRC|5|$$NEW
VAR.$$EXP=$crlf$ $sp$World$tab$ *
JIV.$$SRC!$$EXP|Lab_Error8
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next8
:Lab_Error8
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next8
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
-P1 must be a variable, as it is modified in-place.
-P2 is resolved numerically; non-numeric values may cause errors.
-Binary-safe for P1 and P3; variables resolved only once to avoid unwanted expansion.
-Slower than STR.OVERWRITE for large strings due to byte shifting.
-No stack output; use MBX. or similar to inspect P1 after modification.
Limitations
-P2 must be numeric; invalid values may cause undefined behavior.
-No support for negative positions; use positive 1-based positions.
-No undo mechanism; back up P1 before insertion if needed.
See also:
SBD. - String between Delimiter
SBM. - String between Delimiter-Multiple