[Boost-commit] svn:boost r43685 - trunk/boost/xpressive

From: eric_at_[hidden]
Date: 2008-03-17 17:46:08

Author: eric_niebler
Date: 2008-03-17 17:46:08 EDT (Mon, 17 Mar 2008)
New Revision: 43685
URL: http://svn.boost.org/trac/boost/changeset/43685

Log:
small interface simplification, doc comment improvements
Text files modified: 
   trunk/boost/xpressive/regex_algorithms.hpp |   207 ++++++++++++++++++++------------------- 
   1 files changed, 106 insertions(+), 101 deletions(-)

Modified: trunk/boost/xpressive/regex_algorithms.hpp
==============================================================================
--- trunk/boost/xpressive/regex_algorithms.hpp	(original)
+++ trunk/boost/xpressive/regex_algorithms.hpp	2008-03-17 17:46:08 EDT (Mon, 17 Mar 2008)
@@ -42,24 +42,24 @@
 
 /// \brief See if a regex matches a sequence from beginning to end.
 ///
-/// Determines whether there is an exact match between the regular expression re,
-/// and all of the sequence [begin, end).
+/// Determines whether there is an exact match between the regular expression \c re,
+/// and all of the sequence <tt>[begin, end)</tt>.
 ///
-/// \pre Types BidiIter and OtherBidiIter meet the requirements of a Bidirectional Iterator (24.1.4).
-/// \pre OtherBidiIter is convertible to BidiIter.
-/// \pre [begin,end) denotes a valid iterator range.
+/// \pre Type \c BidiIter meets the requirements of a Bidirectional Iterator (24.1.4).
+/// \pre <tt>[begin,end)</tt> denotes a valid iterator range.
 /// \param begin The beginning of the sequence.
 /// \param end The end of the sequence.
-/// \param what The match_results struct into which the sub_matches will be written
+/// \param what The \c match_results struct into which the sub_matches will be written
 /// \param re The regular expression object to use
-/// \param flags Optional match flags, used to control how the expression is matched against the sequence. (See match_flag_type.)
-/// \return true if a match is found, false otherwise
-/// \throw regex_error on stack exhaustion
-template<typename OtherBidiIter, typename BidiIter>
+/// \param flags Optional match flags, used to control how the expression is matched 
+///        against the sequence. (See \c match_flag_type.)
+/// \return \c true if a match is found, \c false otherwise
+/// \throw \c regex_error on stack exhaustion
+template<typename BidiIter>
 inline bool regex_match
 (
-    OtherBidiIter begin
-  , OtherBidiIter end
+    BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) begin
+  , BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) end
   , match_results<BidiIter> &what
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
@@ -96,18 +96,18 @@
 
 /// \overload
 ///
-template<typename OtherBidiIter, typename BidiIter>
+template<typename BidiIter>
 inline bool regex_match
 (
-    OtherBidiIter begin
-  , OtherBidiIter end
+    BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) begin
+  , BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) end
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
 )
 {
     // BUGBUG this is inefficient
     match_results<BidiIter> what;
-    return regex_match(begin, end, what, re, flags);
+    return xpressive::regex_match(begin, end, what, re, flags);
 }
 
 /// \overload
@@ -124,7 +124,7 @@
     // BUGBUG this is inefficient
     typedef typename remove_const<Char>::type char_type;
     Char *end = begin + std::char_traits<char_type>::length(begin);
-    return regex_match(begin, end, what, re, flags);
+    return xpressive::regex_match(begin, end, what, re, flags);
 }
 
 /// \overload
@@ -136,13 +136,13 @@
   , match_results<BidiIter> &what
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiRange> >::type * = 0
 )
 {
     // Note that the result iterator of the range must be convertible
     // to BidiIter here.
     BidiIter begin = boost::begin(rng), end = boost::end(rng);
-    return regex_match(begin, end, what, re, flags);
+    return xpressive::regex_match(begin, end, what, re, flags);
 }
 
 /// \overload
