Commit 2313938e by Jonathan Wakely Committed by Jonathan Wakely

Improve API docs for std::regex

	* include/bits/regex.h: Improve docs.
	* include/bits/regex.tcc: Do not document implementation details.

From-SVN: r270952
parent 99f12959
2019-05-07 Jonathan Wakely <jwakely@redhat.com> 2019-05-07 Jonathan Wakely <jwakely@redhat.com>
* include/bits/regex.h: Improve docs.
* include/bits/regex.tcc: Do not document implementation details.
* testsuite/19_diagnostics/error_code/hash.cc: New test. * testsuite/19_diagnostics/error_code/hash.cc: New test.
2019-05-06 François Dumont <fdumont@gcc.gnu.org> 2019-05-06 François Dumont <fdumont@gcc.gnu.org>
......
...@@ -838,6 +838,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -838,6 +838,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* @brief Swaps the contents of two regular expression objects. * @brief Swaps the contents of two regular expression objects.
* @param __lhs First regular expression. * @param __lhs First regular expression.
* @param __rhs Second regular expression. * @param __rhs Second regular expression.
* @relates basic_regex
*/ */
template<typename _Ch_type, typename _Rx_traits> template<typename _Ch_type, typename _Rx_traits>
inline void inline void
...@@ -937,10 +938,12 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -937,10 +938,12 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
{ return this->_M_str().compare(__s); } { return this->_M_str().compare(__s); }
// @} // @}
/// @cond undocumented
// Non-standard, used by comparison operators // Non-standard, used by comparison operators
int int
_M_compare(const value_type* __s, size_t __n) const _M_compare(const value_type* __s, size_t __n) const
{ return this->_M_str().compare({__s, __n}); } { return this->_M_str().compare({__s, __n}); }
/// @endcond
private: private:
// Simplified basic_string_view for C++11 // Simplified basic_string_view for C++11
...@@ -1015,6 +1018,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -1015,6 +1018,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
// [7.9.2] sub_match non-member operators // [7.9.2] sub_match non-member operators
/// @relates sub_match @{
/** /**
* @brief Tests the equivalence of two regular expression submatches. * @brief Tests the equivalence of two regular expression submatches.
* @param __lhs First regular expression submatch. * @param __lhs First regular expression submatch.
...@@ -1081,11 +1086,14 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -1081,11 +1086,14 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
operator>(const sub_match<_BiIter>& __lhs, const sub_match<_BiIter>& __rhs) operator>(const sub_match<_BiIter>& __lhs, const sub_match<_BiIter>& __rhs)
{ return __lhs.compare(__rhs) > 0; } { return __lhs.compare(__rhs) > 0; }
/// @cond undocumented
// Alias for a basic_string that can be compared to a sub_match. // Alias for a basic_string that can be compared to a sub_match.
template<typename _Bi_iter, typename _Ch_traits, typename _Ch_alloc> template<typename _Bi_iter, typename _Ch_traits, typename _Ch_alloc>
using __sub_match_string = basic_string< using __sub_match_string = basic_string<
typename iterator_traits<_Bi_iter>::value_type, typename iterator_traits<_Bi_iter>::value_type,
_Ch_traits, _Ch_alloc>; _Ch_traits, _Ch_alloc>;
/// @endcond
/** /**
* @brief Tests the equivalence of a string and a regular expression * @brief Tests the equivalence of a string and a regular expression
...@@ -1554,6 +1562,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -1554,6 +1562,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
const sub_match<_Bi_iter>& __m) const sub_match<_Bi_iter>& __m)
{ return __os << __m.str(); } { return __os << __m.str(); }
// @} relates sub_match
// [7.10] Class template match_results // [7.10] Class template match_results
/** /**
...@@ -1575,8 +1585,6 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -1575,8 +1585,6 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* of characters [first, second) which formed that match. Otherwise matched * of characters [first, second) which formed that match. Otherwise matched
* is false, and members first and second point to the end of the sequence * is false, and members first and second point to the end of the sequence
* that was searched. * that was searched.
*
* @nosubgrouping
*/ */
template<typename _Bi_iter, template<typename _Bi_iter,
typename _Alloc = allocator<sub_match<_Bi_iter> > > typename _Alloc = allocator<sub_match<_Bi_iter> > >
...@@ -1606,7 +1614,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -1606,7 +1614,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
public: public:
/** /**
* @name 10.? Public Types * @name 28.10 Public Types
*/ */
//@{ //@{
typedef sub_match<_Bi_iter> value_type; typedef sub_match<_Bi_iter> value_type;
...@@ -1630,17 +1638,18 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -1630,17 +1638,18 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
/** /**
* @brief Constructs a default %match_results container. * @brief Constructs a default %match_results container.
* @post size() returns 0 and str() returns an empty string. * @post size() returns 0 and str() returns an empty string.
* @{
*/ */
match_results() : match_results(_Alloc()) { } match_results() : match_results(_Alloc()) { }
/**
* @brief Constructs a default %match_results container.
* @post size() returns 0 and str() returns an empty string.
*/
explicit explicit
match_results(const _Alloc& __a) noexcept match_results(const _Alloc& __a) noexcept
: _Base_type(__a) : _Base_type(__a)
{ } { }
// @}
/** /**
* @brief Copy constructs a %match_results. * @brief Copy constructs a %match_results.
*/ */
...@@ -1712,7 +1721,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -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 ...@@ -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 * These functions perform formatted substitution of the matched
* character sequences into their target. The format specifiers and * character sequences into their target. The format specifiers and
...@@ -1898,7 +1907,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -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 ...@@ -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 ...@@ -1929,12 +1938,14 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
//@} //@}
private: private:
template<typename, typename, typename, bool>
friend class __detail::_Executor;
template<typename, typename, typename> template<typename, typename, typename>
friend class regex_iterator; friend class regex_iterator;
/// @cond undocumented
template<typename, typename, typename, bool>
friend class __detail::_Executor;
template<typename _Bp, typename _Ap, typename _Cp, typename _Rp, template<typename _Bp, typename _Ap, typename _Cp, typename _Rp,
__detail::_RegexExecutorPolicy, bool> __detail::_RegexExecutorPolicy, bool>
friend bool friend bool
...@@ -1971,6 +1982,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -1971,6 +1982,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
{ return _Base_type::operator[](_Base_type::size() - 1); } { return _Base_type::operator[](_Base_type::size() - 1); }
_Bi_iter _M_begin; _Bi_iter _M_begin;
/// @endcond
}; };
typedef match_results<const char*> cmatch; typedef match_results<const char*> cmatch;
...@@ -1981,10 +1993,11 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -1981,10 +1993,11 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
#endif #endif
// match_results comparisons // match_results comparisons
/** /**
* @brief Compares two match_results for equality. * @brief Compares two match_results for equality.
* @returns true if the two objects refer to the same match, * @returns true if the two objects refer to the same match,
* false otherwise. * false otherwise.
*/ */
template<typename _Bi_iter, typename _Alloc> template<typename _Bi_iter, typename _Alloc>
inline bool inline bool
...@@ -2008,7 +2021,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -2008,7 +2021,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
/** /**
* @brief Compares two match_results for inequality. * @brief Compares two match_results for inequality.
* @returns true if the two objects do not refer to the same match, * @returns true if the two objects do not refer to the same match,
* false otherwise. * false otherwise.
*/ */
template<typename _Bi_iter, class _Alloc> template<typename _Bi_iter, class _Alloc>
inline bool inline bool
...@@ -2030,9 +2043,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 ...@@ -2030,9 +2043,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
match_results<_Bi_iter, _Alloc>& __rhs) noexcept match_results<_Bi_iter, _Alloc>& __rhs) noexcept
{ __lhs.swap(__rhs); } { __lhs.swap(__rhs); }
_GLIBCXX_END_NAMESPACE_CXX11 _GLIBCXX_END_NAMESPACE_CXX11
// [7.11.2] Function template regex_match // [28.11.2] Function template regex_match
/** /**
* @name Matching, Searching, and Replacing * @name Matching, Searching, and Replacing
*/ */
......
...@@ -34,6 +34,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -34,6 +34,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
namespace __detail namespace __detail
{ {
/// @cond undocumented
// Result of merging regex_match and regex_search. // Result of merging regex_match and regex_search.
// //
// __policy now can be _S_auto (auto dispatch) and _S_alternate (use // __policy now can be _S_auto (auto dispatch) and _S_alternate (use
...@@ -118,7 +120,10 @@ namespace __detail ...@@ -118,7 +120,10 @@ namespace __detail
} }
return __ret; return __ret;
} }
} /// @endcond
} // namespace __detail
/// @cond
template<typename _Ch_type> template<typename _Ch_type>
template<typename _Fwd_iter> template<typename _Fwd_iter>
...@@ -352,7 +357,8 @@ namespace __detail ...@@ -352,7 +357,8 @@ namespace __detail
template<typename _Bi_iter, typename _Alloc> template<typename _Bi_iter, typename _Alloc>
template<typename _Out_iter> template<typename _Out_iter>
_Out_iter match_results<_Bi_iter, _Alloc>:: _Out_iter
match_results<_Bi_iter, _Alloc>::
format(_Out_iter __out, format(_Out_iter __out,
const match_results<_Bi_iter, _Alloc>::char_type* __fmt_first, const match_results<_Bi_iter, _Alloc>::char_type* __fmt_first,
const match_results<_Bi_iter, _Alloc>::char_type* __fmt_last, const match_results<_Bi_iter, _Alloc>::char_type* __fmt_last,
...@@ -667,5 +673,7 @@ namespace __detail ...@@ -667,5 +673,7 @@ namespace __detail
_M_result = nullptr; _M_result = nullptr;
} }
/// @endcond
_GLIBCXX_END_NAMESPACE_VERSION _GLIBCXX_END_NAMESPACE_VERSION
} // namespace } // namespace
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment