MiniRobotLanguage (MRL)
STR.SetLeft
Set Characters at the Left End of a String
Replace a specified number of characters at the left end of a string with a new string.
Intention
The STR.SetLeft command replaces the first P2 characters of a source string (P1) with a new string (P3), deleting all characters to the right of position P2 and appending P3.
The result is stored in an optional result variable (P4) or overwrites the source string if P4 is omitted. This command can change the string’s length and is useful for updating prefixes or modifying binary data.
•The number of characters (P2) determines how many characters from P1 are retained before appending P3.
•The command is safe for binary data, as variables in P1 and P3 are resolved only once.
•The resulting string length is LEN(P3) + MAX(0, LEN(P1) - P2).
If P2 is less than or equal to zero, the source string remains unchanged.
Syntax
STR.SetLeft|P1|P2|P3[|P4]
STR.Sel|P1|P2|P3[|P4]
Parameter Explanation
•P1 - (Source String) The string to modify. Modified directly unless P4 is provided.
•P2 - (Number of Characters) A numeric value specifying how many characters from P1 to retain before replacing with P3. Resolved to an integer.
•P3 - (New String) The string to set at the left end of P1.
•P4 - (Optional Result Variable) The variable to store the result. If omitted, the source string (P1) is overwritten.
Examples
'***********************************
' Example 1: Replace left characters in place
'***********************************
VAR.$$SRC=Hello there
STR.SetLeft|$$SRC|5|WORLD
' $$SRC will contain "WORLD there"
MBX.$$SRC
ENR.
'***********************************
' Example 2: Replace left characters to result variable
'***********************************
VAR.$$SRC=HelloWorld
STR.Sel|$$SRC|3|ABC|$$RES
' $$RES will contain "ABCWorld"
MBX.$$RES
ENR.
'***********************************
' Example 3: Edge cases (zero count, excessive count, empty string)
'***********************************
VAR.$$SRC=HelloWorld
STR.SetLeft|$$SRC|0|ABC|$$RES
' $$RES will contain "HelloWorld" (zero count, unchanged)
MBX.$$RES
STR.SetLeft|$$SRC|20|XYZ
' $$SRC will contain "XYZ" (exceeds string length)
MBX.$$SRC
VAR.$$SRC=
STR.SetLeft|$$SRC|5|ABC|$$RES
' $$RES will contain "ABC" (empty source string)
MBX.$$RES
ENR.
Remarks
- Variables in the source (P1) and new string (P3) are resolved only once, ensuring safety for binary data (e.g., null characters or special sequences).
- P2 is resolved to an integer; non-integer values are rounded down.
- If P2 is greater than or equal to the length of P1, the result is P3.
- If P2 is less than or equal to zero, the source string remains unchanged.
- The command is efficient for updating string prefixes or binary data headers.
- For setting characters at the right end, use STR.SetRight; for general insertion, use STR.Patch or STR.Overwrite.
Limitations:
- P2 must be a non-negative integer; negative values are treated as zero.
- No case-insensitive variant available.
See also:
• STR.Left