ceph/src/boost/libs/regex/doc/posix_api.qbk

   1 [/
   2   Copyright 2006-2007 John Maddock.
   3   Distributed under the Boost Software License, Version 1.0.
   4   (See accompanying file LICENSE_1_0.txt or copy at
   5   http://www.boost.org/LICENSE_1_0.txt).
   6 ]
   7
   8 [section:posix POSIX Compatible C API's]
   9
  10 [note this is an abridged reference to the POSIX API functions, these are provided
  11 for compatibility with other libraries, rather than as an API to be used
  12 in new code (unless you need access from a language other than C++).
  13 This version of these functions should also happily coexist with other versions,
  14 as the names used are macros that expand to the actual function names.]
  15
  16    #include <boost/cregex.hpp>
  17
  18 or:
  19
  20    #include <boost/regex.h>
  21
  22 The following functions are available for users who need a POSIX compatible
  23 C library, they are available in both Unicode and narrow character versions,
  24 the standard POSIX API names are macros that expand to one version or the
  25 other depending upon whether UNICODE is defined or not.
  26
  27 [important Note that all the symbols defined here are enclosed inside namespace
  28 `boost` when used in C++ programs, unless you use `#include <boost/regex.h>`
  29 instead - in which case the symbols are still defined in namespace boost, but
  30 are made available in the global namespace as well.]
  31
  32 The functions are defined as:
  33
  34    extern "C" {
  35
  36    struct regex_tA;
  37    struct regex_tW;
  38
  39    int regcompA(regex_tA*, const char*, int);
  40    unsigned int regerrorA(int, const regex_tA*, char*, unsigned int);
  41    int regexecA(const regex_tA*, const char*, unsigned int, regmatch_t*, int);
  42    void regfreeA(regex_tA*);
  43
  44    int regcompW(regex_tW*, const wchar_t*, int);
  45    unsigned int regerrorW(int, const regex_tW*, wchar_t*, unsigned int);
  46    int regexecW(const regex_tW*, const wchar_t*, unsigned int, regmatch_t*, int);
  47    void regfreeW(regex_tW*);
  48
  49    #ifdef UNICODE
  50    #define regcomp regcompW
  51    #define regerror regerrorW
  52    #define regexec regexecW
  53    #define regfree regfreeW
  54    #define regex_t regex_tW
  55    #else
  56    #define regcomp regcompA
  57    #define regerror regerrorA
  58    #define regexec regexecA
  59    #define regfree regfreeA
  60    #define regex_t regex_tA
  61    #endif
  62    }
  63
  64 All the functions operate on structure regex_t, which exposes two public members:
  65
  66 [table
  67 [[Member][Meaning]]
  68 [[`unsigned int re_nsub`][This is filled in by `regcomp` and indicates the number of sub-expressions contained in the regular expression.]]
  69 [[`const TCHAR* re_endp`][Points to the end of the expression to compile when the flag REG_PEND is set.]]
  70 ]
  71
  72 [note `regex_t` is actually a `#define` - it is either `regex_tA` or `regex_tW`
  73 depending upon whether `UNICODE` is defined or not, `TCHAR` is either `char`
  74 or `wchar_t` again depending upon the macro `UNICODE`.]
  75
  76 [#regcomp][h4 regcomp]
  77
  78 `regcomp` takes a pointer to a `regex_t`, a pointer to the expression to
  79 compile and a flags parameter which can be a combination of:
  80
  81 [table
  82 [[Flag][Meaning]]
  83 [[REG_EXTENDED][Compiles modern regular expressions. Equivalent to `regbase::char_classes | regbase::intervals | regbase::bk_refs`.      ]]
  84 [[REG_BASIC][Compiles basic (obsolete) regular expression syntax. Equivalent to `regbase::char_classes | regbase::intervals | regbase::limited_ops | regbase::bk_braces | regbase::bk_parens | regbase::bk_refs`.        ]]
  85 [[REG_NOSPEC][All characters are ordinary, the expression is a literal string.   ]]
  86 [[REG_ICASE][Compiles for matching that ignores character case.          ]]
  87 [[REG_NOSUB][Has no effect in this library.      ]]
  88 [[REG_NEWLINE][When this flag is set a dot does not match the newline character.         ]]
  89 [[REG_PEND][When this flag is set the re_endp parameter of the regex_t structure must point to the end of the regular expression to compile.     ]]
  90 [[REG_NOCOLLATE][When this flag is set then locale dependent collation for character ranges is turned off.       ]]
  91 [[REG_ESCAPE_IN_LISTS][When this flag is set, then escape sequences are permitted in bracket expressions (character sets).       ]]
  92 [[REG_NEWLINE_ALT ][When this flag is set then the newline character is equivalent to the alternation operator |.        ]]
  93 [[REG_PERL][Compiles Perl like regular expressions.      ]]
  94 [[REG_AWK][A shortcut for awk-like behavior: `REG_EXTENDED | REG_ESCAPE_IN_LISTS`        ]]
  95 [[REG_GREP][A shortcut for grep like behavior: `REG_BASIC | REG_NEWLINE_ALT`     ]]
  96 [[REG_EGREP][A shortcut for egrep like behavior: `REG_EXTENDED | REG_NEWLINE_ALT`        ]]
  97 ]
  98
  99 [#regerror][h4 regerror]
 100
 101 regerror takes the following parameters, it maps an error code to a human
 102 readable string:
 103
 104 [table
 105 [[Parameter][Meaning]]
 106 [[int code][The error code.      ]]
 107 [[const regex_t* e][The regular expression (can be null).        ]]
 108 [[char* buf][The buffer to fill in with the error message.       ]]
 109 [[unsigned int buf_size][The length of buf.      ]]
 110 ]
 111
 112 If the error code is OR'ed with REG_ITOA then the message that results is the
 113 printable name of the code rather than a message, for example "REG_BADPAT".
 114 If the code is REG_ATIO then e must not be null and e->re_pend must point
 115 to the printable name of an error code, the return value is then the value
 116 of the error code. For any other value of code, the return value is the
 117 number of characters in the error message, if the return value is greater than
 118 or equal to buf_size then regerror will have to be called again with a larger buffer.
 119
 120 [#regexec][h4 regexec]
 121
 122 regexec finds the first occurrence of expression e within string buf.
 123 If len is non-zero then /*m/ is filled in with what matched the regular
 124 expression, m[0] contains what matched the whole string, m[1] the
 125 first sub-expression etc, see regmatch_t in the header file declaration
 126 for more details. The eflags parameter can be a combination of:
 127
 128 [table
 129 [[Flag][Meaning]]
 130 [[REG_NOTBOL][Parameter buf does not represent the start of a line.      ]]
 131 [[REG_NOTEOL][Parameter buf does not terminate at the end of a line.     ]]
 132 [[REG_STARTEND][The string searched starts at buf + pmatch\[0\].rm_so and ends at buf + pmatch\[0\].rm_eo.       ]]
 133 ]
 134
 135 [#regfree][h4 regfree]
 136
 137 `regfree` frees all the memory that was allocated by regcomp.
 138
 139 [endsect]
 140
 141
 142