help/search

   1 NAME
   2     search - search for an element satisfying a specified condition
   3
   4 SYNOPSIS
   5     search(a, b [, [c] [, [d] ] ])
   6
   7 TYPES
   8     a           matrix, list, association or file
   9     b           string if a is a file, otherwise any
  10     c           integer, defaults to zero or current file-position
  11     d           integer, defaults to size(a) or current file-position
  12
  13     return      nonnegative integer or null value
  14
  15 DESCRIPTION
  16
  17     Negative values of c and nonpositive values for 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 in the following
  20     description.
  21
  22
  23     For Non-file a:
  24
  25     For a matrix, list, or association a,
  26     search(a, b, c, d) returns, if it exists, the least index i for which
  27     c <= i < d,  0 <= i < size(a), and, if accept() has not been defined,
  28     a[[i]] == b, or if accept() has been defined, accept(a[[i]], b)
  29     tests as nonzero.  The null value is returned if there is no such i.
  30
  31     For example, to search for the first a[[i]] > b an appropriate
  32     accept() function is given by:
  33
  34                 define accept(v,b) = (v > b);
  35
  36     To restore the original behavior of search(), one may then use
  37
  38                 define accept(v, b) = (v == b).
  39
  40     Since the addresses (rather than values) of a and b are passed,
  41     the values of v = x[[i]] and b may be changed during execution
  42     of search(a, b, c, d), e.g. if accept(v,b) has been defined by
  43
  44                 define accept(v,b) = (v > b ? v-- : b++);
  45
  46
  47     For a is a file-stream:
  48
  49     c defaults to the current file-position if there are just two
  50     arguments (a,b) or if there are four arguments as in (a,b, ,d)
  51     where d is an integer.  Otherwise c defaults to zero.
  52
  53     d defaults to the current file-position or size(a) according as
  54     the number of arguments (indicated by commas) is four or less
  55     than four.
  56
  57     If a is a file, a string formed by n successive characters in a
  58     is considered to occur at the file position
  59     of the first character.  E.g. if a has the characters "123456",
  60     the string "345" is said to occur at position 2.
  61
  62     The file is searched forwards from file-position pos = c for
  63     a match with b (not including the terminating '\0').
  64     Only characters with file-positions less than d are considered,
  65     so the effective interval for the first-character position pos
  66     for a matching string is limited by both c <= pos <= d - strlen(b)
  67     and 0 <= pos < size(a) - strlen(b).
  68
  69     The function returns pos if a match is found, and the reading position
  70     for the stream after the search will then correspond to the position of
  71     the terminating '\0' for the string b.
  72
  73     The null value is returned if no match is found.  If c, d, size(a)
  74     and strlen(b) are such that no match is possible, no reading of the
  75     file occurs and the current file-position is not changed.  In a case
  76     where characters are read, the final file-position will be
  77     min(d, size(a)) - strlen(b) + 1,
  78     i.e. the file will be at the first position where a match is impossible
  79     because the specified search region has insufficient remaining characters.
  80
  81 EXAMPLE
  82     > L = list(2,"three",4i)
  83     > search(L,"three")
  84             1
  85     > search(L,"threes")
  86     > search(L, 4i, 4)
  87     > search(L, 4i, 1)
  88             2
  89
  90     > f = fopen("foo", "w+")
  91     > fputs(f, "This file has 28 characters.")
  92     > rewind(f)
  93     > search(f, "ha")
  94         10
  95     > ftell(f)
  96         12
  97     > search(f, "ha")
  98         18
  99     > search(f, "ha")
 100     > search(f, "ha",)
 101         10
 102     > search(f, "ha", 12)
 103         18
 104     > search(f, "ha", -10)
 105         18
 106     > search(f, "ha", ,)
 107         10
 108     > search(f, "ha", 11, 19)
 109     > ftell(f)
 110         18
 111     > search(f, "ha", 11, 20)
 112         18
 113     > search(f, "ha", 5, 500)
 114         10
 115
 116 LIMITS
 117     none
 118
 119 LINK LIBRARY
 120     none
 121
 122 SEE ALSO
 123     assoc, list, mat, rsearch
 124
 125