libstdc++: Add Doxygen comment for string::resize_and_overwite
Checks
Commit Message
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(-)
Comments
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
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.
@@ -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)
{
@@ -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);