From patchwork Thu Feb 23 17:37:41 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 1747062 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=8.43.85.97; helo=sourceware.org; envelope-from=gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.a=rsa-sha256 header.s=default header.b=RE+jepX7; dkim-atps=neutral Received: from sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4PN0c21JgXz2462 for ; Fri, 24 Feb 2023 04:38:08 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 2EC37385483E for ; Thu, 23 Feb 2023 17:38:06 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 2EC37385483E DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1677173886; bh=A9vFz1QvEd2+nH1ErXoLcuap9NFu1a9VChOW+/nfCI4=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:From; b=RE+jepX7x9izyl9S73sLMbVlFttq5tIIJZ3rsbYUiIbFQog18feYSuaGCUUGn8naC az5hTNqyq0zUonL8CeW6erK6t403jDohwPZKWmV1rIg33pLJw4Ys5CD+GT4dRxgVSL OVyOfWJYZU9J807Hsp22yuZbpPLfVtVks6r6FoKM= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 7EBD93857803 for ; Thu, 23 Feb 2023 17:37:46 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 7EBD93857803 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-141-jIIZ3EkGM4q-CaGNcAtPRg-1; Thu, 23 Feb 2023 12:37:42 -0500 X-MC-Unique: jIIZ3EkGM4q-CaGNcAtPRg-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 3CC9029AA2E3; Thu, 23 Feb 2023 17:37:42 +0000 (UTC) Received: from localhost (unknown [10.33.36.228]) by smtp.corp.redhat.com (Postfix) with ESMTP id 04D3B404BEC0; Thu, 23 Feb 2023 17:37:41 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [PATCH] libstdc++: Add Doxygen comment for string::resize_and_overwite Date: Thu, 23 Feb 2023 17:37:41 +0000 Message-Id: <20230223173741.532305-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.2 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org Sender: "Gcc-patches" 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 constexpr void resize_and_overwrite(size_type __n, _Operation __op);