Release calc version 2.10.3t5.45

help/rsearch

@@ -1,33 +1,102 @@
 NAME
-    rsearch - reverse search a matrix, list or association for a value
+    rsearch - reverse search for an element satisfying a specified condition
 
 SYNOPSIS
-    rsearch(x, val [,idx])
+    rsearch(a, b [, [c] [, [d] ] ])
 
 TYPES
-    x		matrix, &matrix, list, &list, assoc, &assoc
-    val		any, &any
-    idx		int
+    a		matrix, list, association, or file open for reading
+    b		string if a is a file, otherwise any
+    c		integer, defaults to zero, size(a) or the current file-position
+    d		integer, defaults to size(a) or current file-position
 
-    return	any
+    return	nonnegative integer or null
 
 DESCRIPTION
-    Reverse search the matrix, list or association x for the value
-    val.  By default, the search starts at the end.  If idx is given,
-    the reverse search starts at index indx.
 
-    If the value is not found, this function returns nil.
+    Negative values of c and nonpositive values of d are treated as
+    offsets from size(a), i.e. as if c were replaced by size(a) + c
+    and d by size(a) + d.  Any such adjustment is assumed to have been
+    made.
+
+    The nature of the search depends on whether the rsearch() is called
+    with or without the fourth argument d.
+
+Four argument case:
+
+    The search interval is as for search(a,b,c,d), i.e. the indices i
+    to be examined are to satisfy c <= i < d and 0 <= i < size(a)
+    for non-file a, and c <= i <= d - strlen(b), 0 <= i <= size(a) - strlen(b)
+    if a is a file stream.  The difference from search(a,b,c,d) is that
+    the indices i, if any, are examined in decreasing order, so that
+    if a match is found, the returned integer i is the largest in the
+    search interval.  The null value is returned if no match is found.
+
+    The default value for d is size(a) for non-file cases, and the current
+    file-position if a is a file.  The default for c is zero except if a
+    is a file and d is an integer.
+
+    For non-file a, the search is for a[[i]] == b, except that if
+    the function accept() as been defined, it is for i such that
+    accept(a[[i]], b) tests as nonzero.  Since the addresses (rather than
+    values) of a[[i]] and b are passed to accept(), the values of one or
+    both of a[[i]] and b may be changed during a call to rsearch().
+
+    In the file-stream case, if strlen(b) = n, a match at file-position i
+    corresponds to the n characters in the file starting at position i
+    matching those of the string b.  The null value is returned if no
+    match is found.   The final file position will correspond to the
+    last character if a match is found, or the start (lowest) position
+    of the search interval if no match is found, except that if no
+    reading of characters is required (e.g. if start > end), the original
+    file-position is not changed.
+
+
+    Two- or Three-argument case:
+
+    If a is not a file, the default value for c is size(a).  If a is a
+    file, rsearch(a,b) = rsearch(a, b, ftell(a)), and
+    rsearch(a,b,) = rsearch(a, b, size(a)).
+
+    If a is not a file, the search starts, if at all, at the largest
+    non-negative index i for which i <= c and i < size(a), and continues
+    until a match a[[i]] == b is found, or if accept() has been defined,
+    accept(a[[i]], b) tests as nonzero; if no such i is found and returned,
+    the null value is returned.
+
+    If a is a file, the first, if any, file-position tested has the greatest
+    nonnegative position i such that i <= c and i <= size(a) - strlen(b).
+    The returned value is either the first i at which a match is found or
+    the null value if no match with the string b is found.  The final
+    file-position will correspond to the last character of b, or the zero
+    position, according as a match is found or not found.
 
 EXAMPLE
-    > lst = list(2,"three",4i)
-    > rsearch(lst,"three")
+    > L = list(2,"three",4i)
+    > rsearch(L,"three")
 	    1
-    > rsearch(lst,"threes")
-    > rsearch(lst, 4i, 4)
-    > rsearch(lst, 4i, 1)
-    > rsearch(lst, 4i, 3)
+    > rsearch(L,"threes")
+    > rsearch(L, 4i, 4)
+    > rsearch(L, 4i, 1)
 	    2
 
+    > f = fopen("foo", "w+")
+    > fputs(f, "This file has 28 characters.")
+    > fflush(f)
+    > rsearch(f, "ha")
+	18
+    > ftell(f)
+	19
+    > rsearch(f, "ha", 17)
+	10
+    > rsearch(f, "ha", 9)
+    > ftell(f)
+	0
+    > rsearch(f, "ha")
+	18
+    > rsearch(f, "ha", 5, 500)
+	18
+
 LIMITS
     none