MiniRobotLanguage (MRL)
STR.SetRightB
Replace a Specified Number of Characters at the Right End of a String (BASIC-Style)
Overwrite the rightmost characters of a string with a new substring, maintaining the original string length.
Intention
The STR.SetRightB command (aliased as STR.SerB) replaces a specified number of characters at the right end of a source string (P1) with a new string (P3), as defined by the count (P2). This command uses a BASIC-style algorithm, similar to PowerBasic’s MID$ statement, ensuring the string length remains unchanged. It is ideal for in-place modifications in fixed-width buffers, binary data manipulation, or formatting tasks where maintaining the original string length is critical.
The command overwrites the last P2 characters of P1 with P3. If P3 is longer than P2, it is truncated; if shorter, the remaining characters in the target range remain unchanged. The modified string is written back to P1. The command is binary-safe, resolving variables only once to handle null characters or special sequences safely.
•If P2 exceeds the string length, the entire string is replaced with the first LEN(P1) characters of P3.
•The command requires exactly three parameters; fewer or more parameters result in no operation.
•If P2 is zero or negative, no operation is performed, and P1 remains unchanged.
Schematic (Right-End Replacement)
Source String: Hello, World!
Command: STR.SetRightB|$$SRC|5|Earth
|H|e|l|l|o|,| |W|o|r|l|d|!|
└─ Count (P2=5) ─┘
Replacement: Earth
Result String: Hello, WEarth
Syntax
STR.SetRightB|P1|P2|P3
STR.SerB|P1|P2|P3
Parameter Explanation
•P1 - (Source and Destination Variable) The string to modify. The result overwrites this variable. Can be a variable or literal.
•P2 - (Count) A numeric value specifying the number of characters to replace from the right end. Resolved to an integer (non-integer values rounded down).
•P3 - (Replacement String) The string to insert at the right end. If longer than P2, it is truncated; if shorter, remaining characters in the target range are unchanged. Can be a variable or literal.
Examples
'***********************************
' Example 1: Replace last 5 characters
'***********************************
VAR.$$SRC=Hello, World!
STR.SetRightB|$$SRC|5|Earth
' $$SRC = "Hello, WEarth" (replaces "orld!" with "Earth")
MBX.$$SRC
ENR.
'***********************************
' Example 2: Replace with longer string (truncation)
'***********************************
VAR.$$SRC=Hello, World!
STR.SetRightB|$$SRC|5|Universe
' $$SRC = "Hello, WUnive" (replaces "orld!" with "Unive", truncated)
MBX.$$SRC
ENR.
'***********************************
' Example 3: Replace with shorter string
'***********************************
VAR.$$SRC=Hello, World!
STR.SetRightB|$$SRC|5|Hi
' $$SRC = "Hello, WHild!" (replaces first 2 of "orld!" with "Hi")
MBX.$$SRC
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for STR.SetRightB
' Purpose: Verify functionality with JIV. for automated checks.
' Tests replacement, truncation, short strings, excessive count, invalid count, and parameter errors.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Replace last 5 characters
STS.CLEAR
$$SRC=Hello, World!
STR.SetRightB|$$SRC|5|Earth
$$EXP=Hello, WEarth
JIV.$$SRC!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT. Test 1.2: Replace with longer string (truncation)
STS.CLEAR
$$SRC=Hello, World!
STR.SetRightB|$$SRC|5|Universe
$$EXP=Hello, WUnive
JIV.$$SRC!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
GSB.Test
'-----------------------------------------------------------
:Lab_Next2
PRT. Test 1.3: Replace with shorter string
STS.CLEAR
$$SRC=Hello, World!
STR.SetRightB|$$SRC|5|Hi
' $$SRC = "Hello, WHild!" (replaces first 2 of "orld!" with "Hi")
$$EXP=Hello, WHild!
JIV.$$SRC!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
GSB.Test
'-----------------------------------------------------------
:Lab_Next3
PRT. Test 1.4: Count exceeds string length
STS.CLEAR
$$SRC=Hello
STR.SetRightB|$$SRC|10|WORLD
$$EXP=WORLD
JIV.$$SRC!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
GSB.Test
'-----------------------------------------------------------
:Lab_Next4
PRT. Test 1.5: Invalid count (zero)
STS.CLEAR
$$SRC=Hello, World!
STR.SetRightB|$$SRC|0|Earth
$$EXP=Hello, World!
JIV.$$SRC!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
GSB.Test
'-----------------------------------------------------------
:Lab_Next5
PRT. Test 1.6: Invalid parameter count (too few)
STS.CLEAR
$$SRC=Hello, World!
STR.SetRightB|$$SRC|5
$$EXP=Hello, World!
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
:Test
$$MSG= -> FAIL - Result: $$SRC (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
RET.
Remarks
- Uses a BASIC-style MID$ statement for in-place replacement, similar to PowerBasic’s string handling.
- Binary-safe: Variables in P1 and P3 are resolved once (via Vari_Bin), preventing unwanted substitutions in binary data (e.g., null characters).
- P2 is resolved to an integer using VAL(TRIM$(SS(2))); non-integer values are rounded down.
- Requires exactly three parameters (checked via IF R01 <> 4); incorrect parameter count results in no operation.
- Efficient for right-end modifications in fixed-width buffers or formatted text fields.
Limitations
- The string length of P1 cannot change; use STR.Replace for dynamic length adjustments.
- No option to store the result in a separate variable; P1 is always modified.
- Case-sensitive; no case-insensitive variant available.
- No support for pattern-based replacement; use RPL. for pattern operations.
See also: