std::match_results::format

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Regular expressions library

Classes

basic_regex (C++11)

sub_match (C++11)

match_results (C++11)

Algorithms

regex_match (C++11)

regex_search (C++11)

regex_replace (C++11)

Iterators

regex_iterator (C++11)

regex_token_iterator (C++11)

Exceptions

regex_error (C++11)

Traits

regex_traits (C++11)

Constants

syntax_option_type (C++11)

match_flag_type (C++11)

error_type (C++11)

Regex Grammar

Modified ECMAScript-262 (C++11)

std::match_results

Member functions

match_results::match_results

match_results::~match_results

match_results::operator=

match_results::get_allocator

State

match_results::ready

Element access

match_results::size

match_results::max_size

match_results::empty

match_results::length

match_results::position

match_results::str

match_results::operator[]

match_results::prefix

match_results::suffix

Iterators

match_results::beginmatch_results::cbegin

match_results::endmatch_results::cend

Format

match_results::format

Modifiers

match_results::swap

template< class OutputIt > OutputIter format( OutputIt out, const char_type* fmt_first, const char_type* fmt_last, std::regex_constants::match_flag_type flags = std::regex_constants::format_default ) const;	(1)	(since C++11)
template< class OutputIt, class ST, class SA > OutputIter format( OutputIt out, const basic_string<char_type,ST,SA>& fmt, std::regex_constants::match_flag_type flags = std::regex_constants::format_default ) const;	(2)	(since C++11)
template< class ST, class SA > std::basic_string<char_type,ST,SA> format( const std::basic_string<char_type,ST,SA>& fmt, std::regex_constants::match_flag_type flags = std::regex_constants::format_default ) const;	(3)	(since C++11)
string_type format( const char_type* fmt_s, std::regex_constants::match_flag_type flags = std::regex_constants::format_default ) const;	(4)	(since C++11)

format outputs a format string, replacing any format specifiers or escape sequences in that string with match data from *this.

1) The format character sequence is defined by the range [fmt_first, fmt_last). The resulting character sequence is copied to out.

2) The format character sequence is defined by the characters in fmt. The resulting character sequence is copied to out.

3-4) The format character sequence is defined by the characters in fmt and fmt_s respectively. The resulting character sequence is copied to a newly constructed std::basic_string, which is returned.

The flags bitmask determines which format specifiers and escape sequences are recognized.

The behavior of format is undefined if ready() != true.

Parameters

fmt_begin, fmt_end	-	pointers to a range of characters defining the format character sequence
fmt	-	std::basic_string defining the format character sequence
fmt_s	-	pointer to a null-terminated character string defining the format character sequence
out	-	iterator that the resulting character sequence is copied to
flags	-	std::regex_constants::match_flag_type bitmask specifying which format specifiers and escape sequences are recognized
Type requirements
- OutputIt must meet the requirements of OutputIterator.

Return value

1-2) out

3-4) The newly constructed string containing resulting character sequence.

Exceptions

(none)

Example

Run this code

#include <iostream>
#include <string>
#include <regex>

int main()
{
    std::string s = "for a good time, call 867-5309";
    std::regex phone_regex("\\d{3}-\\d{4}");
    std::smatch phone_match;

    if (std::regex_search(s, phone_match, phone_regex)) {
        std::string fmt_s = phone_match.format(
            "$`"    // $` means characters before the match
            "[$&]"  // $& means the matched characters
            "$'");  // $' means characters following the match
        std::cout << fmt_s << '\n';
    }   
}

Output:

for a good time, call [867-5309]

See also

regex_replace (C++11)	replaces occurrences of a regular expression with formatted replacement text (function template)
match_flag_type (C++11)	options specific to matching (typedef)