Boost.Regex: Algorithm regex_format (deprecated)

###  | # 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 24 Oct 2003

© Copyright John Maddock 1998- 2003

Use, modification and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)