C++ Reference ยท Keywords and Statements
The union keyword
Reference for C++ union: shared storage, the active member rule, type punning pitfalls, anonymous unions, tagged unions and why std::variant is safer.
A union is a class type whose non-static data members share the same storage. Its size is at least that of its largest member, and only one member is active at a time: the one that was most recently initialized or assigned. Reading a member that is not active is undefined behavior in C++ (unlike C, where reading another member reinterprets the bytes).
Unions save memory when a value can be one of several unrelated types, and they appear in low-level code, wire formats and in the internals of std::variant. In new code prefer std::variant, which remembers which alternative is active and runs constructors and destructors for you.
union Number { int i; float f; };
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
union name { member-declarations }; union { member-declarations }; // anonymous union
| Part | Description |
|---|---|
name |
Optional. A union can have member functions, constructors, a destructor and access specifiers, but no virtual functions and no base classes, and it cannot be a base class. |
| members | Non-static data members of any type except references. Since C++11 members may be non-trivial types such as std::string, but then you must construct and destroy them manually. |
| anonymous union | Declared without a name and without a declarator; its members become members of the enclosing scope. At namespace scope it must be static. |
Usage notes
- Reading an inactive member is undefined behavior. The common shortcut of writing a
floatand reading its bits as anintis not allowed; usestd::bit_cast(C++20) orstd::memcpy. - As a special case, members of standard-layout structs that share a common initial sequence may be inspected through any of them when they are in the same union.
- A union with non-trivial members (a
std::string, say) gets deleted special member functions unless you provide them. Construct with placement new and destroy by calling the destructor yourself. - Only one non-static data member may have a default member initializer.
- Designated initializers (C++20) can pick the member to initialize:
{.d = 1.5}. - Unions are not general-purpose containers. They give no protection against reading the wrong alternative, so they are almost always wrapped in a struct with a tag, which is exactly what
std::variantdoes. sizeofof a union is the size of its largest member rounded up to the alignment of the strictest member.- For raw bytes use
std::bytearrays orstd::bit_cast, not unions.