public inbox for libstdc++-cvs@sourceware.org
help / color / mirror / Atom feed
* [gcc r13-6357] libstdc++: Add Doxygen comment for string::resize_and_overwite
@ 2023-02-27 14:46 Jonathan Wakely
0 siblings, 0 replies; only message in thread
From: Jonathan Wakely @ 2023-02-27 14:46 UTC (permalink / raw)
To: gcc-cvs, libstdc++-cvs
https://gcc.gnu.org/g:dfa85beebfbc2f879d30d3918f634feabc851782
commit r13-6357-gdfa85beebfbc2f879d30d3918f634feabc851782
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Thu Feb 23 15:50:28 2023 +0000
libstdc++: Add Doxygen comment for string::resize_and_overwite
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.
Diff:
---
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);
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2023-02-27 14:46 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-02-27 14:46 [gcc r13-6357] libstdc++: Add Doxygen comment for string::resize_and_overwite Jonathan Wakely
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).