* eval.c (eval_init): Register new search function as intrinsic.

* lib.c (search_list): New static function.
(search): New function.

* lib.h (search): New function declared.

* txr.1: Documented.

* txr.vim: Regenerated.

1 files changed, 51 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index 2a62737d..e34c5118 100644
--- a/txr.1
+++ b/txr.1
@@ -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