Description:
SEARCH finds a pattern in some text and returns either a range indicating
where the found string is located or a 0 indicating no matches were found. Search
begins looking for matching text at the current edit position. The beginning of
the range or buffer is used if the direction is FORWARD; the end is used if the
direction is REVERSE. Note that SEARCH only finds the pattern, it doesn't move
the current cursor position. You should use the POSITION built-in to move to
the found pattern's location. The pattern to be found is passed as the first
parameter and can be any valid pattern expression.
ANCHOR searches fail if the pattern or string is not at the current position.
UNANCHOR searches fail when the string or pattern cannot be found within the
range.
See "Using Pattern Built-ins and Keywords" for an explanation on how to build
a pattern.
A second parameter, FORWARD or REVERSE, tells SEARCH which direction to search
in. This second parameter overrides the current direction setting, forcing a
specific direction for this built-in call.
The third parameter alters how the search is conducted and can be the keyword
EXACT or NO_EXACT, or the constant SEARCH_CASE or SEARCH_DIACRITICAL.
NO_EXACT is the default and forces SEARCH to match regardless of case, but
remains sensitive to diacritical marks. EXACT forces case matches and diacritical
matches. SEARCH_CASE matches only case and not diacritical. The last option is
SEARCH_DIACRITICAL which forces a diacritical but not case-sensitive match.
The fourth parameter tells SEARCH to look somewhere other than the current
buffer or the current cursor location. If the optional fourth parameter is used,
it becomes the starting point of the search.
Syntax:
range := SEARCH ( pattern, {FORWARD|REVERSE} )
range := SEARCH ( pattern, {FORWARD|REVERSE}, { EXACT | NO_EXACT } )
range := SEARCH ( pattern, {FORWARD|REVERSE}, {EXACT | NO_EXACT}, {buffer |
range} )
Examples:
The following tells nu/TPU to place the cursor at the first occurrence of "}"
in the message buffer starting at the current cursor position looking forward.
POSITION (SEARCH ("}", FORWARD, MESSAGE_BUFFER));
The following tells nu/TPU to find the first occurrence of "Whoa" starting at
the current cursor position looking backwards, and to find a case- sensitive
match.
SEARCH ("Whoa", REVERSE, EXACT);
Errors:
TPU$_BADKEY Invalid keyword.
TPU$_CONTROLC Execution aborted by [CTRL-C].
TPU$_ILLPATAS Invalid partial pattern assignment.
TPU$_NOCURRENTBUF Not in a buffer.
TPU$_STRNOTFOUND Search failed.
Related Builtins:
SEARCH