On Wed, Nov 25, 2020 at 10:31:28AM +0000, Jonathan Wakely via Gcc-patches wrote:
> On 25/11/20 10:23 +0100, Jakub Jelinek wrote:
> > On Tue, Nov 24, 2020 at 05:31:03PM -0700, Jeff Law wrote:
> > > FIrst, do we need to document the new builtin?ÃÂ
> >
> > I think for builtins that are only meant for libstdc++ as underlying
> > implementation
> > of its documented in the standard APIs we have some cases where we don't
> > document them and other cases where we don't.
>
> And people report bugs when they're not documented. They might want to
> know how the built-in is supposed to behave so they can implement the
> equivalent in other compilers. Documenting the *intended* behaviour
> also makes it clear which behaviours can be relied on, which allows us
> to change the result for edge cases or out-of-contract inputs later.
> If we don't describe the expected behaviour, then we can't really
> blame people for relying on whatever it happens to do today.
>
> I used to think we don't need to bother documenting them, but I've
> been persuaded that it's useful to do it.
Ok, so like this?
2020-11-25 Jakub Jelinek <ja...@redhat.com>
PR libstdc++/93121
* doc/extend.texi (__builtin_bit_cast): Document.
--- gcc/doc/extend.texi.jj 2020-11-23 17:01:51.986013540 +0100
+++ gcc/doc/extend.texi 2020-11-25 17:21:14.696046005 +0100
@@ -13574,6 +13574,21 @@ have intederminate values and the object
bitwise compared to some other object, for example for atomic operations.
@end deftypefn
+@deftypefn {Built-in Function} @var{type} __builtin_bit_cast (@var{type},
@var{arg})
+The @code{__builtin_bit_cast} function is available only
+in C++. The built-in is intended to be used by implementations of
+the @code{std::bit_cast} C++ template function. Programs should make
+use of the latter function rather than invoking the built-in directly.
+
+This built-in function allows reinterpreting the bits of the @var{arg}
+argument as if it had type @var{type}. @var{type} and the type of the
+@var{arg} argument need to be trivially copyable types with the same size.
+When manifestly constant-evaluated, it performs extra diagnostics required
+for @code{std::bit_cast} and returns a constant expression if @var{arg}
+is a constant expression. For more details
+refer to the latest revision of the C++ standard.
+@end deftypefn
+
@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long
@var{c})
@opindex fprofile-arcs
You may use @code{__builtin_expect} to provide the compiler with
Jakub
