Skip to content
Tutorials Center
My learning

Topics

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.

C++
union Number {
    int i;
    float f;
};

Try it

C++ Shared storage and a tagged union

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.

C++ std::variant, the safe alternative

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

C++
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 float and reading its bits as an int is not allowed; use std::bit_cast (C++20) or std::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::variant does.
  • sizeof of a union is the size of its largest member rounded up to the alignment of the strictest member.
  • For raw bytes use std::byte arrays or std::bit_cast, not unions.