ceph/src/boost/libs/regex/doc/basic_regex.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:basic_regex basic_regex]
   9
  10 [h4 Synopsis]
  11
  12    #include <boost/regex.hpp>
  13
  14 The template class `basic_regex` encapsulates regular expression
  15 parsing and compilation. The class takes two template parameters:
  16
  17 * `charT`: determines the character type, i.e. either `char` or `wchar_t`;
  18 see [link boost_regex.ref.concepts.charT_concept charT concept].
  19 * `traits`: determines the behavior of the character type, for example which
  20 character class names are recognized. A default traits class is provided:
  21 `regex_traits<charT>`.  See also
  22 [link boost_regex.ref.concepts.traits_concept traits concept].
  23
  24 For ease of use there are two typedefs that define the two standard
  25 `basic_regex` instances, unless you want to use custom traits classes or
  26 non-standard character types (for example see
  27 [link boost_regex.ref.non_std_strings.icu unicode support]),
  28 you won't need to use anything other than these:
  29
  30    namespace boost{
  31
  32    template <class charT, class traits = regex_traits<charT>  >
  33    class basic_regex;
  34
  35    typedef basic_regex<char>      regex;
  36    typedef basic_regex<wchar_t>   wregex;
  37
  38    }
  39
  40 The definition of `basic_regex` follows: it is based very closely on class
  41 `basic_string`, and fulfils the requirements for a constant-container of `charT`.
  42
  43    namespace boost{
  44
  45    template <class  charT, class traits = regex_traits<charT> >
  46    class basic_regex {
  47       public:
  48       // types:
  49       typedef          charT                                value_type;
  50       typedef          implementation-specific              const_iterator;
  51       typedef          const_iterator                       iterator;
  52       typedef          charT&                               reference;
  53       typedef          const charT&                         const_reference;
  54       typedef          std::ptrdiff_t                       difference_type;
  55       typedef          std::size_t                          size_type;
  56       typedef          regex_constants::``[syntax_option_type]``  flag_type;
  57       typedef typename traits::locale_type                  locale_type;
  58
  59       // constants:
  60       // main option selection:
  61       static const regex_constants::``[syntax_option_type]`` normal
  62                                                    = regex_constants::normal;
  63       static const regex_constants::``[syntax_option_type]`` ECMAScript
  64                                                    = normal;
  65       static const regex_constants::``[syntax_option_type]`` JavaScript
  66                                                    = normal;
  67       static const regex_constants::``[syntax_option_type]`` JScript
  68                                                    = normal;
  69       static const regex_constants::``[syntax_option_type]`` basic
  70                                                    = regex_constants::basic;
  71       static const regex_constants::``[syntax_option_type]`` extended
  72                                                    = regex_constants::extended;
  73       static const regex_constants::``[syntax_option_type]`` awk
  74                                                    = regex_constants::awk;
  75       static const regex_constants::``[syntax_option_type]`` grep
  76                                                    = regex_constants::grep;
  77       static const regex_constants::``[syntax_option_type]`` egrep
  78                                                    = regex_constants::egrep;
  79       static const regex_constants::``[syntax_option_type]`` sed
  80                                                    = basic = regex_constants::sed;
  81       static const regex_constants::``[syntax_option_type]`` perl
  82                                                    = regex_constants::perl;
  83       static const regex_constants::``[syntax_option_type]`` literal
  84                                                    = regex_constants::literal;
  85
  86       // modifiers specific to perl expressions:
  87       static const regex_constants::``[syntax_option_type]`` no_mod_m
  88                                                    = regex_constants::no_mod_m;
  89       static const regex_constants::``[syntax_option_type]`` no_mod_s
  90                                                    = regex_constants::no_mod_s;
  91       static const regex_constants::``[syntax_option_type]`` mod_s
  92                                                    = regex_constants::mod_s;
  93       static const regex_constants::``[syntax_option_type]`` mod_x
  94                                                    = regex_constants::mod_x;
  95
  96       // modifiers specific to POSIX basic expressions:
  97       static const regex_constants::``[syntax_option_type]`` bk_plus_qm
  98                                                    = regex_constants::bk_plus_qm;
  99       static const regex_constants::``[syntax_option_type]`` bk_vbar
 100                                                    = regex_constants::bk_vbar
 101       static const regex_constants::``[syntax_option_type]`` no_char_classes
 102                                                    = regex_constants::no_char_classes
 103       static const regex_constants::``[syntax_option_type]`` no_intervals
 104                                                    = regex_constants::no_intervals
 105
 106       // common modifiers:
 107       static const regex_constants::``[syntax_option_type]`` nosubs
 108                                                    = regex_constants::nosubs;
 109       static const regex_constants::``[syntax_option_type]`` optimize
 110                                                    = regex_constants::optimize;
 111       static const regex_constants::``[syntax_option_type]`` collate
 112                                                    = regex_constants::collate;
 113       static const regex_constants::``[syntax_option_type]`` newline_alt
 114                                                    = regex_constants::newline_alt;
 115       static const regex_constants::``[syntax_option_type]`` no_except
 116                                                    = regex_constants::newline_alt;
 117
 118       // construct/copy/destroy:
 119       explicit ``[link boost_regex.basic_regex.construct1 basic_regex]`` ();
 120       explicit ``[link boost_regex.basic_regex.construct2 basic_regex]``(const  charT* p, flag_type f = regex_constants::normal);
 121       ``[link boost_regex.basic_regex.construct3 basic_regex]``(const charT* p1, const  charT* p2,
 122                   flag_type f = regex_constants::normal);
 123       ``[link boost_regex.basic_regex.construct4 basic_regex]``(const charT* p, size_type len, flag_type  f);
 124       ``[link boost_regex.basic_regex.construct5 basic_regex]``(const basic_regex&);
 125
 126       template <class ST, class SA>
 127       explicit ``[link boost_regex.basic_regex.construct6 basic_regex]``(const basic_string<charT, ST,  SA>& p,
 128                            flag_type f = regex_constants::normal);
 129
 130       template <class InputIterator>
 131       ``[link boost_regex.basic_regex.construct7 basic_regex]``(InputIterator first,  InputIterator last,
 132                   flag_type f = regex_constants::normal);
 133
 134       ~basic_regex();
 135       ``[link boost_regex.basic_regex.opeq1 basic_regex& operator=]``(const basic_regex&);
 136       ``[link boost_regex.basic_regex.opeq2 basic_regex& operator=]`` (const charT* ptr);
 137
 138       template <class ST, class SA>
 139       ``[link boost_regex.basic_regex.opeq3 basic_regex& operator=]`` (const basic_string<charT, ST, SA>& p);
 140       // iterators:
 141       ``[link boost_regex.basic_regex.subexpression std::pair<const_iterator, const_iterator> subexpression]``(size_type n) const;
 142       ``[link boost_regex.basic_regex.begin const_iterator begin]``() const;
 143       ``[link boost_regex.basic_regex.end const_iterator end]``() const;
 144       // capacity:
 145       ``[link boost_regex.basic_regex.size size_type size]``() const;
 146       ``[link boost_regex.basic_regex.max_size size_type max_size]``() const;
 147       ``[link boost_regex.basic_regex.empty bool empty]``() const;
 148       ``[link boost_regex.basic_regex.mark_count size_type mark_count]``()const;
 149       //
 150       // modifiers:
 151       ``[link boost_regex.basic_regex.assign1 basic_regex& assign]``(const basic_regex& that);
 152       ``[link boost_regex.basic_regex.assign2 basic_regex& assign]``(const charT* ptr,
 153                           flag_type f = regex_constants::normal);
 154       ``[link boost_regex.basic_regex.assign3 basic_regex& assign]``(const charT* ptr, unsigned int len, flag_type f);
 155
 156       template <class string_traits, class A>
 157       ``[link boost_regex.basic_regex.assign4 basic_regex& assign]``(const basic_string<charT, string_traits, A>& s,
 158                           flag_type f = regex_constants::normal);
 159
 160       template <class InputIterator>
 161       ``[link boost_regex.basic_regex.assign5 basic_regex& assign]``(InputIterator first, InputIterator last,
 162                           flag_type f = regex_constants::normal);
 163
 164       // const operations:
 165       ``[link boost_regex.basic_regex.flags flag_type flags]``() const;
 166       ``[link boost_regex.basic_regex.status int status]``()const;
 167       ``[link boost_regex.basic_regex.str basic_string<charT> str]``() const;
 168       ``[link boost_regex.basic_regex.compare int compare]``(basic_regex&) const;
 169       // locale:
 170       ``[link boost_regex.basic_regex.imbue locale_type imbue]``(locale_type loc);
 171       ``[link boost_regex.basic_regex.getloc locale_type getloc]``() const;
 172       // swap
 173       ``[link boost_regex.basic_regex.swap void swap]``(basic_regex&) throw();
 174    };
 175
 176    template <class charT, class traits>
 177    ``[link boost_regex.basic_regex.op_eq bool operator ==]`` (const basic_regex<charT, traits>& lhs,
 178                      const basic_regex<charT, traits>& rhs);
 179
 180    template <class charT, class traits>
 181    ``[link boost_regex.basic_regex.op_ne bool operator !=]`` (const basic_regex<charT, traits>& lhs,
 182                      const basic_regex<charT, traits>& rhs);
 183
 184    template <class charT, class traits>
 185    ``[link boost_regex.basic_regex.op_lt bool operator <]`` (const basic_regex<charT, traits>& lhs,
 186                   const basic_regex<charT, traits>& rhs);
 187
 188    template <class charT, class traits>
 189    ``[link boost_regex.basic_regex.op_le bool operator <=]`` (const basic_regex<charT, traits>& lhs,
 190                      const basic_regex<charT, traits>& rhs);
 191
 192    template <class charT, class traits>
 193    ``[link boost_regex.basic_regex.op_ge bool operator >=]`` (const basic_regex<charT, traits>& lhs,
 194                      const basic_regex<charT, traits>& rhs);
 195
 196    template <class charT, class traits>
 197    ``[link boost_regex.basic_regex.op_gt bool operator >]`` (const basic_regex<charT, traits>& lhs,
 198                   const basic_regex<charT, traits>& rhs);
 199
 200    template <class charT, class io_traits, class re_traits>
 201    basic_ostream<charT, io_traits>&
 202       ``[link boost_regex.basic_regex.op_stream operator <<]`` (basic_ostream<charT, io_traits>& os,
 203                   const basic_regex<charT, re_traits>& e);
 204
 205    template <class charT, class traits>
 206    ``[link boost_regex.basic_regex.op_swap void swap]``(basic_regex<charT, traits>& e1,
 207             basic_regex<charT, traits>& e2);
 208
 209    typedef basic_regex<char> regex;
 210    typedef basic_regex<wchar_t> wregex;
 211
 212    } // namespace boost
 213
 214 [h4 Description]
 215
 216 Class `basic_regex` has the following public members:
 217
 218    // main option selection:
 219    static const regex_constants::``[syntax_option_type]`` normal
 220                                              = regex_constants::normal;
 221    static const regex_constants::``[syntax_option_type]`` ECMAScript
 222                                              = normal;
 223    static const regex_constants::``[syntax_option_type]`` JavaScript
 224                                              = normal;
 225    static const regex_constants::``[syntax_option_type]`` JScript
 226                                              = normal;
 227    static const regex_constants::``[syntax_option_type]`` basic
 228                                              = regex_constants::basic;
 229    static const regex_constants::``[syntax_option_type]`` extended
 230                                              = regex_constants::extended;
 231    static const regex_constants::``[syntax_option_type]`` awk
 232                                              = regex_constants::awk;
 233    static const regex_constants::``[syntax_option_type]`` grep
 234                                              = regex_constants::grep;
 235    static const regex_constants::``[syntax_option_type]`` egrep
 236                                              = regex_constants::egrep;
 237    static const regex_constants::``[syntax_option_type]`` sed
 238                                              = regex_constants::sed;
 239    static const regex_constants::``[syntax_option_type]`` perl
 240                                              = regex_constants::perl;
 241    static const regex_constants::``[syntax_option_type]`` literal
 242                                              = regex_constants::literal;
 243
 244    // modifiers specific to perl expressions:
 245    static const regex_constants::``[syntax_option_type]`` no_mod_m
 246                                              = regex_constants::no_mod_m;
 247    static const regex_constants::``[syntax_option_type]`` no_mod_s
 248                                              = regex_constants::no_mod_s;
 249    static const regex_constants::``[syntax_option_type]`` mod_s
 250                                              = regex_constants::mod_s;
 251    static const regex_constants::``[syntax_option_type]`` mod_x
 252                                              = regex_constants::mod_x;
 253
 254    // modifiers specific to POSIX basic expressions:
 255    static const regex_constants::``[syntax_option_type]`` bk_plus_qm
 256                                              = regex_constants::bk_plus_qm;
 257    static const regex_constants::``[syntax_option_type]`` bk_vbar
 258                                              = regex_constants::bk_vbar
 259    static const regex_constants::``[syntax_option_type]`` no_char_classes
 260                                              = regex_constants::no_char_classes
 261    static const regex_constants::``[syntax_option_type]`` no_intervals
 262                                              = regex_constants::no_intervals
 263
 264    // common modifiers:
 265    static const regex_constants::``[syntax_option_type]`` nosubs
 266                                              = regex_constants::nosubs;
 267    static const regex_constants::``[syntax_option_type]`` optimize
 268                                              = regex_constants::optimize;
 269    static const regex_constants::``[syntax_option_type]`` collate
 270                                              = regex_constants::collate;
 271    static const regex_constants::``[syntax_option_type]`` newline_alt
 272                                              = regex_constants::newline_alt;
 273
 274 The meaning of these options is documented in the [syntax_option_type]
 275 section.
 276
 277 The static constant members are provided as synonyms for the constants declared
 278 in namespace `boost::regex_constants`; for each constant of type [syntax_option_type]
 279 declared in namespace `boost::regex_constants` then a constant with the same name,
 280 type and value is declared within the scope of basic_regex.
 281
 282 [#boost_regex.basic_regex.construct1]
 283
 284    basic_regex();
 285
 286 [*Effects]: Constructs an object of class `basic_regex`.
 287
 288 [table basic_regex default construction postconditions
 289 [[Element][Value]]
 290 [[`empty()`][`true`]]
 291 [[`size()`][`0`]]
 292 [[`str()`][`basic_string<charT>()`]]
 293 ]
 294
 295 [#boost_regex.basic_regex.construct2]
 296
 297    basic_regex(const charT* p, flag_type f = regex_constants::normal);
 298
 299 [*Requires]: /p/ shall not be a null pointer.
 300
 301 [*Throws]: [bad_expression] if /p/ is not a valid regular expression,
 302 unless the flag `no_except` is set in /f/.
 303
 304 [*Effects]: Constructs an object of class [basic_regex]; the object's internal
 305 finite state machine is constructed from the regular expression contained
 306 in the null-terminated string /p/, and interpreted according to the
 307 [link boost_regex.ref.syntax_option_type option
 308 flags] specified in /f/.
 309
 310 [table Postconditions for basic_regex construction
 311 [[Element][Value]]
 312 [[`empty()`][`false`]]
 313 [[`size()`][`char_traits<charT>::length(p)`]]
 314 [[`str()`][`basic_string<charT>(p)`]]
 315 [[`flags()`][['f]]]
 316 [[`mark_count()`][The number of marked sub-expressions within the expression.]]
 317 ]
 318
 319 [#boost_regex.basic_regex.construct3]
 320
 321    basic_regex(const charT* p1, const charT* p2,
 322                flag_type f = regex_constants::normal);
 323
 324 [*Requires]: /p1/ and /p2/ are not null pointers, `p1 < p2`.
 325
 326 [*Throws]: bad_expression if \[p1,p2) is not a valid regular expression, unless
 327 the flag `no_except` is set in /f/.
 328
 329 [*Effects]: Constructs an object of class [basic_regex]; the object's
 330 internal finite state machine is constructed from the regular expression
 331 contained in the sequence of characters \[p1,p2), and interpreted according the
 332 [link boost_regex.ref.syntax_option_type option flags] specified in /f/.
 333
 334 [table Postconditions for basic_regex construction
 335 [[Element][Value]]
 336 [[`empty()`][`false`]]
 337 [[`size()`][`std::distance(p1,p2)`]]
 338 [[`str()`][`basic_string<charT>(p1,p2)`]]
 339 [[`flags()`][['f]]]
 340 [[`mark_count()`][The number of marked sub-expressions within the expression.]]
 341 ]
 342
 343 [#boost_regex.basic_regex.construct4]
 344
 345    basic_regex(const charT* p, size_type len, flag_type f);
 346
 347 [*Requires]: /p/ shall not be a null pointer, `len < max_size()`.
 348
 349 [*Throws]: [bad_expression] if /p/ is not a valid regular expression, unless
 350 the flag `no_except` is set in /f/.
 351
 352 [*Effects]: Constructs an object of class [basic_regex]; the object's
 353 internal finite state machine is constructed from the regular expression
 354 contained in the sequence of characters \[p, p+len), and interpreted
 355 according the option flags specified in /f/.
 356
 357 [table Postconditions for basic_regex construction
 358 [[Element][Value]]
 359 [[`empty()`][`false`]]
 360 [[`size()`][['len]]]
 361 [[`str()`][`basic_string<charT>(p, len)`]]
 362 [[`flags()`][['f]]]
 363 [[`mark_count()`][The number of marked sub-expressions within the expression.]]
 364 ]
 365
 366 [#boost_regex.basic_regex.construct5]
 367
 368    basic_regex(const basic_regex& e);
 369
 370 [*Effects]: Constructs an object of class [basic_regex] as a copy of the object
 371 /e/.
 372
 373 [#boost_regex.basic_regex.construct6]
 374
 375    template <class ST, class SA>
 376    basic_regex(const basic_string<charT, ST, SA>& s,
 377                flag_type f = regex_constants::normal);
 378
 379 [*Throws]: [bad_expression] if /s/ is not a valid regular expression,
 380 unless the flag `no_except` is set in /f/.
 381
 382 [*Effects]: Constructs an object of class [basic_regex]; the object's
 383 internal finite state machine is constructed from the regular expression
 384 contained in the string /s/, and interpreted according to the [link boost_regex.ref.syntax_option_type option
 385 flags] specified in /f/.
 386
 387 [table Postconditions for basic_regex construction
 388 [[Element][Value]]
 389 [[`empty()`][`false`]]
 390 [[`size()`][`s.size()`]]
 391 [[`str()`][['s]]]
 392 [[`flags()`][['f]]]
 393 [[`mark_count()`][The number of marked sub-expressions within the expression.]]
 394 ]
 395
 396 [#boost_regex.basic_regex.construct7]
 397
 398    template <class ForwardIterator>
 399    basic_regex(ForwardIterator first, ForwardIterator last,
 400                flag_type f = regex_constants::normal);
 401
 402 [*Throws]: [bad_expression] if the sequence \[first, last) is not a valid
 403 regular expression, unless the flag `no_except` is set in /f/.
 404
 405 [*Effects]: Constructs an object of class [basic_regex]; the object's
 406 internal finite state machine is constructed from the regular expression
 407 contained in the sequence of characters \[first, last), and interpreted
 408 according to the [link boost_regex.ref.syntax_option_type option flags] specified in /f/.
 409
 410 [table Postconditions for basic_regex construction
 411 [[Element][Value]]
 412 [[`empty()`][`false`]]
 413 [[`size()`][`distance(first,last)`]]
 414 [[`str()`][`basic_string<charT>(first,last)`]]
 415 [[`flags()`][['f]]]
 416 [[`mark_count()`][The number of marked sub-expressions within the expression.]]
 417 ]
 418
 419 [#boost_regex.basic_regex.opeq1]
 420
 421    basic_regex& operator=(const basic_regex& e);
 422
 423 [*Effects]: Returns the result of `assign(e.str(), e.flags())`.
 424
 425 [#boost_regex.basic_regex.opeq2]
 426
 427    basic_regex& operator=(const charT* ptr);
 428
 429 [*Requires]: /p/ shall not be a null pointer.
 430
 431 [*Effects]: Returns the result of `assign(ptr)`.
 432
 433 [#boost_regex.basic_regex.opeq3]
 434
 435    template <class ST, class SA>
 436    basic_regex& operator=(const basic_string<charT, ST, SA>& p);
 437
 438 [*Effects]: Returns the result of `assign(p)`.
 439
 440 [#boost_regex.basic_regex.subexpression]
 441
 442    std::pair<const_iterator, const_iterator> subexpression(size_type n) const;
 443
 444 [*Effects]: Returns a pair of iterators denoting the location of
 445 marked subexpression /n/ within the original regular expression string.
 446 The returned iterators are relative to `begin()` and `end()`.
 447
 448 [*Requires]: The expression must have been compiled with the
 449 [syntax_option_type] save_subexpression_location set.  Argument
 450 /n/ must be in within the range `0 <= n < mark_count()`.
 451
 452 [#boost_regex.basic_regex.begin]
 453
 454    const_iterator begin() const;
 455
 456 [*Effects]: Returns a starting iterator to a sequence of characters representing
 457 the regular expression.
 458
 459 [#boost_regex.basic_regex.end]
 460
 461    const_iterator end() const;
 462
 463 [*Effects]: Returns termination iterator to a sequence of characters representing
 464 the regular expression.
 465
 466 [#boost_regex.basic_regex.size]
 467
 468    size_type size() const;
 469
 470 [*Effects]: Returns the length of the sequence of characters representing the regular expression.
 471
 472 [#boost_regex.basic_regex.max_size]
 473
 474    size_type max_size() const;
 475
 476 [*Effects]: Returns the maximum length of the sequence of characters representing
 477 the regular expression.
 478
 479 [#boost_regex.basic_regex.empty]
 480
 481    bool empty() const;
 482
 483 [*Effects]: Returns true if the object does not contain a valid regular expression,
 484 otherwise false.
 485
 486 [#boost_regex.basic_regex.mark_count]
 487
 488    size_type mark_count() const;
 489
 490 [*Effects]: Returns the number of marked sub-expressions within the regular expression.
 491
 492 [#boost_regex.basic_regex.assign1]
 493
 494    basic_regex& assign(const basic_regex& that);
 495
 496 [*Effects]: Returns [link boost_regex.basic_regex.assign4 `assign(that.str(), that.flags())`].
 497
 498 [#boost_regex.basic_regex.assign2]
 499
 500    basic_regex& assign(const charT* ptr, flag_type f = regex_constants::normal);
 501
 502 [*Effects]: Returns [link boost_regex.basic_regex.assign4 `assign(string_type(ptr), f)`].
 503
 504 [#boost_regex.basic_regex.assign3]
 505
 506    basic_regex& assign(const charT* ptr, unsigned int len, flag_type f);
 507
 508 [*Effects]: Returns [link boost_regex.basic_regex.assign4 `assign(string_type(ptr, len), f)`].
 509
 510 [#boost_regex.basic_regex.assign4]
 511
 512    template <class string_traits, class A>
 513    basic_regex& assign(const basic_string<charT, string_traits, A>& s,
 514                      flag_type f = regex_constants::normal);
 515
 516 [*Throws]: [bad_expression] if /s/ is not a valid regular expression,
 517 unless the flag `no_except` is set in /f/.
 518
 519 [*Returns]: *this.
 520
 521 [*Effects]: Assigns the regular expression contained in the string /s/,
 522 interpreted according the [link boost_regex.ref.syntax_option_type option flags]
 523 specified in /f/.
 524
 525 [table Postconditions for basic_regex::assign
 526 [[Element][Value]]
 527 [[`empty()`][`false`]]
 528 [[`size()`][`s.size()`]]
 529 [[`str()`][['s]]]
 530 [[`flags()`][['f]]]
 531 [[`mark_count()`][The number of marked sub-expressions within the expression.]]
 532 ]
 533
 534 [#boost_regex.basic_regex.assign5]
 535
 536    template <class InputIterator>
 537    basic_regex& assign(InputIterator first, InputIterator last,
 538                        flag_type f = regex_constants::normal);
 539
 540 [*Requires]: The type `InputIterator` corresponds to the
 541 [@http://input_iterator Input Iterator requirements
 542 (24.1.1)].
 543
 544 [*Effects]: Returns [link boost_regex.basic_regex.assign4 `assign(string_type(first, last), f)`].
 545
 546 [#boost_regex.basic_regex.flags]
 547
 548    flag_type flags() const;
 549
 550 [*Effects]: Returns a copy of the [link boost_regex.ref.syntax_option_type
 551 regular expression syntax flags] that were passed to the object's constructor,
 552 or the last call to `assign`.
 553
 554 [#boost_regex.basic_regex.status]
 555
 556    int status() const;
 557
 558 [*Effects]: Returns zero if the expression contains a valid regular expression,
 559 otherwise an error code.  This member function is retained for use in
 560 environments that cannot use exception handling.
 561
 562 [#boost_regex.basic_regex.str]
 563
 564    basic_string<charT> str() const;
 565
 566 [*Effects]: Returns a copy of the character sequence passed to the object's constructor,
 567 or the last call to assign.
 568
 569 [#boost_regex.basic_regex.compare]
 570
 571    int compare(basic_regex& e)const;
 572
 573 [*Effects]: If `flags() == e.flags()` then returns `str().compare(e.str())`,
 574 otherwise returns `flags() - e.flags()`.
 575
 576 [#boost_regex.basic_regex.imbue]
 577
 578    locale_type imbue(locale_type l);
 579
 580 [*Effects]: Returns the result of `traits_inst.imbue(l)` where `traits_inst` is
 581 a (default initialized) instance of the template parameter `traits` stored
 582 within the object. Calls to `imbue` invalidate any currently contained
 583 regular expression.
 584
 585 [*Postcondition]: `empty() == true`.
 586
 587 [#boost_regex.basic_regex.getloc]
 588
 589    locale_type getloc() const;
 590
 591 [*Effects]: Returns the result of `traits_inst.getloc()` where `traits_inst` is
 592 a (default initialized) instance of the template parameter traits stored
 593 within the object.
 594
 595 [#boost_regex.basic_regex.swap]
 596
 597    void swap(basic_regex& e) throw();
 598
 599 [*Effects]: Swaps the contents of the two regular expressions.
 600
 601 [*Postcondition]: `*this` contains the regular expression that was in /e/, /e/ contains
 602 the regular expression that was in `*this`.
 603
 604 [*Complexity]: constant time.
 605
 606 [note Comparisons between [basic_regex] objects are provided on an
 607 experimental basis: please note that these are not present in the [tr1],
 608 so use with care if you are writing code that may need to be ported
 609 to other implementations of [basic_regex].]
 610
 611 [#boost_regex.basic_regex.op_eq]
 612
 613    template <class charT, class traits>
 614    bool operator == (const basic_regex<charT, traits>& lhs,
 615                      const basic_regex<charT, traits>& rhs);
 616
 617 [*Effects]: Returns `lhs.compare(rhs) == 0`.
 618
 619 [#boost_regex.basic_regex.op_ne]
 620
 621    template <class charT, class traits>
 622    bool operator != (const basic_regex<charT, traits>& lhs,
 623                      const basic_regex<charT, traits>& rhs);
 624
 625 [*Effects]: Returns `lhs.compare(rhs) != 0`.
 626
 627 [#boost_regex.basic_regex.op_lt]
 628
 629    template <class charT, class traits>
 630    bool operator < (const basic_regex<charT, traits>& lhs,
 631                   const basic_regex<charT, traits>& rhs);
 632
 633 [*Effects]: Returns `lhs.compare(rhs) < 0`.
 634
 635 [#boost_regex.basic_regex.op_le]
 636
 637    template <class charT, class traits>
 638    bool operator <= (const basic_regex<charT, traits>& lhs,
 639                      const basic_regex<charT, traits>& rhs);
 640
 641 [*Effects]: Returns `lhs.compare(rhs) <= 0`.
 642
 643 [#boost_regex.basic_regex.op_ge]
 644
 645    template <class charT, class traits>
 646    bool operator >= (const basic_regex<charT, traits>& lhs,
 647                      const basic_regex<charT, traits>& rhs);
 648
 649 [*Effects]: Returns `lhs.compare(rhs) >= 0`.
 650
 651 [#boost_regex.basic_regex.op_gt]
 652
 653    template <class charT, class traits>
 654    bool operator > (const basic_regex<charT, traits>& lhs,
 655                   const basic_regex<charT, traits>& rhs);
 656
 657 [*Effects]: Returns `lhs.compare(rhs) > 0`.
 658
 659 [note The basic_regex stream inserter is provided on an experimental basis,
 660 and outputs the textual representation of the expression to the stream.]
 661
 662 [#boost_regex.basic_regex.op_stream]
 663
 664    template <class charT, class io_traits, class re_traits>
 665    basic_ostream<charT, io_traits>&
 666       operator << (basic_ostream<charT, io_traits>& os
 667                   const basic_regex<charT, re_traits>& e);
 668
 669 [*Effects]: Returns `(os << e.str())`.
 670
 671 [#boost_regex.basic_regex.op_swap]
 672
 673    template <class charT, class traits>
 674    void swap(basic_regex<charT, traits>& lhs,
 675             basic_regex<charT, traits>& rhs);
 676
 677 [*Effects]: calls `lhs.swap(rhs)`.
 678
 679 [endsect]
 680