# $EPIC: regex,v 1.3 2002/01/24 19:16:26 crazyed Exp $
Synopsis:
   $regcomp(<regex pattern>)
   $regexec(<compiled pattern> <string>)
   $regmatches(<compiled pattern> <matches> <string>)
   $regerror(<compiled pattern>)
   $regfree(<compiled pattern>)

Technical:
   These functions are an interface to "regular expression" pattern matching:
   $regcomp() is used to "compile" a regular expression.  The return value
        is suitable for /assigning to an ircII variable.  Note that the
        return value of this function must be passed to the $regfree()
        function, to return the allocated resources for the compiled pattern.
        The compilation could fail: if you believe the compilation failed, you
        should call $regerror() to fetch the error.
   $regexec() is used to match a previously compiled pattern against a 
        text string.  The function returns 0 if the string is matched by the
        pattern, and 1 if it does not.
   $regmatches() is used to find substrings within the string.  It returns
        pairs of numbers which can be applied to $mid() to extract the
        respective substring.  If the string doesn't match, it returns the
        empty string.
   $regerror() is used to fetch the error code for the most recently 
        attempted action on a previously compiled pattern.
   $regfree() is used to return the resources allocated to a compiled
        pattern.  Attempting to use a compiled pattern after it has been 
        passed to regfree is an error and may crash the client.  The
        function returns the FALSE value.

   If you neglect to regfree something that was returned by regcomp,
   then that will result in a memory leak.  The client cannot control this,
   and so if you use these functions, it is your duty to keep track of this.

   Passing a value to regexec, regerror, or regfree that was not
   previously returned from regcomp is an error and may crash the client.

   In at least some implementations of the regex calls, regexec will happily
   succeed for any pattern that regcomp failed to compile.  It is necessary
   to check regerror after every regcomp and regexec call if you
   need to know about errors.

Practical:
   These functions can be very very fast for pattern matching (depending on
   implementation) and the notation available is also more powerful than the
   standard regex notation.  If you need to scan all incoming data for all
   variations of your name and performance is important to you, then these
   functions may meet your needs.

Returns:
   $regcomp() returns an opaque r-value suitable for passing to the 
        other three functions.  The return value must be passed later to
        $regfree().
   $regexec() returns 0 or 1 depending on whether the match worked or not
   $regmatches() returns a pair of numbers for each substring match.
   $regerror() returns the current error condition for a pattern
   $regfree() returns the false value.

See Also:
   assign(1); match(6); rmatch(6) mid(6)

