boost/libs/regex/doc/basic_regex.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html>
   3    <head>
   4       <title>Boost.Regex: basic_regex</title>
   5       <meta name="generator" content="HTML Tidy, see www.w3.org">
   6       <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   7       <link rel="stylesheet" type="text/css" href="../../../boost.css">
   8    </head>
   9    <body>
  10       <table id="Table1" cellspacing="1" cellpadding="1" width="100%" border="0">
  11          <tr>
  12             <td valign="top" width="300">
  13                <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
  14             </td>
  15             <td width="353">
  16                <h1 align="center">Boost.Regex</h1>
  17                <h2 align="center">basic_regex</h2>
  18             </td>
  19             <td width="50">
  20                <h3><a href="index.html"><img height="45" width="43" alt="Boost.Regex Index" src="uarrow.gif" border="0"></a></h3>
  21             </td>
  22          </tr>
  23       </table>
  24       <br>
  25       <br>
  26       <hr>
  27       <h3>Synopsis</h3>
  28       <pre>
  29 #include &lt;<a href="../../../boost/regex.hpp">boost/regex.hpp</a>&gt;
  30 </pre>
  31       <p>The template class <em>basic_regex</em> encapsulates regular expression parsing
  32          and compilation. The class takes two template parameters:</p>
  33       <p><b><i>charT</i></b>: determines the character type, i.e. either char or
  34          wchar_t; see <EM><A href="concepts.html#charT">charT concept</A></EM>.</p>
  35       <p><b><i>traits</i></b>: determines the behavior of the character type, for
  36          example which character class names are recognized. A default traits class is
  37          provided: <a href="regex_traits.html">regex_traits&lt;charT&gt;</a>.&nbsp; See
  38          also <EM><A href="concepts.html#traits">traits concept</A></EM>.</p>
  39       <p>For ease of use there are two typedefs that define the two standard <i>basic_regex</i>
  40          instances, unless you want to use custom traits classes or non-standard
  41          character types, you won't need to use anything other than these:</p>
  42       <pre>
  43 <b>namespace</b> boost{
  44 <b>template</b> &lt;<b>class</b> charT, <b>class</b> traits = regex_traits&lt;charT&gt;  &gt;
  45 <b>class</b> basic_regex;
  46 <b>typedef</b> basic_regex&lt;<b>char</b>&gt;      regex;
  47 <b>typedef</b> basic_regex&lt;<b>wchar_t&gt;</b>   wregex;
  48 }
  49 </pre>
  50       <p>The definition of <i>basic_regex</i> follows: it is based very closely on class
  51          basic_string, and fulfils the requirements for a constant-container of <i>charT</i>.</p>
  52       <pre>
  53 namespace boost{
  54
  55 template &lt;class  charT, class traits = regex_traits&lt;charT&gt; &gt;
  56 class basic_regex {
  57    public:
  58    // types:
  59    typedef          charT                                value_type;
  60    typedef          implementation-specific              const_iterator;
  61    typedef          const_iterator                       iterator;
  62    typedef          charT&amp;                               reference;
  63    typedef          const charT&amp;                         const_reference;
  64    typedef          std::ptrdiff_t                       difference_type;
  65    typedef          std::size_t                          size_type;
  66    typedef          regex_constants::syntax_option_type  flag_type;
  67    typedef typename traits::locale_type                  locale_type;
  68
  69    // constants:
  70    // main option selection:
  71    static const regex_constants::syntax_option_type normal          = regex_constants::normal;
  72    static const regex_constants::syntax_option_type ECMAScript      = normal;
  73    static const regex_constants::syntax_option_type JavaScript      = normal;
  74    static const regex_constants::syntax_option_type JScript         = normal;
  75    static const regex_constants::syntax_option_type basic           = regex_constants::basic;
  76    static const regex_constants::syntax_option_type extended        = regex_constants::extended;
  77    static const regex_constants::syntax_option_type awk             = regex_constants::awk;
  78    static const regex_constants::syntax_option_type grep            = regex_constants::grep;
  79    static const regex_constants::syntax_option_type egrep           = regex_constants::egrep;
  80    static const regex_constants::syntax_option_type sed             = basic = regex_constants::sed;
  81    static const regex_constants::syntax_option_type perl            = regex_constants::perl;
  82    static const regex_constants::syntax_option_type literal         = regex_constants::literal;
  83    // modifiers specific to perl expressions:
  84    static const regex_constants::syntax_option_type no_mod_m        = regex_constants::no_mod_m;
  85    static const regex_constants::syntax_option_type no_mod_s        = regex_constants::no_mod_s;
  86    static const regex_constants::syntax_option_type mod_s           = regex_constants::mod_s;
  87    static const regex_constants::syntax_option_type mod_x           = regex_constants::mod_x;
  88    // modifiers specific to POSIX basic expressions:
  89    static const regex_constants::syntax_option_type bk_plus_qm      = regex_constants::bk_plus_qm;
  90    static const regex_constants::syntax_option_type bk_vbar         = regex_constants::bk_vbar
  91    static const regex_constants::syntax_option_type no_char_classes = regex_constants::no_char_classes
  92    static const regex_constants::syntax_option_type no_intervals    = regex_constants::no_intervals
  93    // common modifiers:
  94    static const regex_constants::syntax_option_type nosubs          = regex_constants::nosubs;
  95    static const regex_constants::syntax_option_type optimize        = regex_constants::optimize;
  96    static const regex_constants::syntax_option_type collate         = regex_constants::collate;
  97    static const regex_constants::syntax_option_type newline_alt     = regex_constants::newline_alt;
  98    static const regex_constants::syntax_option_type no_except       = regex_constants::newline_alt;
  99
 100    // construct/copy/destroy:
 101    explicit <A href="#c1">basic_regex</A> ();
 102    explicit <A href="#c2">basic_regex</A>(const  charT* p, flag_type f = regex_constants::normal);
 103    <A href="#c3">basic_regex</A>(const charT* p1, const  charT* p2, flag_type f = regex_constants::normal);
 104    <A href="#c4">basic_regex</A>(const charT* p, size_type len, flag_type  f);
 105    <A href="#c5">basic_regex</A>(const basic_regex&amp;);
 106    template &lt;class ST, class SA&gt;
 107    explicit <A href="#c6">basic_regex</A>(const basic_string&lt;charT, ST,  SA&gt;&amp; p, flag_type f = regex_constants::normal);
 108    template &lt;class InputIterator&gt;
 109    <A href="#c7">basic_regex</A>(InputIterator first,  InputIterator last, flag_type f = regex_constants::normal);
 110
 111    ~basic_regex();
 112    basic_regex&amp; <A href="#o1">operator</A>=(const basic_regex&amp;);
 113    basic_regex&amp; <A href="#o2">operator</A>= (const charT* ptr);
 114    template &lt;class ST, class SA&gt;
 115    basic_regex&amp; <A href="#o3">operator</A>= (const basic_string&lt;charT, ST, SA&gt;&amp; p);
 116    // iterators:
 117    const_iterator <A href="#m1">begin</A>() const;
 118    const_iterator <A href="#m2">end</A>() const;
 119    // capacity:
 120    size_type <A href="#m3">size</A>() const;
 121    size_type <A href="#m4">max_size</A>() const;
 122    bool <A href="#m5">empty</A>() const;
 123    unsigned <A href="#m6">mark_count</A>()const;
 124    //
 125    // modifiers:
 126    basic_regex&amp; <A href="#a1">assign</A>(const basic_regex&amp; that);
 127    basic_regex&amp; <A href="#a2">assign</A>(const charT* ptr, flag_type f = regex_constants::normal);
 128    basic_regex&amp; <A href="#a3">assign</A>(const charT* ptr, unsigned int len, flag_type f);
 129    template &lt;class string_traits, class A&gt;
 130    basic_regex&amp; <A href="#a4">assign</A>(const basic_string&lt;charT, string_traits, A&gt;&amp; s,
 131                        flag_type f = regex_constants::normal);
 132    template &lt;class InputIterator&gt;
 133    basic_regex&amp; <A href="#a5">assign</A>(InputIterator first, InputIterator last,
 134                        flag_type f = regex_constants::normal);
 135
 136    // const operations:
 137    flag_type <A href="#m8">flags</A>() const;
 138    int <A href="#m8b">status</A>()const;
 139    basic_string&lt;charT&gt; <A href="#m9">str</A>() const;
 140    int <A href="#m10">compare</A>(basic_regex&amp;) const;
 141    // locale:
 142    locale_type <A href="#m11">imbue</A>(locale_type loc);
 143    locale_type <A href="#m12">getloc</A>() const;
 144    // swap
 145    void <A href="#m13">swap</A>(basic_regex&amp;) throw();
 146 };
 147
 148 template &lt;class charT, class traits&gt;
 149 bool <A href="#o4">operator</A> == (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 150                   const basic_regex&lt;charT, traits&gt;&amp; rhs);
 151 template &lt;class charT, class traits&gt;
 152 bool <A href="#o5">operator</A> != (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 153                   const basic_regex&lt;charT, traits&gt;&amp; rhs);
 154 template &lt;class charT, class traits&gt;
 155 bool <A href="#o7">operator</A> &lt; (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 156                  const basic_regex&lt;charT, traits&gt;&amp; rhs);
 157 template &lt;class charT, class traits&gt;
 158 bool <A href="#o8">operator</A> &lt;= (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 159                   const basic_regex&lt;charT, traits&gt;&amp; rhs);
 160 template &lt;class charT, class traits&gt;
 161 bool <A href="#o9">operator</A> &gt;= (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 162                   const basic_regex&lt;charT, traits&gt;&amp; rhs);
 163 template &lt;class charT, class traits&gt;
 164 bool <A href="#o10">operator</A> &gt; (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 165                  const basic_regex&lt;charT, traits&gt;&amp; rhs);
 166
 167 template &lt;class charT, class io_traits, class re_traits&gt;
 168 basic_ostream&lt;charT, io_traits&gt;&amp;
 169    <A href="#o11">operator</A> &lt;&lt; (basic_ostream&lt;charT, io_traits&gt;&amp; os,
 170                 const basic_regex&lt;charT, re_traits&gt;&amp; e);
 171
 172 template &lt;class charT, class traits&gt;
 173 void <A href="#o12">swap</A>(basic_regex&lt;charT, traits&gt;&amp; e1,
 174           basic_regex&lt;charT, traits&gt;&amp; e2);
 175
 176 typedef basic_regex&lt;char&gt; regex;
 177 typedef basic_regex&lt;wchar_t&gt; wregex;
 178
 179 } // namespace boost
 180 </pre>
 181       <h3>Description</h3>
 182       <p>Class&nbsp;<em>basic_regex</em> has the following public member functions:</p>
 183       <h4>basic_regex constants</h4>
 184       <pre>
 185 // main option selection:
 186 static const regex_constants::syntax_option_type normal           = regex_constants::normal;
 187 static const regex_constants::syntax_option_type ECMAScript       = normal;
 188 static const regex_constants::syntax_option_type JavaScript       = normal;
 189 static const regex_constants::syntax_option_type JScript          = normal;
 190 static const regex_constants::syntax_option_type basic            = regex_constants::basic;
 191 static const regex_constants::syntax_option_type extended         = regex_constants::extended;
 192 static const regex_constants::syntax_option_type awk              = regex_constants::awk;
 193 static const regex_constants::syntax_option_type grep             = regex_constants::grep;
 194 static const regex_constants::syntax_option_type egrep            = regex_constants::egrep;
 195 static const regex_constants::syntax_option_type sed              = regex_constants::sed;
 196 static const regex_constants::syntax_option_type perl             = regex_constants::perl;
 197 static const regex_constants::syntax_option_type literal          = regex_constants::literal;
 198 // modifiers specific to perl expressions:
 199 static const regex_constants::syntax_option_type no_mod_m         = regex_constants::no_mod_m;
 200 static const regex_constants::syntax_option_type no_mod_s         = regex_constants::no_mod_s;
 201 static const regex_constants::syntax_option_type mod_s            = regex_constants::mod_s;
 202 static const regex_constants::syntax_option_type mod_x            = regex_constants::mod_x;
 203 // modifiers specific to POSIX basic expressions:
 204 static const regex_constants::syntax_option_type bk_plus_qm       = regex_constants::bk_plus_qm;
 205 static const regex_constants::syntax_option_type bk_vbar          = regex_constants::bk_vbar
 206 static const regex_constants::syntax_option_type no_char_classes  = regex_constants::no_char_classes
 207 static const regex_constants::syntax_option_type no_intervals     = regex_constants::no_intervals
 208 // common modifiers:
 209 static const regex_constants::syntax_option_type nosubs           = regex_constants::nosubs;
 210 static const regex_constants::syntax_option_type optimize         = regex_constants::optimize;
 211 static const regex_constants::syntax_option_type collate          = regex_constants::collate;
 212 static const regex_constants::syntax_option_type newline_alt      = regex_constants::newline_alt;
 213 </pre>
 214       <p>The static constant members are provided as synonyms for the constants declared
 215          in namespace <code>boost::regex_constants</code>; for each constant of type <code><A href="syntax_option_type.html">
 216                syntax_option_type</A></code> declared in namespace <code>boost::regex_constants</code>
 217          then a constant with the same name, type and value is declared within the scope
 218          of <code>basic_regex</code>.</p>
 219       <h4>basic_regex constructors</h4>
 220       <pre><A name=c1> basic_regex();
 221 </pre>
 222       <P><b>Effects:</b> Constructs an object of class <code>basic_regex</code>. The
 223          postconditions of this function are indicated in the table:</P>
 224       <div align="center">
 225          <center>
 226             <table id="Table2" cellspacing="1" cellpadding="7" width="624" border="1">
 227                <tbody>
 228                   <tr>
 229                      <td valign="top" width="50%">
 230                         <p><b>Element</b></p>
 231                      </td>
 232                      <td valign="top" width="50%">
 233                         <p><b>Value</b></p>
 234                      </td>
 235                   </tr>
 236                   <tr>
 237                      <td valign="top" width="50%">
 238                         <p>empty()</p>
 239                      </td>
 240                      <td valign="top" width="50%">
 241                         <p>true</p>
 242                      </td>
 243                   </tr>
 244                   <tr>
 245                      <td valign="top" width="50%">
 246                         <p>size()</p>
 247                      </td>
 248                      <td valign="top" width="50%">
 249                         <p>0</p>
 250                      </td>
 251                   </tr>
 252                   <tr>
 253                      <td valign="top" width="50%">
 254                         <p>str()</p>
 255                      </td>
 256                      <td valign="top" width="50%">
 257                         <p>basic_string&lt;charT&gt;()</p>
 258                      </td>
 259                   </tr>
 260                </tbody>
 261             </table>
 262          </center>
 263       </div>
 264       <pre><A name=c2><BR> basic_regex(const charT* p, flag_type f = regex_constants::normal);
 265
 266 </pre>
 267       <P><b>Requires:</b> <i>p</i> shall not be a null pointer.</P>
 268       <p><b>Throws:</b> <code>bad_expression</code> if <i>p</i> is not a valid regular
 269          expression, unless the flag no_except is set in <EM>f</EM>.</p>
 270       <p><b>Effects:</b> Constructs an object of class <code>basic_regex</code>; the
 271          object's internal finite state machine is constructed from the regular
 272          expression contained in the null-terminated string <i>p</i>, and interpreted
 273          according to the <a href="syntax_option_type.html">option flags</a>&nbsp;specified
 274          in <i>f</i>. The postconditions of this function are indicated in the table:</p>
 275       <div align="center">
 276          <center>
 277             <table id="Table3" cellspacing="1" cellpadding="7" width="624" border="1">
 278                <tbody>
 279                   <tr>
 280                      <td valign="top" width="50%">
 281                         <p><b>Element</b></p>
 282                      </td>
 283                      <td valign="top" width="50%">
 284                         <p><b>Value</b></p>
 285                      </td>
 286                   </tr>
 287                   <tr>
 288                      <td valign="top" width="50%">
 289                         <p>empty()</p>
 290                      </td>
 291                      <td valign="top" width="50%">
 292                         <p>false</p>
 293                      </td>
 294                   </tr>
 295                   <tr>
 296                      <td valign="top" width="50%">
 297                         <p>size()</p>
 298                      </td>
 299                      <td valign="top" width="50%">
 300                         <p>char_traits&lt;charT&gt;::length(p)</p>
 301                      </td>
 302                   </tr>
 303                   <tr>
 304                      <td valign="top" width="50%">
 305                         <p>str()</p>
 306                      </td>
 307                      <td valign="top" width="50%">
 308                         <p>basic_string&lt;charT&gt;(p)</p>
 309                      </td>
 310                   </tr>
 311                   <tr>
 312                      <td valign="top" width="50%">
 313                         <p>flags()</p>
 314                      </td>
 315                      <td valign="top" width="50%">
 316                         <p>f</p>
 317                      </td>
 318                   </tr>
 319                   <tr>
 320                      <td valign="top" width="50%">
 321                         <p>mark_count()</p>
 322                      </td>
 323                      <td valign="top" width="50%">
 324                         <p>The number of marked sub-expressions within the expression.</p>
 325                      </td>
 326                   </tr>
 327                </tbody>
 328             </table>
 329          </center>
 330       </div>
 331       <pre>
 332
 333 </pre>
 334       <PRE><A name=c3></A>basic_regex(const charT* p1, const charT* p2, flag_type f = regex_constants::normal);</PRE>
 335       <p><b>Requires:</b> <i>p1</i> and <i>p2</i> are not null pointers, <code>p1 &lt; p2</code>.</p>
 336       <p><b>Throws:</b> <code>bad_expression</code> if [p1,p2) is not a valid regular
 337          expression, unless the flag no_except is set in <EM>f</EM>.</p>
 338       <p><b>Effects:</b> Constructs an object of class <code>basic_regex</code>; the
 339          object's internal finite state machine is constructed from the regular
 340          expression contained in the sequence of characters [p1,p2), and interpreted
 341          according the <a href="syntax_option_type.html">option flags</a> specified in <i>f</i>.
 342          The postconditions of this function are indicated in the table:</p>
 343       <div align="center">
 344          <center>
 345             <table id="Table4" cellspacing="1" cellpadding="7" width="624" border="1">
 346                <tbody>
 347                   <tr>
 348                      <td valign="top" width="50%">
 349                         <p><b>Element</b></p>
 350                      </td>
 351                      <td valign="top" width="50%">
 352                         <p><b>Value</b></p>
 353                      </td>
 354                   </tr>
 355                   <tr>
 356                      <td valign="top" width="50%">
 357                         <p>empty()</p>
 358                      </td>
 359                      <td valign="top" width="50%">
 360                         <p>false</p>
 361                      </td>
 362                   </tr>
 363                   <tr>
 364                      <td valign="top" width="50%">
 365                         <p>size()</p>
 366                      </td>
 367                      <td valign="top" width="50%">
 368                         <p>std::distance(p1,p2)</p>
 369                      </td>
 370                   </tr>
 371                   <tr>
 372                      <td valign="top" width="50%">
 373                         <p>str()</p>
 374                      </td>
 375                      <td valign="top" width="50%">
 376                         <p>basic_string&lt;charT&gt;(p1,p2)</p>
 377                      </td>
 378                   </tr>
 379                   <tr>
 380                      <td valign="top" width="50%">
 381                         <p>flags()</p>
 382                      </td>
 383                      <td valign="top" width="50%">
 384                         <p>f</p>
 385                      </td>
 386                   </tr>
 387                   <tr>
 388                      <td valign="top" width="50%">
 389                         <p>mark_count()</p>
 390                      </td>
 391                      <td valign="top" width="50%">
 392                         <p>The number of marked sub-expressions within the expression.</p>
 393                      </td>
 394                   </tr>
 395                </tbody>
 396             </table>
 397          </center>
 398       </div>
 399       <pre>
 400
 401 </pre>
 402       <pre><A name=c4></A>basic_regex(const charT* p, size_type len, flag_type f);
 403 </pre>
 404       <p><b>Requires:</b> <i>p</i> shall not be a null pointer, <code>len &lt; max_size()</code>.</p>
 405       <p><b>Throws:</b> <code>bad_expression</code> if <i>p</i> is not a valid regular
 406          expression, unless the flag no_except is set in <EM>f</EM>.</p>
 407       <p><b>Effects:</b> Constructs an object of class <code>basic_regex</code>; the
 408          object's internal finite state machine is constructed from the regular
 409          expression contained in the sequence of characters [p, p+len), and interpreted
 410          according the <a href="syntax_option_type.html">option flags</a> specified in <i>f</i>.
 411          The postconditions of this function are indicated in the table:</p>
 412       <div align="center">
 413          <center>
 414             <table id="Table5" cellspacing="1" cellpadding="7" width="624" border="1">
 415                <tbody>
 416                   <tr>
 417                      <td valign="top" width="50%">
 418                         <p><b>Element</b></p>
 419                      </td>
 420                      <td valign="top" width="50%">
 421                         <p><b>Value</b></p>
 422                      </td>
 423                   </tr>
 424                   <tr>
 425                      <td valign="top" width="50%">
 426                         <p>empty()</p>
 427                      </td>
 428                      <td valign="top" width="50%">
 429                         <p>false</p>
 430                      </td>
 431                   </tr>
 432                   <tr>
 433                      <td valign="top" width="50%">
 434                         <p>size()</p>
 435                      </td>
 436                      <td valign="top" width="50%">
 437                         <p>len</p>
 438                      </td>
 439                   </tr>
 440                   <tr>
 441                      <td valign="top" width="50%">
 442                         <p>str()</p>
 443                      </td>
 444                      <td valign="top" width="50%">
 445                         <p>basic_string&lt;charT&gt;(p, len)</p>
 446                      </td>
 447                   </tr>
 448                   <tr>
 449                      <td valign="top" width="50%">
 450                         <p>flags()</p>
 451                      </td>
 452                      <td valign="top" width="50%">
 453                         <p>f</p>
 454                      </td>
 455                   </tr>
 456                   <tr>
 457                      <td valign="top" width="50%">
 458                         <p>mark_count()</p>
 459                      </td>
 460                      <td valign="top" width="50%">
 461                         <p>The number of marked sub-expressions within the expression.</p>
 462                      </td>
 463                   </tr>
 464                </tbody>
 465             </table>
 466          </center>
 467       </div>
 468       <pre><A name=c5></A><BR>basic_regex(const basic_regex&amp; e);
 469 </pre>
 470       <p><b>Effects:</b> Constructs an object of class <code>basic_regex</code> as a
 471          copy of the object <i>e</i>. The postconditions of this function are indicated
 472          in the table:</p>
 473       <div align="center">
 474          <center>
 475             <table id="Table6" cellspacing="1" cellpadding="7" width="624" border="1">
 476                <tbody>
 477                   <tr>
 478                      <td valign="top" width="50%">
 479                         <p><b>Element</b></p>
 480                      </td>
 481                      <td valign="top" width="50%">
 482                         <p><b>Value</b></p>
 483                      </td>
 484                   </tr>
 485                   <tr>
 486                      <td valign="top" width="50%">
 487                         <p>empty()</p>
 488                      </td>
 489                      <td valign="top" width="50%">
 490                         <p>e.empty()</p>
 491                      </td>
 492                   </tr>
 493                   <tr>
 494                      <td valign="top" width="50%">
 495                         <p>size()</p>
 496                      </td>
 497                      <td valign="top" width="50%">
 498                         <p>e.size()</p>
 499                      </td>
 500                   </tr>
 501                   <tr>
 502                      <td valign="top" width="50%">
 503                         <p>str()</p>
 504                      </td>
 505                      <td valign="top" width="50%">
 506                         <p>e.str()</p>
 507                      </td>
 508                   </tr>
 509                   <tr>
 510                      <td valign="top" width="50%">
 511                         <p>flags()</p>
 512                      </td>
 513                      <td valign="top" width="50%">
 514                         <p>e.flags()</p>
 515                      </td>
 516                   </tr>
 517                   <tr>
 518                      <td valign="top" width="50%">
 519                         <p>mark_count()</p>
 520                      </td>
 521                      <td valign="top" width="50%">
 522                         <p>e.mark_count()</p>
 523                      </td>
 524                   </tr>
 525                </tbody>
 526             </table>
 527          </center>
 528       </div>
 529       <pre><BR>
 530 template &lt;class ST, class SA&gt;
 531 <A name=c6></A>basic_regex(const basic_string&lt;charT, ST, SA&gt;&amp; s, flag_type f = regex_constants::normal);
 532 </pre>
 533       <p><b>Throws:</b> <code>bad_expression</code> if <i>s</i> is not a valid regular
 534          expression, unless the flag no_except is set in <EM>f</EM>.</p>
 535       <p><b>Effects:</b> Constructs an object of class <code>basic_regex</code>; the
 536          object's internal finite state machine is constructed from the regular
 537          expression contained in the string <i>s</i>, and interpreted according to the <a href="syntax_option_type.html">
 538             option flags</a> specified in <i>f</i>. The postconditions of this function
 539          are indicated in the table:</p>
 540       <div align="center">
 541          <center>
 542             <table id="Table7" cellspacing="1" cellpadding="7" width="624" border="1">
 543                <tbody>
 544                   <tr>
 545                      <td valign="top" width="50%">
 546                         <p><b>Element</b></p>
 547                      </td>
 548                      <td valign="top" width="50%">
 549                         <p><b>Value</b></p>
 550                      </td>
 551                   </tr>
 552                   <tr>
 553                      <td valign="top" width="50%">
 554                         <p>empty()</p>
 555                      </td>
 556                      <td valign="top" width="50%">
 557                         <p>false</p>
 558                      </td>
 559                   </tr>
 560                   <tr>
 561                      <td valign="top" width="50%">
 562                         <p>size()</p>
 563                      </td>
 564                      <td valign="top" width="50%">
 565                         <p>s.size()</p>
 566                      </td>
 567                   </tr>
 568                   <tr>
 569                      <td valign="top" width="50%">
 570                         <p>str()</p>
 571                      </td>
 572                      <td valign="top" width="50%">
 573                         <p>s</p>
 574                      </td>
 575                   </tr>
 576                   <tr>
 577                      <td valign="top" width="50%">
 578                         <p>flags()</p>
 579                      </td>
 580                      <td valign="top" width="50%">
 581                         <p>f</p>
 582                      </td>
 583                   </tr>
 584                   <tr>
 585                      <td valign="top" width="50%">
 586                         <p>mark_count()</p>
 587                      </td>
 588                      <td valign="top" width="50%">
 589                         <p>The number of marked sub-expressions within the expression.</p>
 590                      </td>
 591                   </tr>
 592                </tbody>
 593             </table>
 594          </center>
 595       </div>
 596       <pre><BR>
 597 template &lt;class ForwardIterator&gt;
 598 <A name=c7></A>basic_regex(ForwardIterator first, ForwardIterator last, flag_type f = regex_constants::normal);
 599 </pre>
 600       <p><b>Throws:</b> <code>bad_expression</code> if the sequence <i>[first, last)</i>
 601          is not a valid regular expression, unless the flag no_except is set in <EM>f</EM>.</p>
 602       <p><b>Effects:</b> Constructs an object of class <code>basic_regex</code>; the
 603          object's internal finite state machine is constructed from the regular
 604          expression contained in the sequence of characters [first, last), and
 605          interpreted according to the <a href="syntax_option_type.html">option flags</a>
 606          specified in <i>f</i>. The postconditions of this function are indicated in the
 607          table:</p>
 608       <div align="center">
 609          <center>
 610             <table id="Table8" cellspacing="1" cellpadding="7" width="624" border="1">
 611                <tbody>
 612                   <tr>
 613                      <td valign="top" width="50%">
 614                         <p><b>Element</b></p>
 615                      </td>
 616                      <td valign="top" width="50%">
 617                         <p><b>Value</b></p>
 618                      </td>
 619                   </tr>
 620                   <tr>
 621                      <td valign="top" width="50%">
 622                         <p>empty()</p>
 623                      </td>
 624                      <td valign="top" width="50%">
 625                         <p>false</p>
 626                      </td>
 627                   </tr>
 628                   <tr>
 629                      <td valign="top" width="50%">
 630                         <p>size()</p>
 631                      </td>
 632                      <td valign="top" width="50%">
 633                         <p>distance(first,last)</p>
 634                      </td>
 635                   </tr>
 636                   <tr>
 637                      <td valign="top" width="50%">
 638                         <p>str()</p>
 639                      </td>
 640                      <td valign="top" width="50%">
 641                         <p>basic_string&lt;charT&gt;(first,last)</p>
 642                      </td>
 643                   </tr>
 644                   <tr>
 645                      <td valign="top" width="50%">
 646                         <p>flags()</p>
 647                      </td>
 648                      <td valign="top" width="50%">
 649                         <p>f</p>
 650                      </td>
 651                   </tr>
 652                   <tr>
 653                      <td valign="top" width="50%">
 654                         <p>mark_count()</p>
 655                      </td>
 656                      <td valign="top" width="50%">
 657                         <p>The number of marked sub-expressions within the expression.</p>
 658                      </td>
 659                   </tr>
 660                </tbody>
 661             </table>
 662          </center>
 663       </div>
 664       <pre><A name=o1></A>
 665 basic_regex&amp; operator=(const basic_regex&amp; e);
 666 </pre>
 667       <p><b>Effects:</b> Returns the result of <code>assign(e.str(), e.flags())</code>.</p>
 668       <pre><A name=o2></A>basic_regex&amp; operator=(const charT* ptr);
 669 </pre>
 670       <p><b>Requires:</b> <i>p</i> shall not be a null pointer.</p>
 671       <p><b>Effects:</b> Returns the result of <code>assign(ptr)</code>.</p>
 672       <pre><A name=o3></A>
 673 template &lt;class ST, class SA&gt;
 674 basic_regex&amp; operator=(const basic_string&lt;charT, ST, SA&gt;&amp; p);
 675 </pre>
 676       <p><b>Effects:</b> Returns the result of <code>assign(p)</code>.</p>
 677       <h4>basic_regex iterators</h4>
 678       <pre><A name=m1>
 679 const_iterator begin() const;
 680 </pre>
 681       <p><b>Effects:</b> Returns a starting iterator to a sequence of characters
 682          representing the regular expression.</p>
 683       <pre><A name=m2>
 684 const_iterator end() const;
 685 </pre>
 686       <p><b>Effects:</b> Returns termination iterator to a sequence of characters
 687          representing the regular expression.</p>
 688       <h4>basic_regex capacity</h4>
 689       <pre><A name=m3>
 690 size_type size() const;
 691 </pre>
 692       <p><b>Effects:</b> Returns the length of the sequence of characters representing
 693          the regular expression.</p>
 694       <pre><A name=m4>
 695 size_type max_size() const;
 696 </pre>
 697       <p><b>Effects:</b> Returns the maximum length of the sequence of characters
 698          representing the regular expression.</p>
 699       <pre><A name=m5></A>
 700 bool empty() const;
 701 </pre>
 702       <p><b>Effects:</b> Returns <b>true</b> if the object does not contain a valid
 703          regular expression, otherwise <b>false</b>.</p>
 704       <pre><A name=m6></A>unsigned mark_count() const;
 705 </pre>
 706       <p><b>Effects:</b> Returns the number of marked sub-expressions within the regular
 707          expresion.</p>
 708       <h4>basic_regex assign</h4>
 709       <pre><A name=a1>
 710 basic_regex&amp; assign(const basic_regex&amp; that);
 711 </pre>
 712       <p><b>Effects:</b> Returns <code>assign(that.str(), that.flags())</code>.</p>
 713       <pre><A name=a2></A>
 714 basic_regex&amp; assign(const charT* ptr, flag_type f = regex_constants::normal);
 715 </pre>
 716       <p><b>Effects:</b> Returns <code>assign(string_type(ptr), f)</code>.</p>
 717       <PRE><A name=a3></A><A name=a3></A>basic_regex&amp; assign(const charT* ptr, unsigned int len, flag_type f);</PRE>
 718       <P><B>Effects:</B> Returns <CODE>assign(string_type(ptr, len), f)</CODE>.</P>
 719       <PRE><A name=a4></A>template &lt;class string_traits, class A&gt;
 720 <A name=a6></A>basic_regex&amp; assign(const basic_string&lt;charT, string_traits, A&gt;&amp; s,
 721                     flag_type f = regex_constants::normal);
 722 </PRE>
 723       <p><b>Throws:</b> <code>bad_expression</code> if <i>s</i> is not a valid regular
 724          expression, unless the flag no_except is set in <EM>f</EM>.</p>
 725       <p><b>Returns:</b> <code>*this</code>.</p>
 726       <p><b>Effects:</b> Assigns the regular expression contained in the string <i>s</i>,
 727          interpreted according the <a href="syntax_option_type.html">option flags</a> specified
 728          in <i>f</i>. The postconditions of this function are indicated in the table:</p>
 729       <div align="center">
 730          <center>
 731             <table id="Table9" cellspacing="1" cellpadding="7" width="624" border="1">
 732                <tbody>
 733                   <tr>
 734                      <td valign="top" width="50%">
 735                         <p><b>Element</b></p>
 736                      </td>
 737                      <td valign="top" width="50%">
 738                         <p><b>Value</b></p>
 739                      </td>
 740                   </tr>
 741                   <tr>
 742                      <td valign="top" width="50%">
 743                         <p>empty()</p>
 744                      </td>
 745                      <td valign="top" width="50%">
 746                         <p>false</p>
 747                      </td>
 748                   </tr>
 749                   <tr>
 750                      <td valign="top" width="50%">
 751                         <p>size()</p>
 752                      </td>
 753                      <td valign="top" width="50%">
 754                         <p>s.size()</p>
 755                      </td>
 756                   </tr>
 757                   <tr>
 758                      <td valign="top" width="50%">
 759                         <p>str()</p>
 760                      </td>
 761                      <td valign="top" width="50%">
 762                         <p>s</p>
 763                      </td>
 764                   </tr>
 765                   <tr>
 766                      <td valign="top" width="50%">
 767                         <p>flags()</p>
 768                      </td>
 769                      <td valign="top" width="50%">
 770                         <p>f</p>
 771                      </td>
 772                   </tr>
 773                   <tr>
 774                      <td valign="top" width="50%">
 775                         <p>mark_count()</p>
 776                      </td>
 777                      <td valign="top" width="50%">
 778                         <p>The number of marked sub-expressions within the expression.</p>
 779                      </td>
 780                   </tr>
 781                </tbody>
 782             </table>
 783          </center>
 784       </div>
 785       <pre>
 786
 787 </pre>
 788       <pre><A name=a5></A>template &lt;class InputIterator&gt;
 789 basic_regex&amp; assign(InputIterator first, InputIterator last,
 790                     flag_type f = regex_constants::normal);
 791 </pre>
 792       <p><b>Requires:</b> The type InputIterator corresponds to the Input Iterator
 793          requirements (24.1.1).</p>
 794       <p><b>Effects:</b> Returns <code>assign(string_type(first, last), f)</code>.</p>
 795       <h4>basic_regex constant operations</h4>
 796       <pre><A name=m7></A><A name=m8></A>flag_type flags() const;
 797 </pre>
 798       <p><b>Effects:</b> Returns a copy of the regular expression syntax flags that were
 799          passed to the object's constructor, or the last call to <code>assign.</code></p>
 800       <CODE>
 801          <PRE><A name=m7></A><A name=m8></A><A name=m8b></A>int status() const;</PRE>
 802       </CODE>
 803       <P><STRONG>Effects</STRONG>: Returns zero if the expression contains a valid
 804          regular expression, otherwise an <A href="error_type.html">error code</A>.&nbsp;
 805          This member function is retained for use in environments that cannot use
 806          exception handling.</P>
 807       <pre><A name=m9></A>basic_string&lt;charT&gt; str() const;
 808 </pre>
 809       <p><b>Effects:</b> Returns a copy of the character sequence passed to the object's
 810          constructor, or the last call to <code>assign.</code></p>
 811       <pre><A name=m10></A>int compare(basic_regex&amp; e)const;
 812 </pre>
 813       <p><b>Effects:</b> If <code>flags() == e.flags()</code> then returns <code>str().compare(e.str())</code>,
 814          otherwise returns <code>flags() - e.flags()</code>.</p>
 815       <h4>basic_regex locale</h4>
 816       <pre><A name=m11></A>locale_type imbue(locale_type l);
 817 </pre>
 818       <p><b>Effects:</b> Returns the result of <code>traits_inst.imbue(l)</code> where <code>
 819             traits_inst</code> is a (default initialized) instance of the template
 820          parameter <code>traits</code> stored within the object. Calls to imbue
 821          invalidate any currently contained regular expression.</p>
 822       <p><b>Postcondition:</b> <code>empty() == true</code>.</p>
 823       <pre><A name=m12></A>
 824 locale_type getloc() const;
 825 </pre>
 826       <p><b>Effects:</b> Returns the result of <code>traits_inst.getloc()</code> where <code>
 827             traits_inst</code> is a (default initialized) instance of the template
 828          parameter <code>traits</code> stored within the object.</p>
 829       <h4>basic_regex swap</h4>
 830       <pre><A name=m13>
 831 void swap(basic_regex&amp; e) throw();
 832 </pre>
 833       <p><b>Effects:</b> Swaps the contents of the two regular expressions.</p>
 834       <p><b>Postcondition:</b> <code>*this</code> contains the characters that were in <i>e</i>,
 835          <i>e</i> contains the regular expression that was in <code>*this</code>.</p>
 836       <p><b>Complexity:</b> constant time.</p>
 837       <h4>basic_regex non-member functions</h4>
 838       <h5>basic_regex non-member comparison operators&nbsp;</h5>
 839       <P>Comparisons between basic_regex objects are provided on an experimental basis:
 840          please note that these are likely to be removed from the standard library
 841          proposal, so use with care if you are writing portable code.</P>
 842       <pre><A name=o4></A>
 843 template &lt;class charT, class traits&gt;
 844 bool operator == (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 845                   const basic_regex&lt;charT, traits&gt;&amp; rhs);
 846 </pre>
 847       <p><b>Effects:</b> Returns <code>lhs.compare(rhs) == 0</code>.</p>
 848       <pre><A name=o5></A>
 849 template &lt;class charT, class traits&gt;
 850 bool operator != (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 851                   const basic_regex&lt;charT, traits&gt;&amp; rhs);
 852 </pre>
 853       <p><b>Effects:</b> Returns <code>lhs.compare(rhs) != 0</code>.</p>
 854       <pre><A name=o7></A>
 855 template &lt;class charT, class traits&gt;
 856 bool operator &lt; (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 857                  const basic_regex&lt;charT, traits&gt;&amp; rhs);
 858 </pre>
 859       <p><b>Effects:</b> Returns <code>lhs.compare(rhs) &lt; 0</code>.</p>
 860       <pre><A name=o8></A>
 861 template &lt;class charT, class traits&gt;
 862 bool operator &lt;= (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 863                   const basic_regex&lt;charT, traits&gt;&amp; rhs);
 864 </pre>
 865       <p><b>Effects:</b> Returns <code>lhs.compare(rhs) &lt;= 0</code>.</p>
 866       <pre><A name=o9></A>
 867 template &lt;class charT, class traits&gt;
 868 bool operator &gt;= (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 869                   const basic_regex&lt;charT, traits&gt;&amp; rhs);
 870 </pre>
 871       <p><b>Effects:</b> Returns <code>lhs.compare(rhs) &gt;= 0</code>.</p>
 872       <pre><A name=o10></A>
 873 template &lt;class charT, class traits&gt;
 874 bool operator &gt; (const basic_regex&lt;charT, traits&gt;&amp; lhs,
 875                  const basic_regex&lt;charT, traits&gt;&amp; rhs);
 876 </pre>
 877       <p><b>Effects:</b> Returns <code>lhs.compare(rhs) &gt; 0</code>.</p>
 878       <h5>basic_regex inserter.</h5>
 879       <P>The basic_regex stream inserter is provided on an experimental basis, and
 880          outputs the textual representation of the expression to the stream:</P>
 881       <pre><A name=o11></A>
 882 template &lt;class charT, class io_traits, class re_traits&gt;
 883 basic_ostream&lt;charT, io_traits&gt;&amp;
 884    operator &lt;&lt; (basic_ostream&lt;charT, io_traits&gt;&amp; os
 885                 const basic_regex&lt;charT, re_traits&gt;&amp; e);
 886 </pre>
 887       <p><b>Effects:</b> Returns (os &lt;&lt; e.str()).</p>
 888       <h5>basic_regex non-member swap</h5>
 889       <pre><A name=o12></A>
 890 template &lt;class charT, class traits&gt;
 891 void swap(basic_regex&lt;charT, traits&gt;&amp; lhs,
 892           basic_regex&lt;charT, traits&gt;&amp; rhs);
 893 </pre>
 894       <p><b>Effects:</b> calls <code>lhs.swap(rhs)</code>.</p>
 895       <hr>
 896       <p>Revised 7 Aug
 897          <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
 898          2004&nbsp;
 899          <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
 900       <p><i>© Copyright John Maddock&nbsp;1998-
 901             <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan -->  2004<!--webbot bot="Timestamp" endspan i-checksum="39359" --></i></p>
 902       <P><I>Use, modification and distribution are subject to the Boost Software License,
 903             Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
 904             or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)</I></P>
 905    </body>
 906 </html>