The basic_regex Class Template






16.4. The basic_regex Class Template

template<class Elem,
  class RXtraits = regex_traits<Elem>
  class basic_regex {
public:

  basic_regex();
  explicit basic_regex(const Elem *ptr,
    flag_type flags = ECMAScript);
  basic_regex(const Elem *ptr, size_type count,
    flag_type flags = ECMAScript);
  basic_regex(const basic_regex& right);
  template<class STtraits, class STalloc>
    explicit basic_regex(
      const basic_string<Elem, STtraits, STalloc>& str,
      flag_type flags = ECMAScript);
  template<class InIt>
    explicit basic_regex(InIt first, InIt last,
      flag_type flags = ECMAScript);

  basic_regex& operator=(const Elem *ptr);
  template<class STtraits, class STalloc>
    basic_regex& operator=(
      const basic_string <Elem, STtraits, STalloc >& str);
  basic_regex& operator=(const basic_regex& right);
  basic_regex& assign(const Elem *ptr,
    flag_type flags = ECMAScript);
  basic_regex& assign(const Elem *ptr, size_type count,
    flag_type flags = ECMAScript);
  template<class STtraits, class STalloc>
  basic_regex& assign(
    const basic_string <Elem, STtraits, STalloc >& str,
    flag_type flags = ECMAScript);
  template<class InIt>
    basic_regex& assign(InIt first, InIt last,
      flag_type flags = ECMAScript);
      basic_regex& assign(const basic_regex& right);

  void swap(basic_regex& other) throw();

  locale_type imbue(locale_type loc);
  locale_type getloc() const;

  unsigned mark_count() const;
  flag_type flags() const;

  typedef Elem value_type;
  typedef regex_constants::syntax_option_type flag_type;
  typedef typename RXtraits::locale_type locale_type;

  static const flag_type ECMAScript =
    regex_constants::ECMAScript;
  static const flag_type basic =
    regex_constants::basic;
  static const flag_type extended =
    regex_constants::extended;
  static const flag_type grep =
    regex_constants::grep ;
  static const  flag_type egrep =
    regex_constants::egrep;
  static const flag_type awk =
    regex_constants::awk;

  static const flag_type nosubs =
    regex_constants::nosubs;
  static const flag_type optimize =
    regex_constants::optimize;
  static const flag_type icase =
    regex_constants::icase;
  static const flag_type collate =
    regex_constants::collate;
  };

16.4.1. basic_regex Summary

An object of type basic_regex<Elem> can be created by the template's default constructor or from an operand sequence describing the regular expression that the object will hold. The constructors are discussed in Section 16.4.2 and the meanings of the various operand sequences are discussed in Section 16.1.

The destructor for basic_regex releases all resources used by the object.

You can change a basic_regex object so that it is empty or so that it holds a different regular expression. This is done with operator= or with the assign member functions, discussed in Section 16.4.3.

If a constructor, operator=, or assign fails, either because the operand sequence does not designate a valid regular expression or because there aren't enough resources available, it throws an object of type regex_error. This is discussed in Section 16.6.

You can exchange the contents of two regular expression objects with the member function basic_regex::swap(basic_regex&) and with the non-member function swap(basic_regex&, basic_regex&). These functions are discussed in Section 16.4.4.

A basic_regex object holds a locale object that determines some of the properties of regular expression matching. You can change this locale object with the member function basic_regex::imbue, and you can get a copy of this local object with the member function basic_regex::getloc. These functions are discussed in Section 16.4.5.

You can get the number of capture groups in a regular expression by calling the member function basic_regex::mark_count. You can get a copy of the flags used for the regular expression by calling the member function basic_regex::flags. These functions are discussed in Section 16.4.6.

The template basic_regex defines two nested type names, based on its template type arguments, and repeats several type names and constants that are also defined in the namespace std::tr1::regex_constants. These definitions are discussed in Section 16.4.7.

16.4.2. Creating basic_regex Objects

basic_regex::basic_regex ();

The constructor constructs a basic_regex object that holds an empty regular expression.

explicit basic_regex::basic_regex (const Elem *ptr,
  flag_type flags = ECMAScript);
basic_regex::basic_regex (const Elem *ptr, size_type  count,
  flag_type flags = ECMAScript);
basic_regex__basic_regex(const basic_regex& right);
template<class STtraits, class STalloc>
  explicit basic_regex::basic_regex(
    const basic_string<Elem,  STtraits, STalloc>& str,
    flag_type flags = ECMAScript);
template<class InIt>
  explicit basic_regex::basic_regex(InIt first, InIt last,
    flag_type flags = ECMAScript);

Each of the constructors constructs a basic_regex object that holds a regular expression defined by the constructor's operand sequence interpreted in accordance with the flags argument.

All the flags arguments have a default value of ECMAScript, so the default grammar is ECMAScript. To use a different grammar, pass the constant that represents that grammar to the constructor.

Figure. basic_regex Constructors (regexbasic/construct.cpp)

# include <regex >
# include <string >
using std ::tr1 ::regex;
using std ::string;

int main ()
  { // demonstrate basic regex constructors
  regex  rgx0;                 // default constructor; matches nothing
  char  expr1[] = "abc [d-f]";
  regex rgx1 (expr1);     // holds "abc[d-f]", ECMAScript grammar
  regex rgx2 (expr1, 3);  // holds "abc", ECMAScript grammar
  regex rgx3 (rgx2);      // holds "abc", ECMAScript grammar
  string str ("[def]");
  regex rgx4 (str, regex ::basic);
                          // holds "[def]", BRE grammar
  regex rgx5 (str.begin(), str.end(),
    regex ::basic | regex ::icase);
                          // holds "[def]", BRE grammar,
                          // case insensitive
  return 0;
  }

16.4.3. Assigning basic_regex Objects

basic_regex& basic_regex::operator= (const Elem *ptr);
template<class STtraits, class STalloc>
  basic_regex& basic_regex::operator=(
    const basic_string<Elem, STtraits, STalloc>&str);
basic_regex& basic_regex::operator=(
  const basic_regex& right);

The operators each replace the regular expression held by *this with the regular expression defined by the operand sequence, then return *this.

The first two operators interpret the operand sequence in accordance with the ECMAScript grammar and no additional flags.

You cannot control the grammar or the other flags with an assignment.

Figure. basic_regex Assignment Operators (regexbasic/assign.cpp)

# include <regex>
# include <string>
using  std ::tr1 ::regex;
using  std ::string;

int main()
  { // demonstrate basic_regex assignment operators
  regex rgx;                   // empty regular expression object
  rgx = "abc";                 // holds  "abc", ECMAScript encoding
  string str("[def]");
  rgx = str;                   // holds  "[def]", ECMAScript encoding
  regex rgx1 ("abc [def]",  regex ::basic);
  rgx = rgx1;              // holds  "abc[def]", BRE encoding
  return 0;
  }

basic_regex & basic_regex ::assign ( const Elem * ptr,
  flag_type flags  = ECMAScript);
basic_regex & basic_regex ::assign (
  const Elem * ptr, size_type   count,
  flag_type flags  = ECMAScript);
template < class STtraits, class   STalloc >
basic_regex & basic_regex ::assign (
  const basic_string <Elem, STtraits, STalloc >& str,
  flag_type flags  = ECMAScript);
template < class   InIt >
  basic_regex & basic_regex ::assign ( InIt   first, InIt last,
    flag_type flags =   ECMAScript);
basic_regex & basic_regex ::assign ( const   basic_regex &  right);

Each of the member functions replaces the regular expression held by *this with the regular expression defined by the operand sequence interpreted in accordance with the flags argument, if present.

16.4.4. Swapping basic_regex Objects

void basic_regex ::swap ( basic_regex & other) throw ();
template < class Elem, class RXtraits >
  void swap ( basic_regex <Elem, RXtraits >& left,
    basic_regex <Elem, RXtraits >& right) throw ();

The member function swaps the regular expressions between *this and other.

The non-member function calls left.swap(right).

Figure. Member Function swap (regexbasic/swap.cpp)

#include <regex>
using std::tr1::regex;

int main()
  { // demonstrate use of swap
  regex  rgx0;            // empty regular expression object
  regex  rgx1("abc");     // holds  "abc"
  rgx0 . swap(rgx1);      // rgx0 holds  "abc" and rgx1 is empty
  swap(rgx0, rgx1);       // rgx0 is empty and rgx1 holds  "abc"
  return 0;
  }

Locales

locale_type basic_regex ::imbue ( locale_type loc);
locale_type basic_regex ::getloc () const ;

The first member function empties *this and calls imbue(loc) on the RXtraits object held by *this. The second member function returns a copy of the locale object held by the RXtraits object held by *this.

The interpretation of a regular expression depends on the locale that it was defined with. A basic_regex object does not keep a copy of the character sequence that defined its regular expression. The object can't reinterpret the character sequence in accordance with the new locale, so when you call imbue, it discards the previous regular expression. If you don't want to have an empty basic_regex object, you should provide a new regular expression by assigning from an operand sequence or calling assign or swap.

Access

unsigned basic_regex ::mark_count () const ;

The member function returns the number of capture groups in the regular expression.

When a basic_regex object was created with the flag nosubs, the regular expression engine is not required to keep track of the contents of capture groups. This does not affect the number of capture groups.

Figure. basic_regex::mark_count (regexbasic/markcount.cpp)

# include <regex>
# include <iostream>
using std :: tr1 :: regex ;
using std :: cout ;

void   show_count ( const char * title, const regex & rgx)
  {
  cout << ' \" ' <<  title <<  " \" has " <<  rgx.mark_count ()
    <<  " capture group "
    <<  ( rgx . mark_count () == 1 ? "" : "s")
    <<  ".\n";
  }

void show ( const char * expr)
  {
  regex rgx ( expr);
  show_count (expr, rgx);
  }

int main ()
  { // demonstrate use of mark_count
  show ("");
  show (" abc ");
  show ("( abc)");
  show ("(a)b(c)");
  show ("(a(b)c)");
  return 0;
  }

flag_type basic_regex ::flags () const ;

The member function returns a copy of the flags argument that was passed when the regular expression was defined. If *this is empty, it returns 0.

Figure. basic_regex::flags (regexbasic/flags.cpp)

# include <regex >
# include < iostream >
using std :: tr1 :: regex ;
using std :: cout ;

void   show_flags ( const regex & rgx)
  {   // extract and show flag values
  regex :: flag_type flags = rgx . flags ();
  if (( flags & regex :: ECMAScript) == regex :: ECMAScript)
    cout << " ECMAScript ";
  else if (( flags & regex :: basic) == regex :: basic)
    cout << " basic ";
  else if (( flags & regex :: extended) == regex :: extended)
    cout << " extended ";
  else if (( flags & regex :: grep) == regex :: grep)
    cout << " grep ";
  else if (( flags & regex :: egrep) == regex :: egrep)
    cout << " egrep ";
  else if (( flags & regex :: awk) == regex :: awk)
    cout << "awk ";
  else
    cout << " unknown grammar ";
  if (( flags & regex :: icase) == regex :: icase)
    cout << " | icase ";
  if (( flags & regex :: collate) == regex :: collate)
    cout << " | collate ";
  if (( flags & regex :: nosubs) == regex :: nosubs)
    cout << " | nosubs ";
  if (( flags & regex :: optimize) == regex :: optimize)
    cout << " | optimize ";
  cout <<   ' \n ' ;
  }

int main ()
  {   // demonstrate member function basic_regex::flags
  regex  rgx ;
  show_flags (rgx);
  rgx . assign ("", regex :: grep | regex :: nosubs);
  show_flags (rgx);
  rgx =   "a";
  show_flags (rgx);
  return 0;
  }

Nested Types and Flags

typedef Elem   basic_regex ::value_type ;
typedef   regex_constants :: syntax_option_type
  basic_regex ::flag_type ;
typedef typename RXtraits :: locale_type
  basic_regex ::locale_type ;

The first typedef is a synonym for the template argument Elem. The second typedef is a synonym for the type regex_constants::syntax_option_-type. The third typedef is a synonym for the type locale_type, defined in the template argument RXtraits.

static const flag_type basic_regex ::ECMAScript   =
  regex_constants :: ECMAScript ;
static const flag_type basic_regex :: basic =
  regex_constants :: basic ;
static const flag_type basic_regex ::extended   =
  regex_constants :: extended ;
static const flag_type basic_regex ::grep   =
  regex_constants ::grep ;
static const flag_type basic_regex :: egrep =
  regex_constants :: egrep ;
static const flag_type basic_regex :: awk =
  regex_constants :: awk ;

static const flag_type basic_regex :: nosubs =
  regex_constants :: nosubs ;
static const flag_type basic_regex ::optimize =
  regex_constants :: optimize ;

static const flag_type basic_regex ::icase =
  regex_constants :: icase ;
static const flag_type basic_regex ::collate   =
  regex_constants :: collate ;

These constants are self-explanatory. They duplicate the values of some of the constants defined in the namespace std::tr1::regex_constants. Writing regex::basic is shorter than writing std::tr1::regex_constants::basic.



 Python   SQL   Java   php   Perl 
 game development   web development   internet   *nix   graphics   hardware 
 telecommunications   C++ 
 Flash   Active Directory   Windows