no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+# $EPIC: regex.txt,v 1.8 2009/03/21 05:49:29 zwhite Exp $
+======Synopsis:======
+$[[regcomp]](<regex pattern>) \\
+$[[regcomp_cs]](<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 case insensitive regular expression.
+The return value is suitable for /[[assign]]ing 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: you should pass the return
+value to $[[regerror]]() to check to fetch the error code.
+$[[regcomp_cs]]() is the same as regcomp, but the pattern is case sensitive.
+$[[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 l-value suitable for passing to the
+other three functions.  The return value must be passed later to
+$[[regfree]](). \\
+$[[regexec]]() returns 0 or non-zero 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.
+======Example:======
+<file>
+   @orig_string = "abc def";
+   @pattern = regcomp(abc);
+   if (regerror($pattern)) {
+      xecho -b Error compiling regex: $regerror($pattern);
+   };
+   if (regexec($pattern $orig_string) == 0) {
+      xecho -b It matched!;
+   } else {
+      xecho -b Regex error: $regerror($pattern);
+   };
+   @regfree($pattern);
+</file>
+When run, this will return:
+<file>
+*** It matched!
+</file>
+======History:======
+All the functions except [[regmatches]] first appeared in EPIC4-1.029.
+The [[regmatches]] function, and its attendant support of subexpressions
+first appeared in EPIC4-1.1.3.