@@ -154,13 +154,13 @@
   , match_results<BidiIter> &what
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiRange> >::type * = 0
 )
 {
     // Note that the result iterator of the range must be convertible
     // to BidiIter here.
     BidiIter begin = boost::begin(rng), end = boost::end(rng);
-    return regex_match(begin, end, what, re, flags);
+    return xpressive::regex_match(begin, end, what, re, flags);
 }
 
 /// \overload
@@ -175,7 +175,7 @@
 {
     // BUGBUG this is inefficient
     match_results<Char *> what;
-    return regex_match(begin, what, re, flags);
+    return xpressive::regex_match(begin, what, re, flags);
 }
 
 /// \overload
@@ -186,12 +186,12 @@
     BidiRange &rng
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiRange> >::type * = 0
 )
 {
     // BUGBUG this is inefficient
     match_results<BidiIter> what;
-    return regex_match(rng, what, re, flags);
+    return xpressive::regex_match(rng, what, re, flags);
 }
 
 /// \overload
@@ -202,12 +202,12 @@
     BidiRange const &rng
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiRange> >::type * = 0
 )
 {
     // BUGBUG this is inefficient
     match_results<BidiIter> what;
-    return regex_match(rng, what, re, flags);
+    return xpressive::regex_match(rng, what, re, flags);
 }
 
 
@@ -330,25 +330,27 @@
 } // namespace detail
 
 
-/// \brief Determines whether there is some sub-sequence within [begin,end) that matches the regular expression re.
+/// \brief Determines whether there is some sub-sequence within <tt>[begin,end)</tt>
+/// that matches the regular expression \c re.
 ///
-/// Determines whether there is some sub-sequence within [begin,end) that matches the regular expression re.
+/// Determines whether there is some sub-sequence within <tt>[begin,end)</tt> that matches
+/// the regular expression \c re.
 ///
-/// \pre Types BidiIter and OtherBidiIter meet the requirements of a Bidirectional Iterator (24.1.4).
-/// \pre OtherBidiIter is convertible to BidiIter.
-/// \pre [begin,end) denotes a valid iterator range.
+/// \pre Type \c BidiIter meets the requirements of a Bidirectional Iterator (24.1.4).
+/// \pre <tt>[begin,end)</tt> denotes a valid iterator range.
 /// \param begin The beginning of the sequence
 /// \param end The end of the sequence
-/// \param what The match_results struct into which the sub_matches will be written
+/// \param what The \c match_results struct into which the sub_matches will be written
 /// \param re The regular expression object to use
-/// \param flags Optional match flags, used to control how the expression is matched against the sequence. (See match_flag_type.)
-/// \return true if a match is found, false otherwise
-/// \throw regex_error on stack exhaustion
-template<typename OtherBidiIter, typename BidiIter>
+/// \param flags Optional match flags, used to control how the expression is matched against
+///        the sequence. (See \c match_flag_type.)
+/// \return \c true if a match is found, \c false otherwise
+/// \throw \c regex_error on stack exhaustion
+template<typename BidiIter>
 inline bool regex_search
 (
-    OtherBidiIter begin
-  , OtherBidiIter end
+    BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) begin
+  , BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) end
   , match_results<BidiIter> &what
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
@@ -371,18 +373,18 @@
 
 /// \overload
 ///
-template<typename OtherBidiIter, typename BidiIter>
+template<typename BidiIter>
 inline bool regex_search
 (
-    OtherBidiIter begin
-  , OtherBidiIter end
+    BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) begin
+  , BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) end
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
 )
 {
     // BUGBUG this is inefficient
     match_results<BidiIter> what;
-    return regex_search(begin, end, what, re, flags);
+    return xpressive::regex_search(begin, end, what, re, flags);
 }
 
 /// \overload
@@ -399,7 +401,7 @@
     // BUGBUG this is inefficient
     typedef typename remove_const<Char>::type char_type;
     Char *end = begin + std::char_traits<char_type>::length(begin);
-    return regex_search(begin, end, what, re, flags);
+    return xpressive::regex_search(begin, end, what, re, flags);
 }
 
 /// \overload
