Boost.Regex

Algorithm regex_format (deprecated)

The algorithm regex_format is deprecated; new code should use match_results::format instead. Existing code will continue to compile, the following documentation is taken from the previous version of boost.regex and will not be further updated:

Algorithm regex_format

#include <boost/regex.hpp>

The algorithm regex_format takes the results of a match and creates a new string based upon a format string, regex_format can be used for search and replace operations:

template <class OutputIterator, class iterator, class Allocator, class charT>
OutputIterator regex_format(OutputIterator out,
                            const match_results<iterator, Allocator>& m,
                            const charT* fmt,
                            match_flag_type flags = 0);
template <class OutputIterator, class iterator, class Allocator, class charT>
OutputIterator regex_format(OutputIterator out,
                            const match_results<iterator, Allocator>& m,
                            const std::basic_string<charT>& fmt,
                            match_flag_type flags = 0);

The library also defines the following convenience variation of regex_format, which returns the result directly as a string, rather than outputting to an iterator [note - this version may not be available, or may be available in a more limited form, depending upon your compilers capabilities]:

template <class iterator, class Allocator, class charT>
std::basic_string<charT> regex_format
                                 (const match_results<iterator, Allocator>& m, 
                                  const charT* fmt,
                                  match_flag_type flags = 0);

template <class iterator, class Allocator, class charT>
std::basic_string<charT> regex_format
                                 (const match_results<iterator, Allocator>& m, 
                                  const std::basic_string<charT>& fmt,
                                  match_flag_type flags = 0);

Parameters to the main version of the function are passed as follows:

	OutputIterator out	An output iterator type, the output string is sent to this iterator. Typically this would be a std::ostream_iterator.
	const match_results<iterator, Allocator>& m	An instance of match_results<> obtained from one of the matching algorithms above, and denoting what matched.
	const charT* fmt	A format string that determines how the match is transformed into the new string.
	unsigned flags	Optional flags which describe how the format string is to be interpreted.

Format flags are defined as follows:

	format_all	Enables all syntax options (perl-like plus extentions).
	format_sed	Allows only a sed-like syntax.
	format_perl	Allows only a perl-like syntax.
	format_no_copy	Disables copying of unmatched sections to the output string during regex_merge operations.
	format_first_only	When this flag is set only the first occurance will be replaced (applies to regex_merge only).

The format string syntax (and available options) is described more fully under format strings .

Revised 17 May 2003

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Dr John Maddock makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.