procyberian/gcc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Doc: Document enum with underlying type extension [PR117689]

Browse source 
This is a C23/C++11 feature that is supported as an extension with
earlier -std= options too, but was never previously documented.  It
interacts with the already-documented forward enum definition extension,
so I have merged discussion of the two extensions into the same section.

gcc/ChangeLog
	PR c/117689
	* doc/extend.texi (Incomplete Enums): Rename to....
	(Enum Extensions): This.  Document support for specifying the
	underlying type of an enum as an extension in all earlier C
	and C++ standards.  Document that a forward declaration with
	underlying type is not an incomplete type, and which dialects
	GCC supports that in.
This commit is contained in:
Sandra Loosemore 2025-04-01 19:34:14 +00:00
parent 0210bedf48
commit 42b2fc3fc9
1 changed files with 50 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
gcc/doc/extend.texi
View file

@ -12943,7 +12943,7 @@ C and/or C++ standards, while others remain specific to GNU C.
* Typeof:: @code{typeof}: referring to the type of an expression.
* Offsetof:: Special syntax for @code{offsetof}.
* Alignment:: Determining the alignment of a function, type or variable.
* Incomplete Enums:: @code{enum foo;}, with details to follow.
* Enum Extensions:: Forward declarations and specifying the underlying type.
* Variadic Macros:: Macros with a variable number of arguments.
* Conditionals:: Omitting the middle operand of a @samp{?:} expression.
* Case Ranges:: `case 1 ... 9' and such.
@ -13643,22 +13643,60 @@ If the operand of the @code{__alignof__} expression is a function,
the expression evaluates to the alignment of the function which may
be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
@node Incomplete Enums
@subsection Incomplete @code{enum} Types
@node Enum Extensions
@subsection Extensions to @code{enum} Type Declarations
@anchor{Incomplete Enums}
@cindex @code{enum} extensions
@cindex base type of an @code{enum}
@cindex underlying type of an @code{enum}
@cindex forward declaration of an @code{enum}
@cindex opaque @code{enum} types
@cindex incomplete @code{enum} types
You can define an @code{enum} tag without specifying its possible values.
This results in an incomplete type, much like what you get if you write
@code{struct foo} without describing the elements. A later declaration
that does specify the possible values completes the type.
The C23 and C++11 standards added new syntax to specify the underlying
type of an @code{enum} type. For example,
@smallexample
enum pet : unsigned char @{ CAT, DOG, ROCK @};
@end smallexample
In GCC, this feature is supported as an extension in all older
dialects of C and C++ as well. For C++ dialects before C++11, use
@option{-Wno-c++11-extensions} to silence the associated warnings.
You can also forward-declare an @code{enum} type, without specifying
its possible values. The enumerators are supplied in a later
redeclaration of the type, which must match the underlying type of the
first declaration.
@smallexample
enum pet : unsigned char;
static enum pet my_pet;
...
enum pet : unsigned char @{ CAT, DOG, ROCK @};
@end smallexample
Forward declaration of @code{enum} types with an explicit underlying
type is also a feature of C++11 that is supported as an extension by
GCC for all C dialects. However, it's not available in C++ dialects
prior to C++11.
The C++ standard refers to a forward declaration of an @code{enum}
with an explicit underlying type as an @dfn{opaque type}. It is not
considered an incomplete type, since its size is known. That means
you can declare variables or allocate storage using the type before
the redeclaration, not just use pointers of that type.
GCC has also traditionally supported forward declarations of
@code{enum} types that don't include an explicit underlying type
specification. This results in an incomplete type, much like what you
get if you write @code{struct foo} without describing the elements.
You cannot allocate variables or storage using the type while it is
incomplete. However, you can work with pointers to that type.
This extension may not be very useful, but it makes the handling of
@code{enum} more consistent with the way @code{struct} and @code{union}
are handled.
This extension is not supported by GNU C++.
Forward-declaring an incomplete enum type without an explicit
underlying type is supported as an extension in all GNU C dialects,
but is not supported at all in GNU C++.
@node Variadic Macros
@subsection Macros with a Variable Number of Arguments.