Re: [PATCH] Revamp documentation for _Complex types extension
On Mon, Jan 3, 2022 at 2:51 AM apinski--- via Gcc-patches
wrote:
>
> From: Andrew Pinski
>
> While cleaning up the bug database, I noticed there was a request
> to improve the documentation of the _Complex type extensions.
> So I rewrote part of the documentation to make things clearer on
> __real/__imag and even added documentation about casts between
> the scalar and the complex type.
> I moved the documentation of __builtin_complex under this section
> too because it makes more sense than having it in the other
> built-in section and reference it.
>
> OK? Built make info and make html and checked out the results to
> make sure the tables look decent.
OK.
> gcc/ChangeLog:
>
> PR c/33193
> * doc/extend.texi: Extend the documentation about Complex
> types for casting and also rewrite the __real__/__imag__
> expression portion to use tables.
> Move __builtin_complex to the Complex type section.
> ---
> gcc/doc/extend.texi | 73 +
> 1 file changed, 54 insertions(+), 19 deletions(-)
>
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index 9676a17406e..c7a43a79e16 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -986,22 +986,57 @@ The ISO C++14 library also defines the @samp{i} suffix,
> so C++14 code
> that includes the @samp{} header cannot use @samp{i} for the
> GNU extension. The @samp{j} suffix still has the GNU meaning.
>
> +GCC can handle both implicit and explicit casts between the @code{_Complex}
> +types and other @code{_Complex} types as casting both the real and imaginary
> +parts to the scalar type.
> +GCC can handle implicit and explicit casts from a scalar type to a
> @code{_Complex}
> +type and where the imaginary part will be considered zero.
> +The C front-end can handle implicit and explicit casts from a
> @code{_Complex} type
> +to a scalar type where the imaginary part will be ignored. In C++ code, this
> cast
> +is considered illformed and G++ will error out.
> +
> +GCC provides a built-in function @code{__builtin_complex} will can be used to
> +construct a complex value.
> +
> @cindex @code{__real__} keyword
> @cindex @code{__imag__} keyword
> -To extract the real part of a complex-valued expression @var{exp}, write
> -@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
> -extract the imaginary part. This is a GNU extension; for values of
> -floating type, you should use the ISO C99 functions @code{crealf},
> -@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
> -@code{cimagl}, declared in @code{} and also provided as
> +
> +GCC has a few extensions which can be used to extract the real
> +and the imaginary part of the complex-valued expression. Note
> +these expressions are lvalues if the @var{exp} is an lvalue.
> +These expressions operands have the type of a complex type
> +which might get prompoted to a complex type from a scalar type.
> +E.g. @code{__real__ (int)@var{x}} is the same as casting to
> +@code{_Complex int} before @code{__real__} is done.
> +
> +@multitable @columnfractions .4 .6
> +@headitem Expression @tab Description
> +@item @code{__real__ @var{exp}}
> +@tab Extract the real part of @var{exp}.
> +@item @code{__imag__ @var{exp}}
> +@tab Extract the imaginary part of @var{exp}.
> +@end multitable
> +
> +For values of floating point, you should use the ISO C99
> +functions, declared in @code{} and also provided as
> built-in functions by GCC@.
>
> +@multitable @columnfractions .4 .2 .2 .2
> +@headitem Expression @tab float @tab double @tab long double
> +@item @code{__real__ @var{exp}}
> +@tab @code{crealf} @tab @code{creal} @tab @code{creall}
> +@item @code{__imag__ @var{exp}}
> +@tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl}
> +@end multitable
> +
> @cindex complex conjugation
> The operator @samp{~} performs complex conjugation when used on a value
> with a complex type. This is a GNU extension; for values of
> floating type, you should use the ISO C99 functions @code{conjf},
> @code{conj} and @code{conjl}, declared in @code{} and also
> -provided as built-in functions by GCC@.
> +provided as built-in functions by GCC@. Note unlike the @code{__real__}
> +and @code{__imag__} operators, this operator will not do an implicit cast
> +to the complex type because the @samp{~} is already a normal operator.
>
> GCC can allocate complex automatic variables in a noncontiguous
> fashion; it's even possible for the real part to be in a register while
> @@ -1013,6 +1048,18 @@ If the variable's actual name is @code{foo}, the two
> fictitious
> variables are named @code{foo$real} and @code{foo$imag}. You can
> examine and set these two fictitious variables with your debugger.
>
> +@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real},
> @var{imag})
> +
> +The built-in function @code{__builtin_complex} is provided for use in
> +implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
> +@cod
[PATCH] Revamp documentation for _Complex types extension
From: Andrew Pinski
While cleaning up the bug database, I noticed there was a request
to improve the documentation of the _Complex type extensions.
So I rewrote part of the documentation to make things clearer on
__real/__imag and even added documentation about casts between
the scalar and the complex type.
I moved the documentation of __builtin_complex under this section
too because it makes more sense than having it in the other
built-in section and reference it.
OK? Built make info and make html and checked out the results to
make sure the tables look decent.
gcc/ChangeLog:
PR c/33193
* doc/extend.texi: Extend the documentation about Complex
types for casting and also rewrite the __real__/__imag__
expression portion to use tables.
Move __builtin_complex to the Complex type section.
---
gcc/doc/extend.texi | 73 +
1 file changed, 54 insertions(+), 19 deletions(-)
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 9676a17406e..c7a43a79e16 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -986,22 +986,57 @@ The ISO C++14 library also defines the @samp{i} suffix,
so C++14 code
that includes the @samp{} header cannot use @samp{i} for the
GNU extension. The @samp{j} suffix still has the GNU meaning.
+GCC can handle both implicit and explicit casts between the @code{_Complex}
+types and other @code{_Complex} types as casting both the real and imaginary
+parts to the scalar type.
+GCC can handle implicit and explicit casts from a scalar type to a
@code{_Complex}
+type and where the imaginary part will be considered zero.
+The C front-end can handle implicit and explicit casts from a @code{_Complex}
type
+to a scalar type where the imaginary part will be ignored. In C++ code, this
cast
+is considered illformed and G++ will error out.
+
+GCC provides a built-in function @code{__builtin_complex} will can be used to
+construct a complex value.
+
@cindex @code{__real__} keyword
@cindex @code{__imag__} keyword
-To extract the real part of a complex-valued expression @var{exp}, write
-@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
-extract the imaginary part. This is a GNU extension; for values of
-floating type, you should use the ISO C99 functions @code{crealf},
-@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
-@code{cimagl}, declared in @code{} and also provided as
+
+GCC has a few extensions which can be used to extract the real
+and the imaginary part of the complex-valued expression. Note
+these expressions are lvalues if the @var{exp} is an lvalue.
+These expressions operands have the type of a complex type
+which might get prompoted to a complex type from a scalar type.
+E.g. @code{__real__ (int)@var{x}} is the same as casting to
+@code{_Complex int} before @code{__real__} is done.
+
+@multitable @columnfractions .4 .6
+@headitem Expression @tab Description
+@item @code{__real__ @var{exp}}
+@tab Extract the real part of @var{exp}.
+@item @code{__imag__ @var{exp}}
+@tab Extract the imaginary part of @var{exp}.
+@end multitable
+
+For values of floating point, you should use the ISO C99
+functions, declared in @code{} and also provided as
built-in functions by GCC@.
+@multitable @columnfractions .4 .2 .2 .2
+@headitem Expression @tab float @tab double @tab long double
+@item @code{__real__ @var{exp}}
+@tab @code{crealf} @tab @code{creal} @tab @code{creall}
+@item @code{__imag__ @var{exp}}
+@tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl}
+@end multitable
+
@cindex complex conjugation
The operator @samp{~} performs complex conjugation when used on a value
with a complex type. This is a GNU extension; for values of
floating type, you should use the ISO C99 functions @code{conjf},
@code{conj} and @code{conjl}, declared in @code{} and also
-provided as built-in functions by GCC@.
+provided as built-in functions by GCC@. Note unlike the @code{__real__}
+and @code{__imag__} operators, this operator will not do an implicit cast
+to the complex type because the @samp{~} is already a normal operator.
GCC can allocate complex automatic variables in a noncontiguous
fashion; it's even possible for the real part to be in a register while
@@ -1013,6 +1048,18 @@ If the variable's actual name is @code{foo}, the two
fictitious
variables are named @code{foo$real} and @code{foo$imag}. You can
examine and set these two fictitious variables with your debugger.
+@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real},
@var{imag})
+
+The built-in function @code{__builtin_complex} is provided for use in
+implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
+@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
+real binary floating-point type, and the result has the corresponding
+complex type with real and imaginary parts @var{real} and @var{imag}.
+Unlike @samp{@var{real} + I * @var{imag}}, this works even when
+infi
