From: "Daniel Krügler" <daniel.kruegler@gmail.com>
To: Jonathan Wakely <jwakely@redhat.com>
Cc: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org
Subject: Re: [PATCH] libstdc++: Add Doxygen comment for string::resize_and_overwite
Date: Thu, 23 Feb 2023 18:42:10 +0100 [thread overview]
Message-ID: <CAGNvRgCv52u-eUq0fhOsA53i=4QA=n6X2LewgBu66R6KpxN9QA@mail.gmail.com> (raw)
In-Reply-To: <20230223173741.532305-1-jwakely@redhat.com>
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
next prev parent reply other threads:[~2023-02-23 17:42 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-02-23 17:37 Jonathan Wakely
2023-02-23 17:42 ` Daniel Krügler [this message]
2023-02-23 17:53 ` Jonathan Wakely
2023-02-27 14:49 ` [committed] " Jonathan Wakely
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAGNvRgCv52u-eUq0fhOsA53i=4QA=n6X2LewgBu66R6KpxN9QA@mail.gmail.com' \
--to=daniel.kruegler@gmail.com \
--cc=gcc-patches@gcc.gnu.org \
--cc=jwakely@redhat.com \
--cc=libstdc++@gcc.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).