28 Text processing library [text]

28.6 Regular expressions library [re]

28.6.2 Requirements [re.req]

This subclause defines requirements on classes representing regular expression traits.
[Note 1: 
The class template regex_traits, defined in [re.traits], meets these requirements.
— end note]
The class template basic_regex, defined in [re.regex], needs a set of related types and functions to complete the definition of its semantics.
These types and functions are provided as a set of member typedef-names and functions in the template parameter traits used by the basic_regex class template.
This subclause defines the semantics of these members.
To specialize class template basic_regex for a character container CharT and its related regular expression traits class Traits, use basic_regex<CharT, Traits>.
In the following requirements,
  • X denotes a traits class defining types and functions for the character container type charT;
  • u is an object of type X;
  • v is an object of type const X;
  • p is a value of type const charT*;
  • I1 and I2 are input iterators ([input.iterators]);
  • F1 and F2 are forward iterators ([forward.iterators]);
  • c is a value of type const charT;
  • s is an object of type X​::​string_type;
  • cs is an object of type const X​::​string_type;
  • b is a value of type bool;
  • I is a value of type int;
  • cl is an object of type X​::​char_class_type; and
  • loc is an object of type X​::​locale_type.
A traits class X meets the regular expression traits requirements if the following types and expressions are well-formed and have the specified semantics.
typename X::char_type
Result: charT, the character container type used in the implementation of class template basic_regex.
typename X::string_type
Result: basic_string<charT>
typename X::locale_type
Result: A copy constructible type that represents the locale used by the traits class.
typename X::char_class_type
Result: A bitmask type ([bitmask.types]) representing a particular character classification.
X::length(p)
Result: size_t
Returns: The smallest i such that p[i] == 0.
Complexity: Linear in i.
v.translate(c)
Result: X​::​char_type
Returns: A character such that for any character d that is to be considered equivalent to c then v.translate(c) == v.translate(d).
v.translate_nocase(c)
Result: X​::​char_type
Returns: For all characters C that are to be considered equivalent to c when comparisons are to be performed without regard to case, then v.translate_nocase(c) == v.translate_nocase(C).
v.transform(F1, F2)
Result: X​::​string_type
Returns: A sort key for the character sequence designated by the iterator range [F1, F2) such that if the character sequence [G1, G2) sorts before the character sequence [H1, H2) then v.transform(G1, G2) < v.transform(H1, H2).
v.transform_primary(F1, F2)
Result: X​::​string_type
Returns: A sort key for the character sequence designated by the iterator range [F1, F2) such that if the character sequence [G1, G2) sorts before the character sequence [H1, H2) when character case is not considered then v.transform_primary(G1, G2) < v.transform_primary(H1, H2).
v.lookup_collatename(F1, F2)
Result: X​::​string_type
Returns: A sequence of characters that represents the collating element consisting of the character sequence designated by the iterator range [F1, F2).
Returns an empty string if the character sequence is not a valid collating element.
v.lookup_classname(F1, F2, b)
Result: X​::​char_class_type
Returns: Converts the character sequence designated by the iterator range [F1, F2) into a value of a bitmask type that can subsequently be passed to isctype.
Values returned from lookup_classname can be bitwise or'ed together; the resulting value represents membership in either of the corresponding character classes.
If b is true, the returned bitmask is suitable for matching characters without regard to their case.
Returns 0 if the character sequence is not the name of a character class recognized by X.
The value returned shall be independent of the case of the characters in the sequence.
v.isctype(c, cl)
Result: bool
Returns: Returns true if character c is a member of one of the character classes designated by cl, false otherwise.
v.value(c, I)
Result: int
Returns: Returns the value represented by the digit c in base I if the character c is a valid digit in base I; otherwise returns -1.
[Note 2: 
The value of I will only be 8, 10, or 16.
— end note]
u.imbue(loc)
Result: X​::​locale_type
Effects: Imbues u with the locale loc and returns the previous locale used by u if any.
v.getloc()
Result: X​::​locale_type
Returns: Returns the current locale used by v, if any.
[Note 3: 
Class template regex_traits meets the requirements for a regular expression traits class when it is specialized for char or wchar_t.
This class template is described in the header <regex>, and is described in [re.traits].
— end note]