@@ -411,13 +413,13 @@
   , match_results<BidiIter> &what
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiRange> >::type * = 0
 )
 {
     // Note that the result iterator of the range must be convertible
     // to BidiIter here.
     BidiIter begin = boost::begin(rng), end = boost::end(rng);
-    return regex_search(begin, end, what, re, flags);
+    return xpressive::regex_search(begin, end, what, re, flags);
 }
 
 /// \overload
@@ -429,13 +431,13 @@
   , match_results<BidiIter> &what
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiRange> >::type * = 0
 )
 {
     // Note that the result iterator of the range must be convertible
     // to BidiIter here.
     BidiIter begin = boost::begin(rng), end = boost::end(rng);
-    return regex_search(begin, end, what, re, flags);
+    return xpressive::regex_search(begin, end, what, re, flags);
 }
 
 /// \overload
@@ -450,7 +452,7 @@
 {
     // BUGBUG this is inefficient
     match_results<Char *> what;
-    return regex_search(begin, what, re, flags);
+    return xpressive::regex_search(begin, what, re, flags);
 }
 
 /// \overload
@@ -461,12 +463,12 @@
     BidiRange &rng
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiRange> >::type * = 0
 )
 {
     // BUGBUG this is inefficient
     match_results<BidiIter> what;
-    return regex_search(rng, what, re, flags);
+    return xpressive::regex_search(rng, what, re, flags);
 }
 
 /// \overload
@@ -477,12 +479,12 @@
     BidiRange const &rng
   , basic_regex<BidiIter> const &re
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiRange> >::type * = 0
 )
 {
     // BUGBUG this is inefficient
     match_results<BidiIter> what;
-    return regex_search(rng, what, re, flags);
+    return xpressive::regex_search(rng, what, re, flags);
 }
 
 
