From 2313938e75f98487eb83d605e0670e2d108c3353 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Tue, 7 May 2019 16:30:40 +0100 Subject: [PATCH] Improve API docs for std::regex * include/bits/regex.h: Improve docs. * include/bits/regex.tcc: Do not document implementation details. From-SVN: r270952 --- libstdc++-v3/ChangeLog | 3 ++ libstdc++-v3/include/bits/regex.h | 46 +++++++++++++++++++---------- libstdc++-v3/include/bits/regex.tcc | 12 ++++++-- 3 files changed, 43 insertions(+), 18 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 19f90999584..5acf43eab33 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,8 @@ 2019-05-07 Jonathan Wakely + * include/bits/regex.h: Improve docs. + * include/bits/regex.tcc: Do not document implementation details. + * testsuite/19_diagnostics/error_code/hash.cc: New test. 2019-05-06 François Dumont diff --git a/libstdc++-v3/include/bits/regex.h b/libstdc++-v3/include/bits/regex.h index 7576cd7a9c0..76219b5ae3b 100644 --- a/libstdc++-v3/include/bits/regex.h +++ b/libstdc++-v3/include/bits/regex.h @@ -838,6 +838,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 * @brief Swaps the contents of two regular expression objects. * @param __lhs First regular expression. * @param __rhs Second regular expression. + * @relates basic_regex */ template inline void @@ -937,10 +938,12 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 { return this->_M_str().compare(__s); } // @} + /// @cond undocumented // Non-standard, used by comparison operators int _M_compare(const value_type* __s, size_t __n) const { return this->_M_str().compare({__s, __n}); } + /// @endcond private: // Simplified basic_string_view for C++11 @@ -1015,6 +1018,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 // [7.9.2] sub_match non-member operators + /// @relates sub_match @{ + /** * @brief Tests the equivalence of two regular expression submatches. * @param __lhs First regular expression submatch. @@ -1081,11 +1086,14 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 operator>(const sub_match<_BiIter>& __lhs, const sub_match<_BiIter>& __rhs) { return __lhs.compare(__rhs) > 0; } + /// @cond undocumented + // Alias for a basic_string that can be compared to a sub_match. template using __sub_match_string = basic_string< typename iterator_traits<_Bi_iter>::value_type, _Ch_traits, _Ch_alloc>; + /// @endcond /** * @brief Tests the equivalence of a string and a regular expression @@ -1554,6 +1562,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 const sub_match<_Bi_iter>& __m) { return __os << __m.str(); } + // @} relates sub_match + // [7.10] Class template match_results /** @@ -1575,8 +1585,6 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 * of characters [first, second) which formed that match. Otherwise matched * is false, and members first and second point to the end of the sequence * that was searched. - * - * @nosubgrouping */ template > > @@ -1606,7 +1614,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 public: /** - * @name 10.? Public Types + * @name 28.10 Public Types */ //@{ typedef sub_match<_Bi_iter> value_type; @@ -1630,17 +1638,18 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 /** * @brief Constructs a default %match_results container. * @post size() returns 0 and str() returns an empty string. - * @{ */ match_results() : match_results(_Alloc()) { } + /** + * @brief Constructs a default %match_results container. + * @post size() returns 0 and str() returns an empty string. + */ explicit match_results(const _Alloc& __a) noexcept : _Base_type(__a) { } - // @} - /** * @brief Copy constructs a %match_results. */ @@ -1712,7 +1721,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 //@} /** - * @name 10.3 Element Access + * @name 28.10.4 Element Access */ //@{ @@ -1837,7 +1846,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 //@} /** - * @name 10.4 Formatting + * @name 28.10.5 Formatting * * These functions perform formatted substitution of the matched * character sequences into their target. The format specifiers and @@ -1898,7 +1907,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 //@} /** - * @name 10.5 Allocator + * @name 28.10.6 Allocator */ //@{ @@ -1912,7 +1921,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 //@} /** - * @name 10.6 Swap + * @name 28.10.7 Swap */ //@{ @@ -1929,12 +1938,14 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 //@} private: - template - friend class __detail::_Executor; - template friend class regex_iterator; + /// @cond undocumented + + template + friend class __detail::_Executor; + template friend bool @@ -1971,6 +1982,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 { return _Base_type::operator[](_Base_type::size() - 1); } _Bi_iter _M_begin; + /// @endcond }; typedef match_results cmatch; @@ -1981,10 +1993,11 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 #endif // match_results comparisons + /** * @brief Compares two match_results for equality. * @returns true if the two objects refer to the same match, - * false otherwise. + * false otherwise. */ template inline bool @@ -2008,7 +2021,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 /** * @brief Compares two match_results for inequality. * @returns true if the two objects do not refer to the same match, - * false otherwise. + * false otherwise. */ template inline bool @@ -2030,9 +2043,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 match_results<_Bi_iter, _Alloc>& __rhs) noexcept { __lhs.swap(__rhs); } + _GLIBCXX_END_NAMESPACE_CXX11 - // [7.11.2] Function template regex_match + // [28.11.2] Function template regex_match /** * @name Matching, Searching, and Replacing */ diff --git a/libstdc++-v3/include/bits/regex.tcc b/libstdc++-v3/include/bits/regex.tcc index 1c8625dc8e8..dbe348dbfe8 100644 --- a/libstdc++-v3/include/bits/regex.tcc +++ b/libstdc++-v3/include/bits/regex.tcc @@ -34,6 +34,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION namespace __detail { + /// @cond undocumented + // Result of merging regex_match and regex_search. // // __policy now can be _S_auto (auto dispatch) and _S_alternate (use @@ -118,7 +120,10 @@ namespace __detail } return __ret; } -} + /// @endcond +} // namespace __detail + + /// @cond template template @@ -352,7 +357,8 @@ namespace __detail template template - _Out_iter match_results<_Bi_iter, _Alloc>:: + _Out_iter + match_results<_Bi_iter, _Alloc>:: format(_Out_iter __out, const match_results<_Bi_iter, _Alloc>::char_type* __fmt_first, const match_results<_Bi_iter, _Alloc>::char_type* __fmt_last, @@ -667,5 +673,7 @@ namespace __detail _M_result = nullptr; } + /// @endcond + _GLIBCXX_END_NAMESPACE_VERSION } // namespace -- 2.30.2