MiniRobotLanguage (MRL)
STR.Remain
Extract Remaining Substring After Specified String
Intention
This command extracts the remaining substring from a source string (P1) starting after the first occurrence of a specified search string (P2), beginning from an optional position (P3).
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), the search starts from that position left-to-right. If negative, it starts from |P3| bytes from the end, searching left-to-right for the search string.
The result includes all characters after the search string up to the end of the source. The search string itself is not included in the result.
This command is useful for parsing delimited strings, such as extracting data after a header in protocols, or processing log files and command outputs without modifying the source unless P4 is omitted.
It supports multi-character search strings (e.g., ",," as a delimiter) and is binary-safe, meaning it can handle non-text data like control characters ($crlf$, $nul$) without expansion or corruption.
Schematic (Forward and Reverse Start Search)
Source: Hello,World!
Search String: ,, Start=1 (LTR) --> Not found, Result: empty
Search --> |H|e|l|l|o|,|W|o|r|l|d|!|
^ (no match for ,,)
Search String: , Start=-6 (from end) --> Result: World!
Search --> |H|e|l|l|o|,|W|o|r|l|d|!|
^ (starts at W, but search from , before W, result after ,)
Syntax
STR.Remain|P1|P2|P3[|P4]
STR.Rein|P1|P2|P3[|P4]
Parameter Explanation
•P1 - (Source String) The main string from which to extract the remainder. Variable or literal.
•P2 - (Search String) The string to locate; extraction starts after its first occurrence. Can be multi-character. 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 remainder. If omitted, result overwrites P1.
Examples
' Basic forward extraction to variable
$$SRC=<Hello, World!>
$$SEA=,
$$STA=1
STR.Remain|$$SRC|$$SEA|$$STA|$$RES
PRT.$$ RES = World!> (after the comma)
' Multi-character delimiter, overwrite source
$$SRC=<Hello,, World!>
$$SEA=,,
$$STA=1
STR.Remain|$$SRC|$$SEA|$$STA
PRT.$$ SRC = World!> (overwritten, after ,,)
' Reverse start position, to variable
$$SRC=Prefix:Data:Value
$$SEA=:
STR.Remain|$$SRC|$$SEA|-6|$$RES
PRT.$$RES = Value (starts search from 'V' position -6 from end, finds second :, extracts after)
' No match found, returns empty
$$SRC=HelloWorld
$$SEA=,
STR.Remain|$$SRC|$$SEA|1|$$RES
PRT.$$RES = (empty, no comma found)
' Binary data handling
$$SRC=$nul$Header$crlf$Data$tab$End
$$SEA=$crlf$
STR.Remain|$$SRC|$$SEA|1|$$RES
PRT.$$RES
PRT.$$RES|h
MBX.Done
ENR.
Test Result for this command.
Remarks
-Case-sensitive search for the search string.
-P3=0 defaults to 1 (start of string).
-Negative P3 counts |P3| bytes from end, searches left-to-right.
-If no match is found, returns empty string.
-If P3 is beyond source length or source/search is empty, returns empty string.
-Binary-safe for P1 and P2; no special/system vars expanded unless explicitly done.
-For extracting before a string, use STR.Extract; for character-based, use STR.ExtractAny.
Limitations
-Extracts after first occurrence only; no support for nth occurrence without looping.
-No wildcard or regex support; for patterns, combine with STR.Find or STR.FindAny.
-No reverse direction search (right-to-left); negative P3 only affects start position.
-Does not include the search string in the result; for inclusion, concatenate manually.
See also: