GNU Searching
-------------

  "Searching" means trying to match starting at successive positions
within a string.  The function `re_search' does this.

  Before calling `re_search', you must compile your regular expression.
See GNU Regular Expression Compiling.

  Here is the function declaration:

     int
     re_search (struct re_pattern_buffer *PATTERN_BUFFER,
                const char *STRING, const int SIZE,
                const int START, const int RANGE,
                struct re_registers *REGS)

whose arguments are the same as those to `re_match' (*note GNU
Matching::.) except that the two arguments START and RANGE replace
`re_match''s argument START.

  If RANGE is positive, then `re_search' attempts a match starting
first at index START, then at START + 1 if that fails, and so on, up to
START + RANGE; if RANGE is negative, then it attempts a match starting
first at index START, then at START -1 if that fails, and so on.

  If START is not between zero and SIZE, then `re_search' returns -1.
When RANGE is positive, `re_search' adjusts RANGE so that START + RANGE
- 1 is between zero and SIZE, if necessary; that way it won't search
outside of STRING.  Similarly, when RANGE is negative, `re_search'
adjusts RANGE so that START + RANGE + 1 is between zero and SIZE, if
necessary.

  If the `fastmap' field of PATTERN_BUFFER is zero, `re_search' matches
starting at consecutive positions; otherwise, it uses `fastmap' to make
the search more efficient.  See Searching with Fastmaps.

  If no match is found, `re_search' returns -1.  If a match is found,
it returns the index where the match began.  If an internal error
happens, it returns -2.