MiniRobotLanguage (MRL)
STR.Overwrite
Overwrite a Portion of a String at a Specified Position
Replace a portion of a source string with a new string without changing the string length.
Intention
The STR.Overwrite command replaces a portion of a source string (P1) with a replacement string (P3) starting at a specified position (P2), preserving the original string length. The result is stored in an optional result variable (P4) or overwrites the source string if P4 is omitted. This command is useful for patching strings or binary data, such as updating specific bytes in a file without altering its length.
•The start position (P2) is 1-based; negative values count from the end of the string (e.g., -1 is the last character).
•The replacement string (P3) overwrites characters starting at P2, up to the length of P3 or the string’s end.
•The command is safe for binary data, as variables in P1 and P3 are resolved only once.
If P2 is invalid or P3 is empty, no changes are made to the source string.
Syntax
STR.Overwrite|P1|P2|P3[|P4]
STR.Over|P1|P2|P3[|P4]
Parameter Explanation
•P1 - (Source String) The string to be overwritten. Modified directly unless P4 is provided.
•P2 - (Start Position) A numeric value specifying the 1-based position to start overwriting. Negative values count from the end (e.g., -1 is the last character). Resolved to an integer.
•P3 - (Replacement String) The string to overwrite into P1. Must be non-empty.
•P4 - (Optional Result Variable) The variable to store the result. If omitted, the source string (P1) is overwritten.
Examples
'***********************************
' Example 1: Overwrite with positive position
'***********************************
VAR.$$SRC=12345XX89
VAR.$$NEW=67
STR.Overwrite|$$SRC|6|$$NEW
' $$SRC will contain "12345678"
MBX.$$SRC
ENR.
'***********************************
' Example 2: Overwrite with negative position
'***********************************
VAR.$$SRC=12345XX89
VAR.$$NEW=67
STR.Over|$$SRC|-2|$$NEW
' $$SRC will contain "12345678" (overwrites "XX" at positions 7-8)
MBX.$$SRC
ENR.
'***********************************
' Example 3: Overwrite with result variable
'***********************************
VAR.$$SRC=HelloWorld
VAR.$$NEW=123
STR.Overwrite|$$SRC|5|$$NEW|$$RES
' $$RES will contain "Hell123rld"
MBX.$$RES
ENR.
Remarks
- Variables in the source (P1) and replacement (P3) strings are resolved only once, ensuring safety for binary data.
- P2 is resolved to an integer; non-integer values are rounded down.
- If P3 is longer than the remaining string length from P2, only the portion up to the string’s end is overwritten.
- The total length of the source string is preserved, truncating P3 if necessary.
- If P2 is invalid (e.g., zero, beyond string length, or negative beyond string length), no changes are made.
- For replacing specific substrings without length constraints, use RPL..
Limitations:
- P3 must be non-empty; an empty string results in no changes.
- P2 must resolve to a valid position within the string length.
- No case-insensitive variant available.
See also:
• STR.Left