MiniRobotLanguage (MRL)
STR.Retain
Retains only the first occurrence of a specified substring.
Intention
This Command searches for a specific substring and returns only that substring if found. If the substring does not exist in the source, an empty string is returned.
This is the inverse of STR.Remove - instead of removing what you specify, you keep only what you specify.
Syntax
STR.Retain|P1|P2|P3
Parameter Explanation
�P1 - (Input, Text) The source string to search within.
�P2 - (Input, Text) The substring to retain (find and return).
�P3 - (Output, Text) Variable to store the retained substring, or empty if not found.
Retaining a Substring
Source String: "Error: File not found"
Search for: "Error"
Result: "Error"
Source String: "Error: File not found"
Search for: "Success"
Result: "" (empty - not found)
Example
'***********************************
' STR.Retain Example
'***********************************
$$SRC="Status: ACTIVE - User logged in"
' Keep only "ACTIVE" if present
STR.Retain|$$SRC|ACTIVE|$$STATUS
' $$STATUS = "ACTIVE"
MBX.$$STATUS
' Check for error indicator
$$LOG="Process completed with ERROR code 500"
STR.Retain|$$LOG|ERROR|$$ERR
IF $$ERR<>"" THEN MBX.Error detected!
ENR.
Remarks
? Only the first occurrence is returned. If you need to find multiple matches, use STR.Instr in a loop.
? The search is case-sensitive. For case-insensitive matching, use STR.CiRetain.
? To keep individual characters rather than a substring, use STR.RetainAny.
See also:
? STR.RetainAny - Keep only specific characters
? STR.CiRetain - Case-insensitive retain
? STR.Remove - Remove substring (opposite operation)