Revamp documentation for _Complex types extension

From: Andrew Pinski <apinski@marvell.com>

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(-)

On Mon, Jan 3, 2022 at 2:51 AM apinski--- via Gcc-patches
<gcc-patches@gcc.gnu.org> wrote:
>
> From: Andrew Pinski <apinski@marvell.com>
>
> 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{<complex>} 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{<complex.h>} 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{<complex.h>} 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{<complex.h>} 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
> +infinities, NaNs and negative zeros are involved.
> +
> +@end deftypefn
> +
>  @node Floating Types
>  @section Additional Floating Types
>  @cindex additional floating types
> @@ -13834,18 +13881,6 @@ an error if there is no such function.
>
>  @end deftypefn
>
> -@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
> -infinities, NaNs and negative zeros are involved.
> -
> -@end deftypefn
> -
>  @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
>  You can use the built-in function @code{__builtin_constant_p} to
>  determine if a value is known to be constant at compile time and hence
> --
> 2.17.1
>