MiniRobotLanguage (MRL)
STR.Patch
Delete and Insert a String at a Specified Position
Delete a specified number of characters and insert a new string at a given position.
Intention
The STR.Patch command combines deletion and insertion operations on a source string (P1). It deletes a specified number of characters (P3) starting at a given position (P2) and inserts a new string (P4) at that position, potentially altering the string’s length. The result is stored in an optional result variable (P5) or overwrites the source string if P5 is omitted. This command is useful for modifying strings or binary data, such as patching specific segments in a file.
•The start position (P2) is 1-based; negative values count from the end (e.g., -1 is the last character).
•If P3 is zero, no deletion occurs, performing only insertion (like STR.Insert).
•If P4 is empty, no insertion occurs, performing only deletion (like STR.Delete).
•The command is safe for binary data, as variables in P1 and P4 are resolved only once.
If P2 is invalid or both P3 and P4 are zero/empty, no changes are made.
Syntax
STR.Patch|P1|P2|P3|P4[|P5]
Parameter Explanation
•P1 - (Source String) The string to be modified. Modified directly unless P5 is provided.
•P2 - (Start Position) A numeric value specifying the 1-based position to start deletion and insertion. Negative values count from the end (e.g., -1 is the last character). Resolved to an integer.
•P3 - (Delete Count) A numeric value specifying the number of characters to delete starting at P2. Zero skips deletion. Resolved to an integer.
•P4 - (Insert String) The string to insert at P2 after deletion. Empty string skips insertion.
•P5 - (Optional Result Variable) The variable to store the result. If omitted, the source string (P1) is overwritten.
Examples
'***********************************
' Example 1: Patch with deletion and insertion
'***********************************
VAR.$$SRC=12345XX89
VAR.$$NEW=67
VAR.$$POS=6
VAR.$$DEL=2
STR.Patch|$$SRC|$$POS|$$DEL|$$NEW
' $$SRC will contain "123456789"
MBX.$$SRC
ENR.
'***********************************
' Example 2: Patch with negative position (insertion only)
'***********************************
VAR.$$SRC=12345XX89
VAR.$$NEW=67
VAR.$$POS=-4
VAR.$$DEL=0
STR.Patch|$$SRC|$$POS|$$DEL|$$NEW
' $$SRC will contain "1234567XX89"
MBX.$$SRC
ENR.
'***********************************
' Example 3: Patch with deletion only
'***********************************
VAR.$$SRC=12345XX89
VAR.$$NEW=
VAR.$$POS=-4
VAR.$$DEL=2
STR.Patch|$$SRC|$$POS|$$DEL|$$NEW
' $$SRC will contain "1234589"
MBX.$$SRC
ENR.
'***********************************
' Example 4: Patch with result variable
'***********************************
VAR.$$SRC=HelloWorld
VAR.$$NEW=123
VAR.$$POS=5
VAR.$$DEL=3
STR.Patch|$$SRC|$$POS|$$DEL|$$NEW|$$RES
' $$RES will contain "Hell123rld"
MBX.$$RES
ENR.
Remarks
- Variables in the source (P1) and insert (P4) strings are resolved only once, ensuring safety for binary data.
- P2 and P3 are resolved to integers; non-integer values are rounded down.
- If P2 is invalid (e.g., zero, beyond string length, or negative beyond string length), no changes are made.
- If P3 is negative, it is treated as zero, skipping deletion.
- If P3 exceeds the remaining string length from P2, all characters from P2 to the end are deleted.
- STR.Patch may be slower than STR.Overwrite for large strings (>100 MB) when the delete and insert lengths are equal; use STR.Overwrite in such cases.
Limitations:
- P2 must resolve to a valid position within the string length.
- P3 must be non-negative; negative values are treated as zero.
- No case-insensitive variant available.
See also:
• STR.Left