# std::aligned_union

> C++ Atlas: `cppatlas.com/w/cpp/types/aligned_union` | Source: https://en.cppreference.com/w/cpp/types/aligned_union | Domain: Type support | Standards: C++11, C++14, C++23

Provides the nested type type, which is a trivial standard-layout type of a size and alignment suitable for use as uninitialized storage for an object of any of the types listed in Types.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <type_traits>

template< std::size_t Len, class... Types >
struct aligned_union; // (since C++11) (deprecated in C++23)
```

Provides the nested type `type`, which is a trivial standard-layout type of a size and alignment suitable for use as uninitialized storage for an object of any of the types listed in `Types`. The size of the storage is at least `Len`. `std::aligned_union` also determines the strictest (largest) alignment requirement among all `Types` and makes it available as the constant `alignment_value`.

If `sizeof...(Types) == 0` or if any of the types in `Types` is not a complete object type, the behavior is undefined.

It is implementation-defined whether any extended alignment is supported.

If the program adds specializations for `std::aligned_union`, the behavior is undefined.

### Member types

**Name — Definition**

- `type`: a trivial and standard-layout type suitable for storage of any type from `Types`

### Helper types

```cpp
template< std::size_t Len, class... Types >
using aligned_union_t = typename aligned_union<Len,Types...>::type; // (since C++14) (deprecated in C++23)
```

### Member constants

- `alignment_value` [static]: the strictest alignment requirement of all `Types` (public static member constant)

### Possible implementation

```cpp
#include <algorithm>

template<std::size_t Len, class... Types>
struct aligned_union
{
    static constexpr std::size_t alignment_value = std::max({alignof(Types)...});

    struct type
    {
        alignas(alignment_value) char _s[std::max({Len, sizeof(Types)...})];
    };
};
```

### Example

```cpp
#include <iostream>
#include <string>
#include <type_traits>

int main()
{
    std::cout << sizeof(std::aligned_union_t<0, char>) << ' ' // 1
              << sizeof(std::aligned_union_t<2, char>) << ' ' // 2
              << sizeof(std::aligned_union_t<2, char[3]>) << ' ' // 3 (!)
              << sizeof(std::aligned_union_t<3, char[4]>) << ' ' // 4
              << sizeof(std::aligned_union_t<1, char, int, double>) << ' '    // 8
              << sizeof(std::aligned_union_t<12, char, int, double>) << '\n'; // 16 (!)

    using var_t = std::aligned_union<16, int, std::string>;

    std::cout << "var_t::alignment_value = " << var_t::alignment_value << '\n'
              << "sizeof(var_t::type) = " << sizeof(var_t::type) << '\n';

    var_t::type aligned_storage;
    int* int_ptr = new(&aligned_storage) int(42); // placement new
    std::cout << "*int_ptr = " << *int_ptr << '\n';

    std::string* string_ptr = new(&aligned_storage) std::string("bar");
    std::cout << "*string_ptr = " << *string_ptr << '\n';
    *string_ptr = "baz";
    std::cout << "*string_ptr = " << *string_ptr << '\n';
    string_ptr->~basic_string();
}
```

Possible output:

```text
1 2 3 4 8 16
var_t::alignment_value = 8
sizeof(var_t::type) = 32
*int_ptr = 42
*string_ptr = bar
*string_ptr = baz
```

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 2979 | C++11 | complete type was not required | requires complete types |

### See also

- [`alignment_of`](https://en.cppreference.com/w/cpp/types/alignment_of) (C++11): obtains the type's alignment requirements (class template)
- [`aligned_storage`](https://en.cppreference.com/w/cpp/types/aligned_storage) (since C++11): defines the type suitable for use as uninitialized storage for types of given size (class template)

---
Attribution: content from https://en.cppreference.com/w/cpp/types/aligned_union (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.