MiniRobotLanguage (MRL)
STR.RetainAny
Retain Any Specified Characters in a String
Keep only specified characters from the source string.
Intention
This command retains individual characters in the source string that are present in the specified match string, removing all other characters. Unlike STR.Retain, which retains entire substrings, STR.RetainAny operates on a per-character basis, keeping only those characters that appear in the match string, regardless of their position or order.
•The command is case-sensitive, meaning characters must match exactly in case.
•Each character in the source string is checked against the match string, and only matching characters are retained in their original order.
•If the match string is empty or no characters match, the result is an empty string.
The result maintains the original order and case of the retained characters from the source string.
Syntax
STR.RetainAny|P1|P2[|P3]
STR.Rta|P1|P2[|P3]
Parameter Explanation
•P1 - (Source String) The main string from which to retain characters. Modified directly unless P3 is provided as a result variable.
•P2 - (Match String) The string containing characters to be retained (case-sensitive).
•P3 - (Optional Result Variable) Variable to store the result. If omitted, the result is stored in P1.
Examples
'***********************************
' Example 1: Retain specific characters, modify source string
'***********************************
$$SRC=abc123ABC
$$MAT=ac1
STR.RetainAny|$$SRC|$$MAT
' $$SRC will contain "ac1"
MBX.$$SRC
ENR.
'***********************************
' Example 2: Retain vowels, store in result variable
'***********************************
$$SRC=HelloWorld
$$MAT=aeiou
STR.Rta|$$SRC|$$MAT|$$RES
' $$RES will contain "eoo"
MBX.$$RES
ENR.
Remarks
- The command retains characters in the order they appear in the source string, not the match string.
- Duplicate characters in the match string are effectively ignored, as each character in the source string is checked for presence in the match string.
- If no characters in the source string match those in the match string, the result is an empty string.
- Empty match strings are ignored, resulting in an empty output.
Limitations:
- Case-sensitive; use STR.CiRetain for case-insensitive substring retention.
- Only retains individual characters, not substrings; use STR.Retain for substring retention.
See also: