search

(#<widget> 'search ?switches? pattern index ?stopIndex?

Searches the text in #<widget> starting at index for a range of characters that matches pattern. If a match is found, the index of the first character in the match is returned as result; otherwise "" is returned.

One or more of the following switches (or abbreviations thereof) may be specified to control the search:

#:forwards

The search will proceed forward through the text, finding the first matching range starting at or after the position given by index. This is the default.

#:backwards

The search will proceed backward through the text, finding the matching range closest to index whose first character is before index.

#:exact

Use exact matching: the characters in the matching range must be identical to those in pattern. This is the default.

#:regexp

Treat pattern as a regular expression and match it against the text using the rules for regular expressions (see the regexp command for details).

#:nocase

Ignore case differences between the pattern and the text.

#:count varName

The argument following #:count gives the name of a variable; if a match is found, the number of index positions between beginning and end of the matching range will be stored in the variable. If there are no embedded images or windows in the matching range, this is equivalent to the number of characters matched. In either case, the range matchIdx to matchIdx + $count chars will return the entire matched text.

#:elide

Find elidden (hidden) text as well. By default only displayed text is searched.

#:-

This switch has no effect except to terminate the list of switches: the next argument will be treated as pattern even if it starts with -.

The matching range must be entirely within a single line of text.

For regular expression matching the newlines are removed from the ends of the lines before matching: use the "$" feature in regular expressions to match the end of a line.

For exact matching the newlines are retained.

If stopIndex is specified, the search stops at that index: for forward searches, no match at or after stopIndex will be considered; for backward searches, no match earlier in the text than stopIndex will be considered.

If stopIndex is omitted, the entire text will be searched: when the beginning or end of the text is reached, the search continues at the other end until the starting location is reached again.

If stopIndex is specified, no wrap-around will occur.

© Author | Home | Sitemap