@@ -494,14 +496,14 @@
 {
 ///////////////////////////////////////////////////////////////////////////////
 // regex_replace_impl
-template<typename OutIter, typename BidiIter, typename ForwardRangeOrNTBS>
+template<typename OutIter, typename BidiIter, typename Formatter>
 inline OutIter regex_replace_impl
 (
     OutIter out
   , BidiIter begin
   , BidiIter end
   , basic_regex<BidiIter> const &re
-  , ForwardRangeOrNTBS const &format
+  , Formatter const &format
   , regex_constants::match_flag_type flags = regex_constants::match_default
 )
 {
@@ -553,120 +555,123 @@
 } // namespace detail
 
 /// \brief Build an output sequence given an input sequence, a regex, and a format string or
-/// a formatter object or function.
-///
-/// Constructs a regex_iterator object: regex_iterator\< BidiIter \> i(begin, end, re, flags),
-/// and uses i to enumerate through all of the matches m of type match_results\< BidiIter \> that
-/// occur within the sequence [begin, end). If no such matches are found and !(flags \& format_no_copy)
-/// then calls std::copy(begin, end, out). Otherwise, for each match found, if !(flags \& format_no_copy)
-/// calls std::copy(m.prefix().first, m.prefix().second, out), and then calls m.format(out, format, flags).
-/// Finally if !(flags \& format_no_copy) calls std::copy(last_m.suffix().first, last_m.suffix().second, out)
-/// where last_m is a copy of the last match found. If flags \& format_first_only is non-zero then only
-/// the first match found is replaced.
-///
-/// \pre Types BidiIter and OtherBidiIter meet the requirements of a Bidirectional Iterator (24.1.4).
-/// \pre Type OutIter meets the requirements of an Output Iterator (24.1.2).
-/// \pre OtherBidiIter is convertible to BidiIter.
-/// \pre [begin,end) denotes a valid iterator range.
+/// a formatter object, function, or expression.
 ///
+/// Constructs a \c regex_iterator object: <tt>regex_iterator\< BidiIter \> i(begin, end, re, flags)</tt>,
+/// and uses \c i to enumerate through all of the matches m of type <tt>match_results\< BidiIter \></tt> that
+/// occur within the sequence <tt>[begin, end)</tt>. If no such matches are found and <tt>!(flags \& format_no_copy)</tt>
+/// then calls <tt>std::copy(begin, end, out)</tt>. Otherwise, for each match found, if <tt>!(flags \& format_no_copy)</tt>
+/// calls <tt>std::copy(m.prefix().first, m.prefix().second, out)</tt>, and then calls <tt>m.format(out, format, flags)</tt>.
+/// Finally if <tt>!(flags \& format_no_copy)</tt> calls <tt>std::copy(last_m.suffix().first, last_m.suffix().second, out)</tt>
+/// where \c last_m is a copy of the last match found.
+///
+/// If <tt>flags \& format_first_only</tt> is non-zero then only the first match found is replaced.
+///
+/// \pre Type \c BidiIter meets the requirements of a Bidirectional Iterator (24.1.4).
+/// \pre Type \c OutIter meets the requirements of an Output Iterator (24.1.2).
+/// \pre Type \c Formatter models \c ForwardRange, <tt>Callable\<match_results\<BidiIter\> \></tt>, 
+///      <tt>Callable\<match_results\<BidiIter\>, OutIter\></tt>, or
+///      <tt>Callable\<match_results\<BidiIter\>, OutIter, regex_constants::match_flag_type\></tt>;
+///      or else it is a null-terminated format string, or an expression template
+///      representing a formatter lambda expression.
+/// \pre <tt>[begin,end)</tt> denotes a valid iterator range.
 /// \param out An output iterator into which the output sequence is written.
 /// \param begin The beginning of the input sequence.
 /// \param end The end of the input sequence.
 /// \param re The regular expression object to use.
 /// \param format The format string used to format the replacement sequence,
-///        or a formatter function or function object.
-/// \param flags Optional match flags, used to control how the expression is matched against the sequence. (See match_flag_type.)
+///        or a formatter function, function object, or expression.
+/// \param flags Optional match flags, used to control how the expression is matched against
+///        the sequence. (See \c match_flag_type.)
 /// \return The value of the output iterator after the output sequence has been written to it.
-/// \throw regex_error on stack exhaustion or invalid format string.
-template<typename OutIter, typename OtherBidiIter, typename BidiIter, typename ForwardRange>
+/// \throw \c regex_error on stack exhaustion or invalid format string.
+template<typename OutIter, typename BidiIter, typename Formatter>
 inline OutIter regex_replace
 (
     OutIter out
-  , OtherBidiIter begin
-  , OtherBidiIter end
+  , BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) begin
+  , BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) end
   , basic_regex<BidiIter> const &re
-  , ForwardRange const &format
+  , Formatter const &format
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<detail::is_char_ptr<ForwardRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<Formatter> >::type * = 0
 )
 {
-    BidiIter begin_ = begin, end_ = end;
-    return detail::regex_replace_impl(out, begin_, end_, re, format, flags);
+    return detail::regex_replace_impl(out, begin, end, re, format, flags);
 }
 
 /// \overload
 ///
-template<typename OutIter, typename OtherBidiIter, typename BidiIter>
+template<typename OutIter, typename BidiIter>
 inline OutIter regex_replace
 (
     OutIter out
-  , OtherBidiIter begin
-  , OtherBidiIter end
+  , BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) begin
+  , BOOST_XPR_NONDEDUCED_TYPE_(BidiIter) end
   , basic_regex<BidiIter> const &re
   , typename iterator_value<BidiIter>::type const *format
   , regex_constants::match_flag_type flags = regex_constants::match_default
 )
 {
-    BidiIter begin_ = begin, end_ = end;
-    return detail::regex_replace_impl(out, begin_, end_, re, format, flags);
+    return detail::regex_replace_impl(out, begin, end, re, format, flags);
 }
 
 /// \overload
 ///
