[PATCH] libstdc++: Add Doxygen comment for string::resize_and_overwite

[PATCH] libstdc++: Add Doxygen comment for string::resize_and_overwite

[Jonathan Wakely]

Reviews of the resize_and_overwite description welcome. I've tried to
strike a balance between pedantic precision and user-friendliness.

-- >8 --

This is a complicated API that should be clearly documented.

Also improve the comment on basic_ios::_M_setstate.

libstdc++-v3/ChangeLog:

	* include/bits/basic_ios.h (basic_ios::_M_setstate): Add
	caveat to comment.
	* include/bits/basic_string.h (resize_and_overwrite): Add
	doxygen comment.
---
 libstdc++-v3/include/bits/basic_ios.h    |  2 +-
 libstdc++-v3/include/bits/basic_string.h | 28 ++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/libstdc++-v3/include/bits/basic_ios.h b/libstdc++-v3/include/bits/basic_ios.h
index e0667b7d049..d0a4e7d3dfd 100644
--- a/libstdc++-v3/include/bits/basic_ios.h
+++ b/libstdc++-v3/include/bits/basic_ios.h
@@ -159,7 +159,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
       // Flip the internal state on for the proper state bits, then
       // rethrows the propagated exception if bit also set in
-      // exceptions().
+      // exceptions(). Must only be called within a catch handler.
       void
       _M_setstate(iostate __state)
       {
diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h
index c81dc0d425a..1abac655fd1 100644
--- a/libstdc++-v3/include/bits/basic_string.h
+++ b/libstdc++-v3/include/bits/basic_string.h
@@ -1117,6 +1117,34 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
 #if __cplusplus > 202002L
 #define __cpp_lib_string_resize_and_overwrite 202110L
+      /** Resize the string and call a function to fill it.
+       *
+       * @param __n   The maximum size requested.
+       * @param __op  A callable object that writes characters to the string.
+       *
+       * This is a low-level function that is easy to misuse, be careful.
+       *
+       * Calling `str.resize_and_overwrite(n, op)` will reserve at least `n`
+       * characters in `str`, evaluate `n2 = std::move(op)(str.data(), n)`,
+       * and finally set the string length to `n2` (adding a null terminator
+       * at the end). The function object `op` is allowed to write to the
+       * extra capacity added by the initial reserve operation, which is not
+       * allowed if you just call `str.reserve(n)` yourself.
+       *
+       * This can be used to efficiently fill a `string` buffer without the
+       * overhead of zero-initializing characters that will be overwritten
+       * anyway.
+       *
+       * The callable `op` not access the string directly (only through the
+       * pointer passed as its first argument), must not write more than `n`
+       * characters to the string; must return a value no greater than `n`;
+       * and must ensure that all characters up to the returned length are
+       * valid after it returns (i.e. there must be no uninitialized values
+       * left in the string after the call, because accessing them would
+       * have undefined behaviour).
+       *
+       * @since C++23
+       */
       template<typename _Operation>
 	constexpr void
 	resize_and_overwrite(size_type __n, _Operation __op);
-- 
2.39.2

Re: [PATCH] libstdc++: Add Doxygen comment for string::resize_and_overwite

[Daniel Krügler]

Am Do., 23. Feb. 2023 um 18:38 Uhr schrieb Jonathan Wakely via
Libstdc++ <libstdc++@gcc.gnu.org>:
>
> Reviews of the resize_and_overwite description welcome. I've tried to
> strike a balance between pedantic precision and user-friendliness.
>
> -- >8 --
>
> This is a complicated API that should be clearly documented.
>
> Also improve the comment on basic_ios::_M_setstate.
>
> libstdc++-v3/ChangeLog:
>
>         * include/bits/basic_ios.h (basic_ios::_M_setstate): Add
>         caveat to comment.
>         * include/bits/basic_string.h (resize_and_overwrite): Add
>         doxygen comment.
> ---
>  libstdc++-v3/include/bits/basic_ios.h    |  2 +-
>  libstdc++-v3/include/bits/basic_string.h | 28 ++++++++++++++++++++++++
>  2 files changed, 29 insertions(+), 1 deletion(-)
>
> diff --git a/libstdc++-v3/include/bits/basic_ios.h b/libstdc++-v3/include/bits/basic_ios.h
> index e0667b7d049..d0a4e7d3dfd 100644
> --- a/libstdc++-v3/include/bits/basic_ios.h
> +++ b/libstdc++-v3/include/bits/basic_ios.h
> @@ -159,7 +159,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>
>        // Flip the internal state on for the proper state bits, then
>        // rethrows the propagated exception if bit also set in
> -      // exceptions().
> +      // exceptions(). Must only be called within a catch handler.
>        void
>        _M_setstate(iostate __state)
>        {
> diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h
> index c81dc0d425a..1abac655fd1 100644
> --- a/libstdc++-v3/include/bits/basic_string.h
> +++ b/libstdc++-v3/include/bits/basic_string.h
> @@ -1117,6 +1117,34 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
>
>  #if __cplusplus > 202002L
>  #define __cpp_lib_string_resize_and_overwrite 202110L
> +      /** Resize the string and call a function to fill it.
> +       *
> +       * @param __n   The maximum size requested.
> +       * @param __op  A callable object that writes characters to the string.
> +       *
> +       * This is a low-level function that is easy to misuse, be careful.
> +       *
> +       * Calling `str.resize_and_overwrite(n, op)` will reserve at least `n`
> +       * characters in `str`, evaluate `n2 = std::move(op)(str.data(), n)`,
> +       * and finally set the string length to `n2` (adding a null terminator
> +       * at the end). The function object `op` is allowed to write to the
> +       * extra capacity added by the initial reserve operation, which is not
> +       * allowed if you just call `str.reserve(n)` yourself.
> +       *
> +       * This can be used to efficiently fill a `string` buffer without the
> +       * overhead of zero-initializing characters that will be overwritten
> +       * anyway.
> +       *
> +       * The callable `op` not access the string directly (only through the

Did you mean "The callable `op` <ins>must</ins> not access the string
directly" instead?

- Daniel

Re: [PATCH] libstdc++: Add Doxygen comment for string::resize_and_overwite

[Jonathan Wakely]

On Thu, 23 Feb 2023 at 17:42, Daniel Krügler <daniel.kruegler@gmail.com> wrote:
>
> Am Do., 23. Feb. 2023 um 18:38 Uhr schrieb Jonathan Wakely via
> Libstdc++ <libstdc++@gcc.gnu.org>:
> >
> > Reviews of the resize_and_overwite description welcome. I've tried to
> > strike a balance between pedantic precision and user-friendliness.
> >
> > -- >8 --
> >
> > This is a complicated API that should be clearly documented.
> >
> > Also improve the comment on basic_ios::_M_setstate.
> >
> > libstdc++-v3/ChangeLog:
> >
> >         * include/bits/basic_ios.h (basic_ios::_M_setstate): Add
> >         caveat to comment.
> >         * include/bits/basic_string.h (resize_and_overwrite): Add
> >         doxygen comment.
> > ---
> >  libstdc++-v3/include/bits/basic_ios.h    |  2 +-
> >  libstdc++-v3/include/bits/basic_string.h | 28 ++++++++++++++++++++++++
> >  2 files changed, 29 insertions(+), 1 deletion(-)
> >
> > diff --git a/libstdc++-v3/include/bits/basic_ios.h b/libstdc++-v3/include/bits/basic_ios.h
> > index e0667b7d049..d0a4e7d3dfd 100644
> > --- a/libstdc++-v3/include/bits/basic_ios.h
> > +++ b/libstdc++-v3/include/bits/basic_ios.h
> > @@ -159,7 +159,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> >
> >        // Flip the internal state on for the proper state bits, then
> >        // rethrows the propagated exception if bit also set in
> > -      // exceptions().
> > +      // exceptions(). Must only be called within a catch handler.
> >        void
> >        _M_setstate(iostate __state)
> >        {
> > diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h
> > index c81dc0d425a..1abac655fd1 100644
> > --- a/libstdc++-v3/include/bits/basic_string.h
> > +++ b/libstdc++-v3/include/bits/basic_string.h
> > @@ -1117,6 +1117,34 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
> >
> >  #if __cplusplus > 202002L
> >  #define __cpp_lib_string_resize_and_overwrite 202110L
> > +      /** Resize the string and call a function to fill it.
> > +       *
> > +       * @param __n   The maximum size requested.
> > +       * @param __op  A callable object that writes characters to the string.
> > +       *
> > +       * This is a low-level function that is easy to misuse, be careful.
> > +       *
> > +       * Calling `str.resize_and_overwrite(n, op)` will reserve at least `n`
> > +       * characters in `str`, evaluate `n2 = std::move(op)(str.data(), n)`,
> > +       * and finally set the string length to `n2` (adding a null terminator
> > +       * at the end). The function object `op` is allowed to write to the
> > +       * extra capacity added by the initial reserve operation, which is not
> > +       * allowed if you just call `str.reserve(n)` yourself.
> > +       *
> > +       * This can be used to efficiently fill a `string` buffer without the
> > +       * overhead of zero-initializing characters that will be overwritten
> > +       * anyway.
> > +       *
> > +       * The callable `op` not access the string directly (only through the
>
> Did you mean "The callable `op` <ins>must</ins> not access the string
> directly" instead?

I did, thanks! Fixed locally.

[committed] libstdc++: Add Doxygen comment for string::resize_and_overwite

[Jonathan Wakely]

Here's what I committed, including the fix for the typo Daniel spotted.

Pushed to trunk.

-- >8 --

This is a complicated API that should be clearly documented.

Also improve the comment on basic_ios::_M_setstate.

libstdc++-v3/ChangeLog:

	* include/bits/basic_ios.h (basic_ios::_M_setstate): Add
	caveat to comment.
	* include/bits/basic_string.h (resize_and_overwrite): Add
	doxygen comment.
---
 libstdc++-v3/include/bits/basic_ios.h    |  4 ++--
 libstdc++-v3/include/bits/basic_string.h | 29 ++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/libstdc++-v3/include/bits/basic_ios.h b/libstdc++-v3/include/bits/basic_ios.h
index e0667b7d049..de5719c1d68 100644
--- a/libstdc++-v3/include/bits/basic_ios.h
+++ b/libstdc++-v3/include/bits/basic_ios.h
@@ -157,9 +157,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       setstate(iostate __state)
       { this->clear(this->rdstate() | __state); }
 
-      // Flip the internal state on for the proper state bits, then
+      // Flips the internal state on for the proper state bits, then
       // rethrows the propagated exception if bit also set in
-      // exceptions().
+      // exceptions(). Must only be called within a catch handler.
       void
       _M_setstate(iostate __state)
       {
diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h
index c81dc0d425a..1b8ebca7dad 100644
--- a/libstdc++-v3/include/bits/basic_string.h
+++ b/libstdc++-v3/include/bits/basic_string.h
@@ -1117,6 +1117,35 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
 #if __cplusplus > 202002L
 #define __cpp_lib_string_resize_and_overwrite 202110L
+      /** Resize the string and call a function to fill it.
+       *
+       * @param __n   The maximum size requested.
+       * @param __op  A callable object that writes characters to the string.
+       *
+       * This is a low-level function that is easy to misuse, be careful.
+       *
+       * Calling `str.resize_and_overwrite(n, op)` will reserve at least `n`
+       * characters in `str`, evaluate `n2 = std::move(op)(str.data(), n)`,
+       * and finally set the string length to `n2` (adding a null terminator
+       * at the end). The function object `op` is allowed to write to the
+       * extra capacity added by the initial reserve operation, which is not
+       * allowed if you just call `str.reserve(n)` yourself.
+       *
+       * This can be used to efficiently fill a `string` buffer without the
+       * overhead of zero-initializing characters that will be overwritten
+       * anyway.
+       *
+       * The callable `op` must not access the string directly (only through
+       * the pointer passed as its first argument), must not write more than
+       * `n` characters to the string, must return a value no greater than `n`,
+       * and must ensure that all characters up to the returned length are
+       * valid after it returns (i.e. there must be no uninitialized values
+       * left in the string after the call, because accessing them would
+       * have undefined behaviour). If `op` exits by throwing an exception
+       * the behaviour is undefined.
+       *
+       * @since C++23
+       */
       template<typename _Operation>
 	constexpr void
 	resize_and_overwrite(size_type __n, _Operation __op);
-- 
2.39.2