Union declaration
A union is a special class type that can hold only one of its non-static data members at a time.
The class specifier for a union declaration is similar to class or struct declaration:
union attr class-head-name { member-specification }
|
|||||||||
| attr(C++11) | - | optional sequence of any number of attributes |
| class-head-name | - | the name of the union that's being defined. Optionally prepended by nested-name-specifier (sequence of names and scope-resolution operators, ending with scope-resolution operator). The name may be omitted, in which case the union is unnamed |
| member-specification | - | list of access specifiers, member object and member function declarations and definitions. |
A union can have member functions (including constructors and destructors), but not virtual functions.
A union cannot have base classes and cannot be used as a base class.
A union cannot have data members of reference types.
| Unions cannot contain a non-static data member with a non-trivial special member function (copy constructor, copy-assignment operator, or destructor). | (until C++11) |
| If a union contains a non-static data member with a non-trivial special member function (default constructor, copy/move constructor, copy/move assignment, or destructor), that function is deleted by default in the union and needs to be defined explicitly by the programmer.
At most one data member can have a default member initializer. |
(since C++11) |
Just like in struct declaration, the default member access in a union is public.
Contents |
[edit] Explanation
The union is only as big as necessary to hold its largest data member. The other data members are allocated in the same bytes as part of that largest member. The details of that allocation are implementation-defined, and it's undefined behavior to read from the member of the union that wasn't most recently written. Many compilers implement, as a non-standard language extension, the ability to read inactive members of a union.
#include <iostream> union S { std::int32_t n; // occupies 4 bytes std::uint16_t s[2]; // occupies 4 bytes std::uint8_t c; // occupies 1 byte }; // the whole union occupies 4 bytes int main() { S s = {0x12345678}; // initializes the first member, s.n is now the active member // at this point, reading from s.s or s.c is undefined behavior std::cout << std::hex << "s.n = " << s.n << '\n'; s.s[0] = 0x0011; // s.s is now the active member // at this point, reading from n or c is UB but most compilers define it std::cout << "s.c is now " << +s.c << '\n' // 11 or 00, depending on platform << "s.n is now " << s.n << '\n'; // 12340011 or 00115678 }
Each member is allocated as if it is the only member of the class.
|
If members of a union are classes with user-defined constructors and destructors, to switch the active member, explicit destructor and placement new are generally needed: #include <iostream> #include <string> #include <vector> union S { std::string str; std::vector<int> vec; ~S() {} // needs to know which member is active, only possible in union-like class }; // the whole union occupies max(sizeof(string), sizeof(vector<int>)) int main() { S s = {"Hello, world"}; // at this point, reading from s.vec is undefined behavior std::cout << "s.str = " << s.str << '\n'; s.str.~basic_string<char>(); new (&s.vec) std::vector<int>; // now, s.vec is the active member of the union s.vec.push_back(10); std::cout << s.vec.size() << '\n'; s.vec.~vector<int>(); } |
(since C++11) |
If two union members are standard-layout types, it's well-defined to examine their common subsequence on any compiler.
[edit] Anonymous unions
An anonymous union is an unnamed union definition that does not simultaneously define any variables (including objects of the union type, references, or pointers to the union).
union { member-specification } ;
|
|||||||||
Anonymous unions have further restrictions: they cannot have member functions, cannot have static data members, and all their data members must be public. The only declarations allowed are non-static data members and static_assert declarations (since C++14).
Members of an anonymous union are injected in the enclosing scope (and must not conflict with other names declared there).
int main() { union { int a; const char* p; }; a = 1; p = "Jennifer"; }
Namespace-scope anonymous unions must be static.
[edit] Union-like classes
A union-like class is a union or a class that has at least one anonymous union as a member. A union-like class has a set of variant members:
- the non-static data members of its member anonymous unions;
- in addition, if the union-like class is a union, its non-static data members that are not anonymous unions.
Union-like classes can be used to implement tagged unions.
#include <iostream> // S has one non-static data member (tag), three enumerator members (CHAR, INT, DOUBLE), // and three variant members (c, i, d) struct S { enum{CHAR, INT, DOUBLE} tag; union { char c; int i; double d; }; }; void print_s(const S& s) { switch(s.tag) { case S::CHAR: std::cout << s.c << '\n'; break; case S::INT: std::cout << s.i << '\n'; break; case S::DOUBLE: std::cout << s.d << '\n'; break; } } int main() { S s = {S::CHAR, 'a'}; print_s(s); s.tag = S::INT; s.i = 123; print_s(s); }
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| CWG 1940 | c++14 | anonymous unions only allowed non-static data members | static_assert also allowed |
[edit] See also
|
C documentation for Union declaration
|