Initializes an aggregate from an initializer list. It is a form of list-initialization.(since C++11)

Syntax

Explanation

Aggregate initialization initializes each element of an aggregate with the corresponding initializer in the initializer list, in the element order. An aggregate is either an array or a class that meets certain criteria, see below.

The effects of aggregate initialization are:

• Each initializer clause (that does not have a designator)(since C++20) copy-initializes an aggregate element in order of array subscript/appearance in the class definition.

• If the initializer clause is an expression:

• Implicit conversions are allowed as per copy-initialization, except that narrowing conversions are prohibited(since C++11).
• If an implicit conversion sequence cannot be formed that converts the expression to the type of the corresponding aggregate element e, and e is itself an aggregate with at least one element, brace elision is assumed. In this case, subsequent initializer clauses appertain to the elements of e. See below for details. The aggregate element e is copy-initialized from a brace-enclosed initializer list consisting of the initializer clauses that appertain to its subaggregate elements (or, recursively, to aggregate elements of these elements), in appearance order.

• If the initializer clause is a nested initializer list (not an expression), the corresponding aggregate element is copy-list-initialized from that clause.

struct A
{
    int x;

    struct B
    {
        int i;
        int j;
    } b;
} a = {1, {2, 3}}; // initializes “a.x” with 1, “a.b.i” with 2, “a.b.j” with 3

struct A { int x; int y; int z; };

A a{.y = 2, .x = 1}; // error; designator order does not match declaration order
A b{.x = 1, .z = 2}; // OK, “b.y” initialized to 0

struct C
{
    union
    {
        int a;
        const char* p;
    };
    
    int x;
} c = {.a = 1, .x = 3}; // initializes “c.a” with 1 and “c.x” with 3

// C++29 designated initializers for base class members:
struct A { int a; };
struct B : A { int b; };
struct C : B { int c; };

// the “A” element is initialized from {.a=1}
B x = B{.a=1};
// the “B” element is initialized from {.a=2, .b=3}
// which leads to its “A” element being initialized from {.a=2}
C y = C{.a=2, .b=3, .c=4};

• For a non-union aggregate, each aggregate element that is not explicitly initialized is initialized as follows:

• Otherwise, the element must not be a reference. The element is copy-initialized from an empty initializer list.

• For a union aggregate, if the initializer list is empty:

• Otherwise, the first member of the union (if any) is copy-initialized from an empty initializer list.

In any case, the initializations of the elements of the aggregate are evaluated in the element order. That is, all value computations and side effects associated with a given element are sequenced before those of any element that follows it in order.

struct S { int a; const char* b; int c; int d = b[a]; };
S ss = { 1, "asdf" }; // Initializes “ss.a” with 1
                      // then initializes “ss.b” with "asdf"
                      // then initializes “ss.c” with int{} (that is, 0)
                      // then initializes “ss.d” with ss.b[ss.a] (that is, 's')

If the object is an array of unknown size, the size of the array is the number of explicitly initialized elements (which must not be zero). Note that the object in this case cannot be a non-static data member: a member must have complete type.

int x[] = {1, 3, 5}; // x has 3 elements

struct Y { int i, j, k; };

Y a[] = {1, 2, 3, 4, 5, 6};
X b[2] = {{1, 2, 3}, {4, 5, 6}}; // “a” and “b” have the same type and value

int z[] = {}; // Error: cannot declare an array without any element

struct S { int y[] = {0}; }; // Error: non-static data member of incomplete type

If the object is a union, there must be at most one explicitly initialized element.

union U { int a; const char* b; };

U a = {1};                   // OK: explicitly initializes member “a”
U b = {0, "asdf"};           // Error: explicitly initializes two members
U c = {"asdf"};              // Error: int cannot be initialized by "asdf"

// C++20 designated initializer lists
U d = {.b = "asdf"};         // OK: can explicitly initialize a non-initial member
U e = {.a = 1, .b = "asdf"}; // Error: explicitly initializes two members

