|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > String commands > !STR.- String Command > BASIC-String Commands > String Operations |
MiniRobotLanguage (MRL)
STR.SetLeftB
Set Characters at the Left End of a String (Length-Preserving)
Replace a specified number of characters at the left end of a string with a new string, maintaining the original length.
Intention
The STR.SetLeftB command replaces the first P2 characters of a source string (P1) with a new string (P3), preserving the original string length by padding P3 with spaces if too short or truncating it if too long.
The result is stored in an optional result variable (P4) or overwrites the source string if P4 is omitted.
This command is useful for updating string prefixes or binary data headers while maintaining a fixed length, such as in fixed-width data formats.
•The number of characters (P2) determines how many characters from P1 are replaced with P3.
•The result matches the original length of P1, padding P3 with spaces or truncating it as needed.
•The command is safe for binary data, as variables in P1 and P3 are resolved only once.
If P2 is less than or equal to zero, the source string remains unchanged.
Syntax
STR.SetLeftB|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 replace with P3. Resolved to an integer.
•P3 - (New String) The string to set at the left end, padded with spaces or truncated to maintain P1's length.
•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.SetLeftB|$$SRC|5|WORLD
' $$SRC will contain "WORLD there" (length 11 preserved)
MBX.$$SRC
ENR.
'***********************************
' Example 2: Replace with padding to result variable
'***********************************
VAR.$$SRC=HelloWorld
STR.Sel|$$SRC|5|ABC|$$RES
' $$RES will contain "ABC World" (padded with spaces, length 10)
MBX.$$RES
ENR.
'***********************************
' Example 3: Edge cases (zero count, excessive count, empty string)
'***********************************
VAR.$$SRC=HelloWorld
STR.SetLeftB|$$SRC|0|ABC|$$RES
' $$RES will contain "HelloWorld" (zero count, unchanged)
MBX.$$RES
STR.SetLeftB|$$SRC|5|ABCDEFGHIJKLMNOPQRSTUVWXYZ
' $$SRC will contain "ABCDEWorld" (truncated to length 10)
MBX.$$SRC
VAR.$$SRC=
STR.SetLeftB|$$SRC|5|ABC|$$RES
' $$RES will contain "ABC " (padded to length 5)
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 padded or truncated to LEN(P1).
- If P2 is less than or equal to zero, the source string remains unchanged.
- The command is efficient for updating fixed-length string prefixes or binary data headers.
- For length-changing prefix updates, use STR.SetLeft; for right-end modifications, use STR.SetRight or STR.SetRightB.
Limitations:
- P2 must be a non-negative integer; negative values are treated as zero.
- The result length must match LEN(P1); use STR.SetLeft for length-changing operations.
- No case-insensitive variant available.
See also:
• STR.Left