docs: Attempt to clarify complex literal suffixes [PR112960]

This attempts to clarify Complex literal suffixes in the documentation.

2025-03-07  Jakub Jelinek  <jakub@redhat.com>

	PR c/112960
	PR c/117029
	* doc/extend.texi (Complex): Add I and J suffixes to the list of
	complex suffixes, adjust for all of those being part of ISO C2Y,
	clarify that for -fno-ext-numeric-literals none of those are
	recognized as GNU extensions and for C++14 i is considered UDL
	even for -fext-numeric-literals when <complex> is included.

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 83f6e45170be119aed9378e054c9784235738608..13cbc72ed24cda4f5bfca1f5df5e45b8e8f0f127 100644 (file)
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -990,19 +990,24 @@ have real and imaginary parts of type @code{short int}; this is not
 likely to be useful, but it shows that the set of complex types is
 complete.
 
-To write a constant with a complex data type, use the suffix @samp{i} or
-@samp{j} (either one; they are equivalent).  For example, @code{2.5fi}
-has type @code{_Complex float} and @code{3i} has type
+To write a constant with a complex data type, use the suffix @samp{i},
+@samp{I}, @samp{j} or @samp{J} (any one; they are equivalent).  For
+example, @code{2.5fi} has type @code{_Complex float} and @code{3i} has type
 @code{_Complex int}.  Such a constant always has a pure imaginary
 value, but you can form any complex value you like by adding one to a
-real constant.  This is a GNU extension; if you have an ISO C99
-conforming C library (such as the GNU C Library), and want to construct complex
-constants of floating type, you should include @code{<complex.h>} and
-use the macros @code{I} or @code{_Complex_I} instead.
-
-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.
+real constant.  This is part of ISO C2Y and for older C revisions
+a GNU extension.  If you have an ISO C99 conforming C library
+(such as the GNU C Library), and want to construct complex
+constants of floating type when using standard versions before ISO C2Y,
+you should include @code{<complex.h>} and use the macros @code{I} or
+@code{_Complex_I} instead.
+
+For C++ if @code{-fext-numeric-literals} option is enabled, it is also
+a GNU extension, otherwise it is handled like any other C++ user-defined
+literal.  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{I}, @samp{j} or @samp{J} suffixes still have
+the GNU meaning.
 
 GCC handles both implicit and explicit casts between the
 @code{_Complex} types with different scalar base types by casting both