A stackoverflow poster was confused by the comments on basic_string::length() which talk about null-temrination, as it isn't obvious that embedded nulls are not terminators.
I think this makes it clearer, but would appreciate other opinions. (The @{ and @} commands tell doxygen to use the same comment for both functions, to avoid duplicating the text more than already necessary for the two string implementations.)
commit e028b1ff506e21567bb315715d4e694c36d1d006 Author: Jonathan Wakely <jwak...@redhat.com> Date: Fri Apr 1 11:48:26 2016 +0100 Clarify doxygen comments w.r.t nulls in std::string * include/bits/basic_string.h (basic_string::size, basic_string::length): Clarify handling of embedded null characters. diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h index 374c985..f79b531 100644 --- a/libstdc++-v3/include/bits/basic_string.h +++ b/libstdc++-v3/include/bits/basic_string.h @@ -783,18 +783,29 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 public: // Capacity: - /// Returns the number of characters in the string, not including any - /// null-termination. + + /** + * @{ + * + * @brief Returns the number of characters in the string. + * + * The return value does not include the null character that follows + * the string contents, e.g. in the pointer returned by c_str(), + * but embedded null characters inside the string are part of the + * string contents and so they (and characters following them) are + * counted. + */ + size_type size() const _GLIBCXX_NOEXCEPT { return _M_string_length; } - /// Returns the number of characters in the string, not including any - /// null-termination. size_type length() const _GLIBCXX_NOEXCEPT { return _M_string_length; } + // @} + /// Returns the size() of the largest possible %string. size_type max_size() const _GLIBCXX_NOEXCEPT @@ -1967,6 +1978,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 swap(basic_string& __s) _GLIBCXX_NOEXCEPT; // String operations: + /** * @brief Return const pointer to null-terminated contents. * @@ -3233,18 +3245,29 @@ _GLIBCXX_END_NAMESPACE_CXX11 public: // Capacity: - /// Returns the number of characters in the string, not including any - /// null-termination. + + /** + * @{ + * + * @brief Returns the number of characters in the string. + * + * The return value does not include the null character that follows + * the string contents, e.g. in the pointer returned by c_str(), + * but embedded null characters inside the string are part of the + * string contents and so they (and characters following them) are + * counted. + */ + size_type size() const _GLIBCXX_NOEXCEPT { return _M_rep()->_M_length; } - /// Returns the number of characters in the string, not including any - /// null-termination. size_type length() const _GLIBCXX_NOEXCEPT { return _M_rep()->_M_length; } + // @} + /// Returns the size() of the largest possible %string. size_type max_size() const _GLIBCXX_NOEXCEPT