#pragma enum

Description

The #pragma enum directive specifies the size of enum variables that follow. The size at the left brace of a declaration is the one that affects that declaration, regardless of whether further enum directives occur within the declaration. This pragma pushes a value on a stack each time it is used, with a reset option available to return to the previously pushed value.

Syntax

Read syntax diagramSkip visual syntax diagram>>-#--pragma--enum--+-(--suboption--)-+------------------------><
                    '-=--suboption----'

where suboption is any of the following:

1 The enumeration type is one byte in length, of type char if the range of enumeration values falls within the limits of signed char, and unsigned char otherwise.
2 The enumeration type is two bytes in length, of type short if the range of enumeration values falls within the limits of signed short, and unsigned short otherwise.
4 The enumeration type is four bytes in length, of type int if the range of enumeration values falls within the limits of signed int, and unsigned int otherwise.
8 The enumeration type is eight bytes in length.
In 32-bit compilation mode, the enumeration is of type long long if the range of enumeration values falls within the limits of signed long long, and unsigned long long otherwise.
In 64-bit compilation mode, the enumeration is of type long if the range of enumeration values falls within the limits of signed long , and unsigned long otherwise.
int Same as #pragma enum=4.
intlong Specifies that enumeration will occupy 8 bytes of storage if the range of values in the enumeration exceeds the limit for int. See the description for #pragma enum.
If the range of values in the enumeration does not exceed the limit for int, the enumeration will occupy 4 bytes of storage and is represented by int.
small The enumeration type is the smallest integral type that can contain all variables.
If an 8-byte enum results, the actual enumeration type used is dependent on compilation mode. See the description for #pragma enum.
pop This suboption resets the enum size setting to its previous #pragma enum setting. If there is no previous setting, the command line setting for -qenum is used.
reset Same as pop. This option is provided for backwards compatibility.

Notes

Popping on an empty stack generates a warning message and the enum value remains unchanged.

The #pragma enum directive overrides the -qenum compiler option.

For each #pragma enum directive that you put in a source file, it is good practice to have a corresponding #pragma enum=reset before the end of that file. This is the only way to prevent one file from potentially changing the enum setting of another file that #includes it.

The #pragma options enum= directive can be used instead of #pragma enum. The two pragmas are interchangeable.

A -qenum=reset option corresponding to the #pragma enum=reset directive does not exist. Attempting to use -qenum=reset generates a warning message and the option is ignored.

Examples

  1. Usage of the pop and reset suboptions are shown in the following code segment.
    #pragma enum(1)
    #pragma enum(2)
    #pragma enum(4)
    #pragma enum(pop)    /* will reset enum size to 2       */
    #pragma enum(reset)  /* will reset enum size to 1       */
    #pragma enum(pop)    /* will reset enum size to the -qenum setting,
                            assuming -qenum was specified on the command 
                            line.  If -qenum was not specified on the 
                            command line, the compiler default is used. */
  2. One typical use for the reset suboption is to reset the enumeration size set at the end of an include file that specifies an enumeration storage different from the default in the main file. For example, the following include file, small_enum.h, declares various minimum-sized enumerations, then resets the specification at the end of the include file to the last value on the option stack:
    #ifndef small_enum_h
    #define small_enum_h 1
    /*
     * File small_enum.h
     * This enum must fit within an unsigned char type
     */
    
    #pragma options enum=small
    enum e_tag {a, b=255};
    enum e_tag u_char_e_var; /* occupies 1 byte of storage */
     
    
    /* Reset the enumeration size to whatever it was before */
    #pragma options enum=reset
    #endif

    The following source file, int_file.c, includes small_enum.h:

    /*
     * File int_file.c
     * Defines 4 byte enums
     */
    #pragma options enum=int
    enum testing {ONE, TWO, THREE};
    enum testing test_enum;
    
    /* various minimum-sized enums are declared */
    #include "small_enum.h"
      
    /* return to int-sized enums. small_enum.h has reset the
     * enum size
     */
    enum sushi {CALIF_ROLL, SALMON_ROLL, TUNA, SQUID, UNI};
    enum sushi first_order = UNI;

    The enumerations test_enum and first_order both occupy 4 bytes of storage and are of type int. The variable u_char_e_var defined in small_enum.h occupies 1 byte of storage and is represented by an unsigned char data type.

  3. If the following C fragment is compiled with the enum=small option:
    enum e_tag {a, b, c} e_var;
    the range of enum constants is 0 through 2. This range falls within all of the ranges described in the table above. Based on priority, the compiler uses predefined type unsigned char.
  4. If the following C code fragment is compiled with the enum=small option:
    enum e_tag {a=-129, b, c} e_var;
    the range of enum constants is -129 through -127. This range only falls within the ranges of short (signed short) and int (signed int). Because short (signed short) is smaller, it will be used to represent the enum.
  5. If you compile a file myprogram.C using the command:
    xlc++ myprogram.C -qenum=small
    assuming file myprogram.C does not contain #pragma options=int statements, all enum variables within your source file will occupy the minimum amount of storage.
  6. If you compile a file yourfile.C that contains the following lines:
    enum testing {ONE, TWO, THREE};
    enum testing test_enum;
      
    #pragma options enum=small
    enum sushi {CALIF_ROLL, SALMON_ROLL, TUNA, SQUID, UNI};
    enum sushi first_order = UNI;
      
    #pragma options enum=int
    enum music {ROCK, JAZZ, NEW_WAVE, CLASSICAL};
    enum music listening_type;
    using the command:
    xlc++ yourfile.C
    only the enum variable first_order will be minimum-sized (that is, enum variable first_order will only occupy 1 byte of storage). The other two enum variables test_enum and listening_type will be of type int and occupy 4 bytes of storage.

The following examples show invalid enumerations or usage of #pragma enum:

Related information