MiniRobotLanguage (MRL)
STR.Left
Extract Characters from the Left of a String
Extract a specified number of characters from the left end of a string.
Intention
The STR.Left command extracts a specified number of characters from the left end of a source string (P1) and stores the result in a destination variable (P3) or overwrites the source string in P1 if P3 is omitted.
A positive count extracts characters from the start, while a negative count extracts all but the last specified number of characters from the end. This command is useful for retrieving prefixes, trimming strings, or handling binary data.
•A positive P2 extracts the first P2 characters from P1.
•A negative P2 extracts all but the last |P2| characters from P1 (equivalent to LEN(P1) - ABS(P2)).
•The command is safe for binary data, as variables in P1 are resolved only once.
If P2 is zero or the source string is empty, the result is an empty string.
Syntax
STR.Left|P1|P2[|P3]
STR.lft|P1|P2[|P3]
Parameter Explanation
•P1 - (Source String) The string from which to extract characters.
•P2 - (Number of Characters) A numeric value specifying the number of characters to extract. Positive values extract from the left; negative values extract all but the last |P2| characters. Resolved to an integer.
•P3 - (Optional Result Variable) The variable to store the result. If omitted, the source string (P1) is overwritten.
Examples
'***********************************
' Example 1: Extract a prefix to a result variable
'***********************************
VAR.$$SRC=HelloWorld
STR.Left|$$SRC|5|$$RES
' $$RES will contain "Hello"
MBX.$$RES
ENR.
'***********************************
' Example 2: Extract all but the last characters
'***********************************
VAR.$$SRC=HelloWorld
STR.lft|$$SRC|-2
' $$SRC will contain "HelloWor" (all but the last 2 characters)
MBX.$$SRC
ENR.
'***********************************
' Example 3: Invalid count (zero or excessive)
'***********************************
VAR.$$SRC=HelloWorld
STR.Left|$$SRC|0|$$RES
' $$RES will contain "" (empty string, zero count)
MBX.$$RES
STR.Left|$$SRC|20|$$RES
' $$RES will contain "HelloWorld" (entire string, excessive count)
MBX.$$RES
ENR.
Remarks
- Variables in the source string (P1) 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 the length of P1, the entire source string is returned.
- If P2 is zero or negative and exceeds the string length, an empty string is returned.
- The command is efficient for extracting prefixes or trimming ends of strings.
Limitations:
- P2 must be an integer; non-integer values are rounded down.
- No case-insensitive variant available.
See also:
• STR.Mid