MiniRobotLanguage (MRL)
STR.ExtractAny
Extract Substring Up to Any Specified Character
Intention
This command extracts a substring from a source string (P1), starting from an optional position (P3) and ending at the first occurrence of any character listed in P2.
The result is placed in a variable (P4) or, if P4 is omitted, overwrites P1.
The search is case-sensitive (e.g., "A" does not match "a").
If P3 is positive (or 0, defaults to 1), extraction starts from that position left-to-right. If negative, it starts from |P3| bytes from the end, searching left-to-right for the delimiter.
The result includes all characters from the start position up to, but not including, the first delimiter found.
This command is useful for parsing delimited strings, such as CSV data or command-line arguments, without modifying the source string unless P4 is omitted.
Schematic (Forward and Reverse Start Extraction)
Source: Hello,World!
Delimiters: ,!, Start=1 (LTR) --> Result: Hello
Search --> |H|e|l|l|o|,|W|o|r|l|d|!|
^ ^ (stops at ,)
Delimiters: ,!, Start=-6 (from end) --> Result: World
Search --> |H|e|l|l|o|,|W|o|r|l|d|!|
^ ^ (starts at W, stops at !)
Syntax
STR.ExtractAny|P1|P2[|P3][|P4]
STR.Exa|P1|P2[|P3][|P4]
Parameter Explanation
•P1 - (Source String) The main string from which to extract. Variable or literal.
•P2 - (Delimiter Characters) A string containing characters, any of which will stop the extraction. Variable or literal.
•P3 - (Optional Start Position) Numeric, 1-based (default 1). If negative, starts |P3| bytes from the end, searching left-to-right.
•P4 - (Optional Result Variable) Variable to store the extracted substring. If omitted, result overwrites P1.
Examples
' Forward extraction to variable
$$TXT=Hello,World!
$$SEA=,!
STR.ExtractAny|$$TXT|$$SEA|1|$$RES
' $$RES = Hello (stops at ,)
' Reverse start position extraction, overwrite source
$$TXT=Hello,World!
$$SEA=,!
STR.ExtractAny|$$TXT|$$SEA|-6
' $$TXT = World (starts at W, stops at !)
' No delimiter found, extract all
$$TXT=HelloWorld
$$SEA=;:
STR.ExtractAny|$$TXT|$$SEA|1|$$RES
' $$RES = HelloWorld (no delimiter found)
ENR.
'---------------------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for STR.ExtractAny
' Purpose: Verify all features with JIV. for automated checks and a summary report.
' Tests forward/reverse start positions, result to variable/source, no delimiter, edge cases (empty, invalid start).
' Uses short jumps (JIV.) and clear PRT. for readability.
' =================================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. FORWARD EXTRACTION TESTS
PRT. ===================================================
PRT. Test 1.1: Extract up to , or ! from Hello,World! (start=1, to variable)
$$TXT=Hello,World!
$$SEA=,!
STR.ExtractAny|$$TXT|$$SEA|1|$$RES
JIV.$$RES!Hello|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
$$MSG= -> FAIL - Result: $$RES (exp: Hello)
PRT.$$MSG
VIC.$$FAI
:Lab_Next1
STS.CLEAR
PRT. Test 1.2: Extract up to , or ! from Hello,World! (start=1, overwrite source)
$$TXT=Hello,World!
$$SEA=,!
STR.ExtractAny|$$TXT|$$SEA|1
JIV.$$TXT!Hello|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
$$MSG= -> FAIL - Result: $$TXT (exp: Hello)
PRT.$$MSG
VIC.$$FAI
:Lab_Next2
STS.CLEAR
PRT. ===================================================
PRT. 2. REVERSE START POSITION TESTS
PRT. ===================================================
PRT. Test 2.1: Extract from -6 to , or ! in Hello,World! (to variable)
$$TXT=Hello,World!
$$SEA=,!
STR.ExtractAny|$$TXT|$$SEA|-6|$$RES
JIV.$$RES!World|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
$$MSG= -> FAIL - Result: $$RES (exp: World)
PRT.$$MSG
VIC.$$FAI
:Lab_Next3
STS.CLEAR
PRT. Test 2.2: Extract from -6 to , or ! in Hello,World! (overwrite source)
$$TXT=Hello,World!
$$SEA=,!
STR.ExtractAny|$$TXT|$$SEA|-6
JIV.$$TXT!World|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
$$MSG= -> FAIL - Result: $$TXT (exp: World)
PRT.$$MSG
VIC.$$FAI
:Lab_Next4
STS.CLEAR
PRT. ===================================================
PRT. 3. NO DELIMITER TESTS
PRT. ===================================================
PRT. Test 3.1: No delimiter found in HelloWorld (start=1, to variable)
$$TXT=HelloWorld
$$SEA=;:
STR.ExtractAny|$$TXT|$$SEA|1|$$RES
JIV.$$RES!HelloWorld|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
$$MSG= -> FAIL - Result: $$RES (exp: HelloWorld)
PRT.$$MSG
VIC.$$FAI
:Lab_Next5
STS.CLEAR
PRT. Test 3.2: Case mismatch for delimiters in Hello,World! (start=1, to variable)
$$TXT=Hello,World!
$$SEA=;:
STR.ExtractAny|$$TXT|$$SEA|1|$$RES
JIV.$$RES!Hello,World!|Lab_Error6
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next6
:Lab_Error6
$$MSG= -> FAIL - Result: $$RES (exp: Hello,World!)
PRT.$$MSG
VIC.$$FAI
:Lab_Next6
STS.CLEAR
PRT. ===================================================
PRT. 4. EDGE CASE TESTS
PRT. ===================================================
PRT. Test 4.1: Empty source string (start=1, to variable)
$$TXT=
$$SEA=,!
STR.ExtractAny|$$TXT|$$SEA|1|$$RES
JIV.$$RES!|Lab_Error7
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next7
:Lab_Error7
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next7
STS.CLEAR
PRT. Test 4.2: Empty delimiter string (start=1, to variable)
$$TXT=Hello,World!
$$SEA=
STR.ExtractAny|$$TXT|$$SEA|1|$$RES
JIV.$$RES!Hello,World!|Lab_Error8
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next8
:Lab_Error8
$$MSG= -> FAIL - Result: $$RES (exp: Hello,World!)
PRT.$$MSG
VIC.$$FAI
:Lab_Next8
STS.CLEAR
PRT. Test 4.3: Start position beyond source length (start=20, to variable)
$$TXT=Hello
$$SEA=,!
STR.ExtractAny|$$TXT|$$SEA|20|$$RES
JIV.$$RES!|Lab_Error9
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next9
:Lab_Error9
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next9
STS.CLEAR
PRT. Test 4.4: Negative start position beyond source length (start=-20, to variable)
$$TXT=Hello
$$SEA=,!
STR.ExtractAny|$$TXT|$$SEA|-20|$$RES
JIV.$$RES!|Lab_Error10
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next10
:Lab_Error10
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next10
STS.CLEAR
PRT. Test 4.5: Binary data extraction (start=1, to variable)
$$TXT=$crlf$Hello$sp$World$tab$
$$SEA=$sp$$tab$
STR.ExtractAny|$$TXT|$$SEA|1|$$RES
JIV.$$RES!$crlf$Hello|Lab_Error11
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next11
:Lab_Error11
$$MSG= -> FAIL - Result: $$RES (exp: $crlf$Hello)
PRT.$$MSG
VIC.$$FAI
:Lab_Next11
STS.CLEAR
PRT. ===================================================
PRT. TEST SUMMARY
PRT. ===================================================
CAL.$$TOT=$$PAS+$$FAI
$$MSG=Total Tests: $$TOT
PRT.$$MSG
$$MSG=Passed: $$PAS
PRT.$$MSG
$$MSG=Failed: $$FAI
PRT.$$MSG
' Display final result
JIV.$$FAI=0|Lab_Success
$$MSG=FAILURE: $$FAI of $$TOT tests failed.
MBX.$$MSG|Test Result|16
JMP.Lab_End
:Lab_Success
MBX.SUCCESS: All tests passed!|Test Result|64
:Lab_End
ENR.
Test Result for this command.
Remarks
-Case-sensitive search for delimiters.
-P3=0 defaults to 1 (start of string).
-Negative P3 counts |P3| bytes from end, searches left-to-right.
-If no delimiter is found, returns all characters from start position to end.
-If P3 is beyond source length or source is empty, returns empty string.
-Binary-safe for P1 and P2; no special/system vars expanded.
-For extracting up to a specific string, use STR.Extract.
Limitations
-Extracts up to first delimiter only; no nth occurrence support.
-No wildcard or pattern support; use STR.FindAny for patterns.
-No reverse direction search; negative P3 only affects start position.
See also: