Message ID | 20230223173741.532305-1-jwakely@redhat.com |
---|---|
State | New |
Headers | show |
Series | libstdc++: Add Doxygen comment for string::resize_and_overwite | expand |
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.
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);