From patchwork Mon Feb 27 14:49:57 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 61970 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:5915:0:0:0:0:0 with SMTP id v21csp2460525wrd; Mon, 27 Feb 2023 06:51:08 -0800 (PST) X-Google-Smtp-Source: AK7set94es8hAc20M45hxNEc4CqSNmLRU/DHQA1YtNnyRr28w/bjq10nlOMMiU2Md4mF4GQgzSoU X-Received: by 2002:a05:6402:12d9:b0:4ad:71bd:67c9 with SMTP id k25-20020a05640212d900b004ad71bd67c9mr27223868edx.25.1677509468359; Mon, 27 Feb 2023 06:51:08 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1677509468; cv=none; d=google.com; s=arc-20160816; b=tN56oVZz+8IQVVCp6CHGsxXGnFU56a3XCZXHH4wCTB4azaHbVayYuxMscqtf+7qaBA JOulSnKiKfrf5ZH3PFOPtcpal//G76qyZYSuBNJFkGjOZmrOsDpgl9VMaseV7w0xWvqy UO4KhQm5q0U2gvoAmL1uJaDFLT2i05NYCuEv0eLQnKR3mZyJ+wDYEMruCtaquqw6SxfT OPxY7VEAiwjv+l0+l5fCnwsp7nA6pIWqTPVzI6mj3kjX4qtN0pdUwWuBYTx0zJ1UMqkn XqIQs2a9bATf800OXH93tEjUeCgZjyOIGJybsEC47tHEzP1HRJhDPKyqI4F+Un+A12ts LKXg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:reply-to:from:list-subscribe:list-help:list-post :list-archive:list-unsubscribe:list-id:precedence :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:dmarc-filter:delivered-to :dkim-signature:dkim-filter; bh=TIysYa7JorXRoFJGNKCnLpkrXJFCSuQdr15s3xnggRc=; b=CiAZSHNak7GkJ2S16qcmeqZMzdi7WHVF//QDfNlJMMKVZWqC9BTWZ2lRfHjnxWWhdn T5AnFTWcIzFusxkqAOG6HIfiPKnVeVuk0/8OOgqK4l1FhSBXjCAuP2qjYeCz0qySVNX9 JW/243KoZt0tCOE0E9NJVHjCmu134hvpcYqyy6ng22w0Ft23hlDEc5FyJQ9/d7/6DWIo 2O9v6bguLnmF1Ds9AvKbzZIEJsParQpj7L5DdkSN9lZ38zGh2pAWsugK8WNhI2vGKYUS KHLqbb4N53OZmVSJep8H6P1DCxlj7EMTeISldcHH5cnbEqREvcF70+oNvybOfq7Gjd7m UnLQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=B2OowMOm; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from sourceware.org (server2.sourceware.org. [2620:52:3:1:0:246e:9693:128c]) by mx.google.com with ESMTPS id bf24-20020a0564021a5800b004ace7b75545si194415edb.531.2023.02.27.06.51.08 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 27 Feb 2023 06:51:08 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) client-ip=2620:52:3:1:0:246e:9693:128c; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=B2OowMOm; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id B80563850429 for ; Mon, 27 Feb 2023 14:50:50 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org B80563850429 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1677509450; bh=TIysYa7JorXRoFJGNKCnLpkrXJFCSuQdr15s3xnggRc=; h=To:Cc:Subject:Date:In-Reply-To:References:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From:Reply-To:From; b=B2OowMOmPIv7rkklFOs2GIIWM6VbfBtThhTtbpVAgKE7HUh1GwRkh5kxeU3unCO42 tCHSO2dqIWgfen2c7ilM3iWjrbBBPsPrOe1SZWuI4/6Qft/SEP5v/WFJeXdBu32JtO TENE78HENmsEDC0P0zvT76IuTPdGraT4a9u0UocY= 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 452FD3858D39 for ; Mon, 27 Feb 2023 14:50:06 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 452FD3858D39 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-487-CdmN8nbfOB2dysf5c2TmFg-1; Mon, 27 Feb 2023 09:49:59 -0500 X-MC-Unique: CdmN8nbfOB2dysf5c2TmFg-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 A009E886461; Mon, 27 Feb 2023 14:49:58 +0000 (UTC) Received: from localhost (unknown [10.33.36.228]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6A4854051E4A; Mon, 27 Feb 2023 14:49:58 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Cc: =?utf-8?q?Daniel_Kr=C3=BCgler?= Subject: [committed] libstdc++: Add Doxygen comment for string::resize_and_overwite Date: Mon, 27 Feb 2023 14:49:57 +0000 Message-Id: <20230227144957.1076432-1-jwakely@redhat.com> In-Reply-To: References: 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=-11.8 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=ham 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+ouuuleilei=gmail.com@gcc.gnu.org Sender: "Gcc-patches" X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1758644324814872255?= X-GMAIL-MSGID: =?utf-8?q?1758996168499239409?= Here's what I committed, including the fix for the typo Daniel spotted. Pushed to trunk. -- >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 | 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);