c_cpp/etc/calc/help/rsearch

   1 NAME
   2     rsearch - reverse search for an element satisfying a specified condition
   3
   4 SYNOPSIS
   5     rsearch(a, b [, [c] [, [d] ] ])
   6
   7 TYPES
   8     a           matrix, list, association, or file open for reading
   9     b           string if a is a file, otherwise any
  10     c           integer, defaults to zero, size(a) or the current file-position
  11     d           integer, defaults to size(a) or current file-position
  12
  13     return      nonnegative integer or null
  14
  15 DESCRIPTION
  16
  17     Negative values of c and nonpositive values of d are treated as
  18     offsets from size(a), i.e. as if c were replaced by size(a) + c
  19     and d by size(a) + d.  Any such adjustment is assumed to have been
  20     made.
  21
  22     The nature of the search depends on whether the rsearch() is called
  23     with or without the fourth argument d.
  24
  25 Four argument case:
  26
  27     The search interval is as for search(a,b,c,d), i.e. the indices i
  28     to be examined are to satisfy c <= i < d and 0 <= i < size(a)
  29     for non-file a, and c <= i <= d - strlen(b), 0 <= i <= size(a) - strlen(b)
  30     if a is a file stream.  The difference from search(a,b,c,d) is that
  31     the indices i, if any, are examined in decreasing order, so that
  32     if a match is found, the returned integer i is the largest in the
  33     search interval.  The null value is returned if no match is found.
  34
  35     The default value for d is size(a) for non-file cases, and the current
  36     file-position if a is a file.  The default for c is zero except if a
  37     is a file and d is an integer.
  38
  39     For non-file a, the search is for a[[i]] == b, except that if
  40     the function accept() as been defined, it is for i such that
  41     accept(a[[i]], b) tests as nonzero.  Since the addresses (rather than
  42     values) of a[[i]] and b are passed to accept(), the values of one or
  43     both of a[[i]] and b may be changed during a call to rsearch().
  44
  45     In the file-stream case, if strlen(b) = n, a match at file-position i
  46     corresponds to the n characters in the file starting at position i
  47     matching those of the string b.  The null value is returned if no
  48     match is found.   The final file position will correspond to the
  49     last character if a match is found, or the start (lowest) position
  50     of the search interval if no match is found, except that if no
  51     reading of characters is required (e.g. if start > end), the original
  52     file-position is not changed.
  53
  54
  55     Two- or Three-argument case:
  56
  57     If a is not a file, the default value for c is size(a).  If a is a
  58     file, rsearch(a,b) = rsearch(a, b, ftell(a)), and
  59     rsearch(a,b,) = rsearch(a, b, size(a)).
  60
  61     If a is not a file, the search starts, if at all, at the largest
  62     non-negative index i for which i <= c and i < size(a), and continues
  63     until a match a[[i]] == b is found, or if accept() has been defined,
  64     accept(a[[i]], b) tests as nonzero; if no such i is found and returned,
  65     the null value is returned.
  66
  67     If a is a file, the first, if any, file-position tested has the greatest
  68     nonnegative position i such that i <= c and i <= size(a) - strlen(b).
  69     The returned value is either the first i at which a match is found or
  70     the null value if no match with the string b is found.  The final
  71     file-position will correspond to the last character of b, or the zero
  72     position, according as a match is found or not found.
  73
  74 EXAMPLE
  75     ; L = list(2,"three",4i)
  76     ; rsearch(L,"three")
  77             1
  78     ; rsearch(L,"threes")
  79     ; rsearch(L, 4i, 4)
  80     ; rsearch(L, 4i, 1)
  81             2
  82
  83     ; f = fopen("foo", "w+")
  84     ; fputs(f, "This file has 28 characters.")
  85     ; fflush(f)
  86     ; rsearch(f, "ha")
  87         18
  88     ; ftell(f)
  89         19
  90     ; rsearch(f, "ha", 17)
  91         10
  92     ; rsearch(f, "ha", 9)
  93     ; ftell(f)
  94         0
  95     ; rsearch(f, "ha")
  96         18
  97     ; rsearch(f, "ha", 5, 500)
  98         18
  99
 100 LIMITS
 101     none
 102
 103 LINK LIBRARY
 104     none
 105
 106 SEE ALSO
 107      append, delete, insert, islist, pop, push, remove, search,
 108      select, size,
 109
 110      assoc, list, mat
 111
 112 ## Copyright (C) 1999-2006  Landon Curt Noll
 113 ##
 114 ## Calc is open software; you can redistribute it and/or modify it under
 115 ## the terms of the version 2.1 of the GNU Lesser General Public License
 116 ## as published by the Free Software Foundation.
 117 ##
 118 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 119 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 120 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 121 ## Public License for more details.
 122 ##
 123 ## A copy of version 2.1 of the GNU Lesser General Public License is
 124 ## distributed with calc under the filename COPYING-LGPL.  You should have
 125 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 126 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 127 ##
 128 ## @(#) $Revision: 30.1 $
 129 ## @(#) $Id: rsearch,v 30.1 2007/03/16 11:10:42 chongo Exp $
 130 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/rsearch,v $
 131 ##
 132 ## Under source code control:   1994/03/19 03:13:21
 133 ## File existed as early as:    1994
 134 ##
 135 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 136 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/