From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id E482C3858D39; Mon, 27 Feb 2023 14:46:59 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E482C3858D39 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1677509219; bh=+9eAgE9JKmIYQNTRofb0W1axFyOuQAET2E4CF9iO+EE=; h=From:To:Subject:Date:From; b=hd7zBRbkHEwaSW3V5k+ICPDBKhTs1ph+OK+CkBKtNhz8tYG1ZzVt7plfq8Q/solYE YMBlZHxki2sGZCnq2gLKjW4wVW0QId5pwqDkiLzRX+28dfbSVLLeOB4xCmy579Mj/R H2B1QbPE6BJh+WVhIej2drFj3eRZPOOsvotGguO8= MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r13-6357] libstdc++: Add Doxygen comment for string::resize_and_overwite X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/master X-Git-Oldrev: ce83c3e492c2fa5a08c15b5f4619d58f42a5dcd0 X-Git-Newrev: dfa85beebfbc2f879d30d3918f634feabc851782 Message-Id: <20230227144659.E482C3858D39@sourceware.org> Date: Mon, 27 Feb 2023 14:46:59 +0000 (GMT) List-Id: https://gcc.gnu.org/g:dfa85beebfbc2f879d30d3918f634feabc851782 commit r13-6357-gdfa85beebfbc2f879d30d3918f634feabc851782 Author: Jonathan Wakely 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 constexpr void resize_and_overwrite(size_type __n, _Operation __op);