diff options
Diffstat (limited to 'txr.1')
| -rw-r--r-- | txr.1 | 51 |
1 files changed, 51 insertions, 0 deletions
@@ -9918,6 +9918,57 @@ This operation is destructive: it may work "in place" by modifying the original sequence. The caller should retain the return value and stop relying on the original input sequence. +.SS Function search + +.TP +Syntax: + + (search <haystack> <needle> [<testfun> [<keyfun>]) + +.TP +Description: + +The search function determines whether the sequence <needle> occurs as substring +within <haystack>, under the given comparison function <testfun> and +key function <keyfun>. If this is the case, then the zero-based position of +the leftmost occurrence of <key> within <haystack> is returned. Otherwise nil +is returned to indicate that <key> does not occur within <haystack>. +If <key> is empty, then zero is always returned. + +The arguments <haystack> and <needle> are sequences: lists, vectors +or strings, in any combination. + +If <needle> is not empty, then occurs at some position N within <haystack> if +the first element of <needle> matches the element at position N of <haystack>, +the second element of <needle> matches the element at position N+1 of +<haystack> and so forth, for all elements of <needle>. A match between elements +is determined by passing each element through <keyfun>, and then comparing +the resulting values using <testfun>. + +If <testfun> is supplied, it must be a function which can be +called with two arguments. If it is not supplied, it defaults to eql. + +If <keyfun> is supplied, it must be a function which can be called +with one argument. If it is not supplied, it deafaults to identity. + +.TP +Examples: + + ;; fails because 3.0 doesn't match 3 under the default eql function + [search #(1.0 3.0 4.0 7.0) '(3 4)] -> nil + + ;; occurrence found at position 1: (3.0 4.0) matches (3 4) under = + [search #(1.0 3.0 4.0 7.0) '(3 4) =] -> 1 + + ;; "even odd odd odd even" pattern matches at position 2 + [search #(1 1 2 3 5 7 8) '(2 1 1 1 2) : evenp] -> 2 + + ;; Case insensitive string search + [search "abcd" "CD" : chr-toupper] -> 2 + + ;; Case insensitive string search using vector of characters as key + [search "abcd" #(#\eC #\eD) : chr-toupper] -> 2 + .SS Functions ref and refset .TP |