Definitions

Aggregate

An aggregate is one of the following types:

• array types
• class types that has

• no private or protected direct non-static data members

• no virtual member functions

Element

The elements of an aggregate are:

• for an array, the array elements in increasing subscript order, or

Appertainment

Each initializer clause in a brace-enclosed initializer list is said to appertain to an element of the aggregate being initialized or to an element of one of its subaggregates.

Considering the sequence of initializer clauses, and the sequence of aggregate elements initially formed as the sequence of elements of the aggregate being initialized and potentially modified as described below:

• For each initializer clause, if any of the following conditions is satisfied, it appertains to the corresponding aggregate element elem:

• elem is not an aggregate.
• The initializer clause begins with {.
• The initializer clause is an expression, and an implicit conversion sequence can be formed that converts the expression to the type of elem.
• elem is an aggregate that itself has no aggregate elements.

• Otherwise, elem is an aggregate and that subaggregate is replaced in the list of aggregate elements by the sequence of its own aggregate elements, and the appertainment analysis resumes with the first such element and the same initializer clause. In other words, these rules apply recursively to the aggregate’s subaggregates.

The analysis is complete when all initializer clauses have been exhausted. If any initializer clause remains that does not appertain to an element of the aggregate or one of its subaggregates, the program is ill-formed.

struct S1 { int a, b; };
struct S2 { S1 s, t; };

// Each subaggregate of “x” is appertained to an initializer clause starting with {
S2 x[2] =
{
    // appertains to “x[0]”
    {
        {1, 2}, // appertains to “x[0].s”
        {3, 4}  // appertains to “x[0].t”
    },
    // appertains to “x[1]”
    {
        {5, 6}, // appertains to “x[1].s”
        {7, 8}  // appertains to “x[1].t”
    }
};

// “x” and “y” have the same value (see below)
S2 y[2] = {1, 2, 3, 4, 5, 6, 7, 8};

// The process of the appertainment analysis of “y”:
// 1. Initializes the aggregate element sequence (x[0], x[1]) and
//    the initializer clause sequence (1, 2, 3, 4, 5, 6, 7, 8).
// 2. Starting from the first elements of each sequence,
//    checks whether 1 appertains to x[0]:
//    · x[0] is an aggregate.
//    · 1 does not begin with {.
//    · 1 is an expression, but it cannot be implicitly converted to S2.
//    · x[0] has aggregate elements.
// 3. 0 cannot appertain to x[0], therefore x[0] is replaced by x[0].s and x[0].t,
//    the aggregate element sequence becomes (x[0].s, x[0].t, x[1]).
// 4. Resumes the appertainment check, but 1 cannot appertain to x[0].s either.
// 5. The aggregate element sequence now becomes (x[0].s.a, x[0].s.b, x[0].t, x[1]).
// 6. Resumes the appertainment check again:
//    1 appertains to x[0].s.a, and 2 appertains to x[0].s.b.
// 7. The rest of the appertainment analysis works similarly.

char cv[4] = {'a', 's', 'd', 'f', 0}; // Error: too many initializer clauses

Character arrays

Arrays of ordinary character types (char, signed char, unsigned char), char8_t(since C++20), char16_t, char32_t(since C++11), or wchar_t can be initialized from ordinary string literals, UTF-8 string literals(since C++20), UTF-16 string literals, UTF-32 string literals(since C++11), or wide string literals, respectively, optionally enclosed in braces. Additionally, an array of char or unsigned char may be initialized by a UTF-8 string literal, optionally enclosed in braces(since C++20). Successive characters of the string literal (which includes the implicit terminating null character) initialize the elements of the array, with an integral conversion if necessary for the source and destination value(since C++20). If the size of the array is specified and it is larger than the number of characters in the string literal, the remaining characters are zero-initialized.

char a[] = "abc";
// equivalent to char a[4] = {'a', 'b', 'c', '\0'};

//  unsigned char b[3] = "abc"; // Error: initializer string too long
unsigned char b[5]{"abc"};
// equivalent to unsigned char b[5] = {'a', 'b', 'c', '\0', '\0'};

wchar_t c[] = {L"кошка"}; // optional braces
// equivalent to wchar_t c[6] = {L'к', L'о', L'ш', L'к', L'а', L'\0'};

Notes

An aggregate class or array may include non-aggregate public bases(since C++17), members, or elements, which are initialized as described above (e.g., copy-initialization from the corresponding initializer clause).

Until C++11, narrowing conversions were permitted in aggregate initialization, but they are no longer allowed.

Until C++11, aggregate initialization could only be used in variable definition, and could not be used in a constructor initializer list, a new-expression, or temporary object creation due to syntax restrictions.

In C, character array of size one less than the size of the string literal may be initialized from a string literal; the resulting array is not null-terminated. This is not allowed in C++.

struct A { int x, y; };
struct B { struct A a; };

struct A a = {.y = 1, .x = 2}; // valid C, invalid C++ (out of order)
int arr[3] = {[1] = 5};        // valid C, invalid C++ (array)
struct B b = {.a.x = 0};       // valid C, invalid C++ (nested)
struct A a = {.x = 1, 2};      // valid C, invalid C++ (mixed)

Example

#include <array>
#include <cstdio>
#include <string>

struct S
{
    int x;
    
    struct Foo
    {
        int i;
        int j;
        int a[3];
    } b;
};

int main()
{
    S s1 = {1, {2, 3, {4, 5, 6}}};
    S s2 = {1, 2, 3, 4, 5, 6};  // the same, but with brace elision
    S s3{1, {2, 3, {4, 5, 6}}}; // the same, using direct-list-initialization syntax
    S s4{1, 2, 3, 4, 5, 6}; // error until CWG 1270:
                            // brace elision only allowed with equals sign

    int ar[] = {1, 2, 3}; // ar is int[3]
//  char cr[3] = {'a', 'b', 'c', 'd'}; // too many initializer clauses
    char cr[3] = {'a'}; // array initialized as {'a', '\0', '\0'}

    int ar2d1[2][2] = {{1, 2}, {3, 4}}; // fully-braced 2D array: {1, 2}
                                        //                        {3, 4}
    int ar2d2[2][2] = {1, 2, 3, 4}; // brace elision: {1, 2}
                                    //                {3, 4}
    int ar2d3[2][2] = {{1}, {2}}; // only first column: {1, 0}
                                  //                    {2, 0}

    std::array<int, 3> std_ar2{{1, 2, 3}};  // std::array is an aggregate
    std::array<int, 3> std_ar1 = {1, 2, 3}; // brace-elision okay

//  int ai[] = {1, 2.0}; // narrowing conversion from double to int:
                         // error in C++11, okay in C++03

    std::string ars[] = {std::string("one"), // copy-initialization
                         "two",              // conversion, then copy-initialization
                         {'t', 'h', 'r', 'e', 'e'}}; // list-initialization
    union U
    {
        int a;
        const char* b;
    };
    U u1 = {1};         // OK, first member of the union
//  U u2 = {0, "asdf"}; // Error: too many initializers for union
//  U u3 = {"asdf"};    // Error: invalid conversion to int
}

// aggregate
struct Base1 { int b1, b2 = 42; };

// non-aggregate
struct Base2
{
    Base2() : b3(42) {} // constructor makes this class non-aggregate
    
    int b3;
};

// aggregate in C++17
struct Derived : Base1, Base2 { int d; };

Derived d1{{1, 2}, {}, 4}; // d1.b1 = 1, d1.b2 = 2,  d1.b3 = 42, d1.d = 4
Derived d2{{}, {}, 4};     // d2.b1 = 0, d2.b2 = 42, d2.b3 = 42, d2.d = 4

Defect reports

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

See also

• copy elision
• initialization
  • constant initialization
  • list initialization
  • reference initialization
  • value initialization
  • zero initialization