-template<typename BidiContainer, typename BidiIter, typename ForwardRange>
+template<typename BidiContainer, typename BidiIter, typename Formatter>
 inline BidiContainer regex_replace
 (
     BidiContainer &str
   , basic_regex<BidiIter> const &re
-  , ForwardRange const &format
+  , Formatter const &format
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<mpl::or_<is_pointer<BidiContainer>, detail::is_char_ptr<ForwardRange> > >::type * = 0
+  , typename disable_if<mpl::or_<detail::is_char_ptr<BidiContainer>, detail::is_char_ptr<Formatter> > >::type * = 0
 )
 {
     BidiContainer result;
     // Note that the result iterator of the range must be convertible
     // to BidiIter here.
     BidiIter begin = boost::begin(str), end = boost::end(str);
-    regex_replace(std::back_inserter(result), begin, end, re, format, flags);
+    xpressive::regex_replace(std::back_inserter(result), begin, end, re, format, flags);
     return result;
 }
 
 /// \overload
 ///
-template<typename BidiContainer, typename BidiIter, typename ForwardRange>
+template<typename BidiContainer, typename BidiIter, typename Formatter>
 inline BidiContainer regex_replace
 (
     BidiContainer const &str
   , basic_regex<BidiIter> const &re
-  , ForwardRange const &format
+  , Formatter const &format
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<mpl::or_<is_pointer<BidiContainer>, detail::is_char_ptr<ForwardRange> > >::type * = 0
+  , typename disable_if<mpl::or_<detail::is_char_ptr<BidiContainer>, detail::is_char_ptr<Formatter> > >::type * = 0
 )
 {
     BidiContainer result;
     // Note that the result iterator of the range must be convertible
     // to BidiIter here.
     BidiIter begin = boost::begin(str), end = boost::end(str);
-    regex_replace(std::back_inserter(result), begin, end, re, format, flags);
+    xpressive::regex_replace(std::back_inserter(result), begin, end, re, format, flags);
     return result;
 }
 
 /// \overload
 ///
-template<typename Char, typename ForwardRange>
+template<typename Char, typename Formatter>
 inline std::basic_string<typename remove_const<Char>::type> regex_replace
 (
     BOOST_XPR_NONDEDUCED_TYPE_(Char) *str
   , basic_regex<Char *> const &re
-  , ForwardRange const &format
+  , Formatter const &format
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<detail::is_char_ptr<ForwardRange> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<Formatter> >::type * = 0
 )
 {
     typedef typename remove_const<Char>::type char_type;
     std::basic_string<char_type> result;
     Char *end = str + std::char_traits<char_type>::length(str);
-    regex_replace(std::back_inserter(result), str, end, re, format, flags);
+    xpressive::regex_replace(std::back_inserter(result), str, end, re, format, flags);
     return result;
 }
 
@@ -679,14 +684,14 @@
   , basic_regex<BidiIter> const &re
   , typename iterator_value<BidiIter>::type const *format
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiContainer> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiContainer> >::type * = 0
 )
 {
     BidiContainer result;
     // Note that the result iterator of the range must be convertible
     // to BidiIter here.
     BidiIter begin = boost::begin(str), end = boost::end(str);
-    regex_replace(std::back_inserter(result), begin, end, re, format, flags);
+    xpressive::regex_replace(std::back_inserter(result), begin, end, re, format, flags);
     return result;
 }
 
@@ -699,14 +704,14 @@
   , basic_regex<BidiIter> const &re
   , typename iterator_value<BidiIter>::type const *format
   , regex_constants::match_flag_type flags = regex_constants::match_default
-  , typename disable_if<is_pointer<BidiContainer> >::type * = 0
+  , typename disable_if<detail::is_char_ptr<BidiContainer> >::type * = 0
 )
 {
     BidiContainer result;
     // Note that the result iterator of the range must be convertible
     // to BidiIter here.
     BidiIter begin = boost::begin(str), end = boost::end(str);
-    regex_replace(std::back_inserter(result), begin, end, re, format, flags);
+    xpressive::regex_replace(std::back_inserter(result), begin, end, re, format, flags);
     return result;
 }
 
@@ -724,7 +729,7 @@
     typedef typename remove_const<Char>::type char_type;
     std::basic_string<char_type> result;
     Char *end = str + std::char_traits<char_type>::length(str);
-    regex_replace(std::back_inserter(result), str, end, re, format, flags);
+    xpressive::regex_replace(std::back_inserter(result), str, end, re, format, flags);
     return result;
 }