MiniRobotLanguage (MRL)
STR.SetRight
Replace a Specified Number of Characters at the Right End of a String
All Tests passed.
Replace the rightmost characters of a string with a new substring, maintaining the original string length.
Intention
The STR.SetRight command (aliased as STR.Ser) replaces a specified number of characters at the right end of a source string (P1) with a new string (P3). The number of characters to replace is defined by P2. This command mimics the behavior of BASIC’s RIGHT$ function, as seen in languages like PowerBasic, ensuring the string length remains unchanged. It is useful for tasks like padding, formatting fixed-width fields, or modifying binary data buffers where maintaining 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 is binary-safe, handling null characters or special sequences without variable expansion.
•If P2 is zero or negative, no operation is performed, and P1 remains unchanged.
Schematic (Right-End Replacement)
Source String: Hello there
Command: STR.SetRight|$$SRC|5|WORLD
|H|e|l|l|o| |t|h|e|r|e|
└─ Count (P2=5) ─┘
Replacement: WORLD
Result String: Hello WORLD
Syntax
STR.SetRight|P1|P2|P3
STR.Ser|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 there
STR.SetRight|$$SRC|5|WORLD
' $$SRC = "Hello WORLD" (replaces "there" with "WORLD")
MBX.$$SRC
ENR.
'***********************************
' Example 2: Replace with longer string (truncation)
'***********************************
VAR.$$SRC=Hello there
STR.SetRight|$$SRC|5|UNIVERSE
' $$SRC = "Hello UNIVE" (replaces "there" with "UNIVE", truncated)
MBX.$$SRC
ENR.
'***********************************
' Example 3: Replace with shorter string
'***********************************
VAR.$$SRC=Hello there
STR.SetRight|$$SRC|5|HI
' $$SRC = "Hello HIere" (replaces first 2 of "there" with "HI")
MBX.$$SRC
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for STR.SetRight
' 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 there
STR.SetRight|$$SRC|5|WORLD
$$EXP=Hello WORLD
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 there
STR.SetRight|$$SRC|5|UNIVERSE
$$EXP=Hello UNIVERSE
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 there
STR.SetRight|$$SRC|5|HI
$$EXP=Hello HI
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.SetRight|$$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 there
STR.SetRight|$$SRC|0|WORLD
$$EXP=Hello there
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 there
STR.SetRight|$$SRC|5
$$EXP=Hello there
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
- Mimics BASIC’s RIGHT$ function, ensuring fixed-length string operations similar to PowerBasic’s string handling.
- Binary-safe: Variables in P1 and P3 are resolved once, preventing unwanted substitutions in binary data (e.g., null characters).
- P2 is resolved to an integer; non-integer values are rounded down.
- If P2 is zero or negative, no operation is performed, and P1 remains unchanged.
- 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: