regex_traits Class

Describes characteristics of elements for matching.

Syntax

template<class Elem>
class regex_traits

Parameters

Elem
The character element type to describe.

Remarks

The class template describes various regular expression traits for type Elem. The class template basic_regex Class uses this information to manipulate elements of type Elem.

Each regex_traits object holds an object of type regex_traits::locale which is used by some of its member functions. The default locale is a copy of regex_traits::locale(). The member function imbue replaces the locale object, and the member function getloc returns a copy of the locale object.

Constructors

Constructor	Description
regex_traits	Constructs the object.

Typedefs

Type name	Description
char_class_type	The type of character class designators.
char_type	The type of an element.
locale_type	The type of the stored locale object.
size_type	The type of a sequence length.
string_type	The type of a string of elements.

Member functions

Member function	Description
getloc	Returns the stored locale object.
imbue	Alters the stored locale object.
isctype	Tests for class membership.
length	Returns the length of a null-terminated sequence.
lookup_classname	Maps a sequence to a character class.
lookup_collatename	Maps a sequence to a collating element.
transform	Converts to equivalent ordered sequence.
transform_primary	Converts to equivalent caseless ordered sequence.
translate	Converts to equivalent matching element.
translate_nocase	Converts to equivalent caseless matching element.
value	Converts an element to a digit value.

Requirements

Header: <regex>

Namespace: std

Example

// std__regex__regex_traits.cpp
// compile with: /EHsc
#include <regex>
#include <iostream>

typedef std::regex_traits<char> Mytr;
int main()
    {
    Mytr tr;

    Mytr::char_type ch = tr.translate('a');
    std::cout << "translate('a') == 'a' == " << std::boolalpha
        << (ch == 'a') << std::endl;

    std::cout << "nocase 'a' == 'A' == " << std::boolalpha
        << (tr.translate_nocase('a') == tr.translate_nocase('A'))
        << std::endl;

    const char *lbegin = "abc";
    const char *lend = lbegin + strlen(lbegin);
    Mytr::size_type size = tr.length(lbegin);
    std::cout << "length(\"abc\") == " << size <<std::endl;

    Mytr::string_type str = tr.transform(lbegin, lend);
    std::cout << "transform(\"abc\") < \"abc\" == " << std::boolalpha
        << (str < "abc") << std::endl;

    const char *ubegin = "ABC";
    const char *uend = ubegin + strlen(ubegin);
    std::cout << "primary \"ABC\" < \"abc\" == " << std::boolalpha
        << (tr.transform_primary(ubegin, uend) <
            tr.transform_primary(lbegin, lend))
        << std::endl;

    const char *dig = "digit";
    Mytr::char_class_type cl = tr.lookup_classname(dig, dig + 5);
    std::cout << "class digit == d == " << std::boolalpha
        << (cl == tr.lookup_classname(dig, dig + 1))
        << std::endl;

    std::cout << "'3' is digit == " <<std::boolalpha
        << tr.isctype('3', tr.lookup_classname(dig, dig + 5))
        << std::endl;

    std::cout << "hex C == " << tr.value('C', 16) << std::endl;

// other members
    str = tr.lookup_collatename(dig, dig + 5);

    Mytr::locale_type loc = tr.getloc();
    tr.imbue(loc);

    return (0);
    }

translate('a') == 'a' == true
nocase 'a' == 'A' == true
length("abc") == 3
transform("abc") < "abc" == false
primary "ABC" < "abc" == false
class digit == d == true
'3' is digit == true
hex C == 12

regex_traits::char_class_type

The type of character class designators.

typedef T8 char_class_type;

Remarks

The type is a synonym for an unspecified type that designates character classes. Values of this type can be combined using the | operator to designate character classes that are the union of the classes designated by the operands.

regex_traits::char_type

The type of an element.

typedef Elem char_type;

Remarks

The typedef is a synonym for the template argument Elem.

regex_traits::getloc

Returns the stored locale object.

locale_type getloc() const;

Remarks

The member function returns the stored locale object.

regex_traits::imbue

Alters the stored locale object.

locale_type imbue(locale_type loc);

Parameters

loc
The locale object to store.

Remarks

The member function copies loc to the stored locale object and returns a copy of the previous value of the stored locale object.

regex_traits::isctype

Tests for class membership.

bool isctype(char_type ch, char_class_type cls) const;

Parameters

ch
The element to test.

cls
The classes to test for.

Remarks

The member function returns true only if the character ch is in the character class designated by cls.

regex_traits::length

Returns the length of a null-terminated sequence.

static size_type length(const char_type *str);

Parameters

str
The null-terminated sequence.

Remarks

The static member function returns std::char_traits<char_type>::length(str).

regex_traits::locale_type

The type of the stored locale object.

typedef T7 locale_type;

Remarks

The typedef is a synonym for a type that encapsulates locales. In the specializations regex_traits<char> and regex_traits<wchar_t> it is a synonym for std::locale.

regex_traits::lookup_classname

Maps a sequence to a character class.

template <class FwdIt>
char_class_type lookup_classname(FwdIt first, FwdIt last) const;

Parameters

first
Beginning of sequence to look up.

last
End of sequence to look up.

Remarks

The member function returns a value that designates the character class named by the character sequence pointed to by its arguments. The value does not depend on the case of the characters in the sequence.

The specialization regex_traits<char> recognizes the names "d", "s", "w", "alnum", "alpha", "blank", "cntrl", "digit", "graph", "lower", "print", "punct", "space", "upper", and "xdigit", all without regard to case.

The specialization regex_traits<wchar_t> recognizes the names L"d", L"s", L"w", L"alnum", L"alpha", L"blank", L"cntrl", L"digit", L"graph", L"lower", L"print", L"punct", L"space", L"upper", and L"xdigit", all without regard to case.

regex_traits::lookup_collatename

Maps a sequence to a collating element.

template <class FwdIt>
string_type lookup_collatename(FwdIt first, FwdIt last) const;

Parameters

first
Beginning of sequence to look up.

last
End of sequence to look up.

Remarks

The member function returns a string object containing the collating element corresponding to the sequence [first, last), or an empty string if the sequence is not a valid collating element.

regex_traits::regex_traits

Constructs the object.

regex_traits();

Remarks

The constructor constructs an object whose stored locale object is initialized to the default locale.

regex_traits::size_type

The type of a sequence length.

typedef T6 size_type;

Remarks

The typedef is a synonym for an unsigned integral type. In the specializations regex_traits<char> and regex_traits<wchar_t> it is a synonym for std::size_t.

The typedef is a synonym for std::size_t.

regex_traits::string_type

The type of a string of elements.

typedef basic_string<Elem> string_type;

Remarks

The typedef is a synonym for basic_string<Elem>.

regex_traits::transform

Converts to equivalent ordered sequence.

template <class FwdIt>
string_type transform(FwdIt first, FwdIt last) const;

Parameters

first
Beginning of sequence to transform.

last
End of sequence to transform.

Remarks

The member function returns a string that it generates by using a transformation rule that depends on the stored locale object. For two character sequences designated by the iterator ranges [first1, last1) and [first2, last2), transform(first1, last1) < transform(first2, last2) if the character sequence designated by the iterator range [first1, last1) sorts before the character sequence designated by the iterator range [first2, last2).

regex_traits::transform_primary

Converts to equivalent caseless ordered sequence.

template <class FwdIt>
string_type transform_primary(FwdIt first, FwdIt last) const;

Parameters

first
Beginning of sequence to transform.

last
End of sequence to transform.

Remarks

The member function returns a string that it generates by using a transformation rule that depends on the stored locale object. For two character sequences designated by the iterator ranges [first1, last1) and [first2, last2), transform_primary(first1, last1) < transform_primary(first2, last2) if the character sequence designated by the iterator range [first1, last1) sorts before the character sequence designated by the iterator range [first2, last2) without regard for case or accents.

regex_traits::translate

Converts to equivalent matching element.

char_type translate(char_type ch) const;

Parameters

ch
The element to convert.

Remarks

The member function returns a character that it generates by using a transformation rule that depends on the stored locale object. For two char_type objects ch1 and ch2, translate(ch1) == translate(ch2) only if ch1 and ch2 should match when one occurs in the regular expression definition and the other occurs at a corresponding position in the target sequence for a locale-sensitive match.

regex_traits::translate_nocase

Converts to equivalent caseless matching element.

char_type translate_nocase(char_type ch) const;

Parameters

ch
The element to convert.

Remarks

The member function returns a character that it generates by using a transformation rule that depends on the stored locale object. For two char_type objects ch1 and ch2, translate_nocase(ch1) == translate_nocase(ch2) only if ch1 and ch2 should match when one occurs in the regular expression definition and the other occurs at a corresponding position in the target sequence for a case-insensitive match.

regex_traits::value

Converts an element to a digit value.

int value(Elem ch, int radix) const;

Parameters

ch
The element to convert.

radix
The arithmetic base to use.

Remarks

The member function returns the value represented by the character ch in the base radix, or -1 if ch is not a valid digit in the base radix. The function will only be called with a radix argument of 8, 10, or 16.

See also

<regex>
regex_constants Class
regex_error Class
<regex> functions
regex_iterator Class
<regex> operators
regex_token_iterator Class
<regex> typedefs
regex_traits<char> Class
regex_traits<wchar_t> Class