Initializes an object from abrace-enclosed initializer list.

[edit]Syntax

[edit]Direct-list-initialization

[edit]Copy-list-initialization

List initialization is performed in the following situations:

• direct-list-initialization (both explicit and non-explicit constructors are considered)

• copy-list-initialization (both explicit and non-explicit constructors are considered, but only non-explicit constructors may be called)

[edit]Explanation

The effects of list-initialization of an object of type (possibly cv-qualified)T are:

• IfT is an aggregate class and the brace-enclosed initializer list, which does not contain a designated initializer list,(since C++20) has a single initializer clause of the same or derived type (possibly cv-qualified), the object is initialized from that initializer clause (bycopy-initialization for copy-list-initialization, or bydirect-initialization for direct-list-initialization).
• Otherwise, ifT is a character array and the brace-enclosed initializer list has a single initializer clause that is an appropriately-typed string literal, the array isinitialized from the string literal as usual.

• Otherwise, ifT is anaggregate type,aggregate initialization is performed.

• Otherwise, if the brace-enclosed initializer list is empty andT is a class type with a default constructor,value-initialization is performed.

• Otherwise, ifT is a specialization ofstd::initializer_list, the object is initialized as describedbelow.

• Otherwise, ifT is a class type, the constructors ofT are considered, in two phases:

• All constructors that takestd::initializer_list as the only argument, or as the first argument if the remaining arguments have default values, are examined, and matched byoverload resolution against a single argument of typestd::initializer_list.

• If the previous stage does not produce a match, all constructors ofT participate inoverload resolution against the set of arguments that consists of the initializer clauses of the brace-enclosed initializer list, with the restriction that only non-narrowing conversions are allowed. If this stage produces an explicit constructor as the best match for a copy-list-initialization, compilation fails (note, in simple copy-initialization, explicit constructors are not considered at all).

• Otherwise (ifT is not a class type), if the brace-enclosed initializer list has only one initializer clause and eitherT is not a reference type or is a reference type whose referenced type is same as or is a base class of the type of the initializer clause,T isdirect-initialized (in direct-list-initialization) orcopy-initialized (in copy-list-initialization), except that narrowing conversions are not allowed.

• Otherwise, ifT is a reference type that is not compatible with the type of the initializer clause:

• Otherwise, if the brace-enclosed initializer list has no initializer clause,T isvalue-initialized.

[edit]List-initializingstd::initializer_list

An object of typestd::initializer_list<E> is constructed from an initializer list as if the compiler generated andmaterialized(since C++17) aprvalue of type “array ofNconst E”, whereN is the number of initializer clauses in the initializer list; this is called the initializer list’sbacking array.

Each element of the backing array iscopy-initialized with the corresponding initializer clause of the initializer list, and thestd::initializer_list<E> object is constructed to refer to that array. A constructor or conversion function selected for the copy is required to beaccessible in the context of the initializer list. If a narrowing conversion is required to initialize any of the elements, the program is ill-formed.

The backing array has the same lifetime as any othertemporary object, except that initializing anstd::initializer_list object from the backing array extends the lifetime of the array exactly likebinding a reference to a temporary.

void f(std::initializer_list<double> il); void g(float x){   f({1, x,3});} void h(){   f({1,2,3});} struct A{ mutableint i;}; void q(std::initializer_list<A>); void r(){    q({A{1}, A{2}, A{3}});} // The initialization above will be implemented in a way roughly equivalent to below,// assuming that the compiler can construct an initializer_list object with a pair of// pointers, and with the understanding that `__b` does not outlive the call to `f`. void g(float x){constdouble __a[3]={double{1},double{x},double{3}};// backing array    f(std::initializer_list<double>(__a, __a+3));} void h(){staticconstexprdouble __b[3]={double{1},double{2},double{3}};// backing array    f(std::initializer_list<double>(__b, __b+3));} void r(){const A __c[3]={A{1}, A{2}, A{3}};// backing array    q(std::initializer_list<A>(__c, __c+3));}

Whether all backing arrays are distinct (that is, are stored innon-overlapping objects) is unspecified:

bool fun(std::initializer_list<int> il1,std::initializer_list<int> il2){return il2.begin()== il1.begin()+1;} bool overlapping= fun({1,2,3},{2,3,4});// the result is unspecified:// the back arrays can share// storage within {1, 2, 3, 4}

[edit]Narrowing conversions

List-initialization limits the allowedimplicit conversions by prohibiting the following:

• conversion from a floating-point type to an integer type

• conversion from a floating-point typeT to another floating-point type whosefloating-point conversion rank is neither greater than nor equal to that ofT, except where the conversion result is aconstant expression and one of the following conditions is satisfied:
  • The converted value is finite, and the conversion does not overflow.
  • The values before and after the conversion are not finite.

• conversion from an integer type to a floating-point type, except where the source is a constant expression whose value can be stored exactly in the target type

• conversion from integer or unscoped enumeration type to integer type that cannot represent all values of the original, except where
  • the source is abit-field whose widthw is less than that of its type (or, for anenumeration type, its underlying type) and the target type can represent all the values of a hypothetical extended integer type with widthw and with the same signedness as the original type, or
  • the source is a constant expression whose value can be stored exactly in the target type

• conversion from a pointer type or pointer-to-member type tobool

[edit]Notes

Every initializer clause issequenced before any initializer clause that follows it in the brace-enclosed initializer list. This is in contrast with the arguments of afunction call expression, which areunsequenced(until C++17)indeterminately sequenced(since C++17).

A brace-enclosed initializer list is not an expression and therefore has no type, e.g.decltype({1,2}) is ill-formed. Having no type implies that template type deduction cannot deduce a type that matches a brace-enclosed initializer list, so given the declarationtemplate<class T>void f(T); the expressionf({1,2,3}) is ill-formed. However, the template parameter can otherwise be deduced, as is the case forstd::vector<int> v(std::istream_iterator<int>(std::cin),{}), where the iterator type is deduced by the first argument but also used in the second parameter position. A special exception is made fortype deduction using the keywordauto, which deduces any brace-enclosed initializer list asstd::initializer_list in copy-list-initialization.

Also because a brace-enclosed initializer list has no type,special rules for overload resolution apply when it is used as an argument to an overloaded function call.

Aggregates copy/move initialize directly from brace-enclosed initializer list of a single initializer clause of the same type, but non-aggregates considerstd::initializer_list constructors first:

struct X{};// aggregate struct Q// non-aggregate{    Q()=default;    Q(Qconst&)=default;    Q(std::initializer_list<Q>){}}; int main(){    X x;    X x2= X{x};// copy-constructor (not aggregate initialization)     Q q;    Q q2= Q{q};// initializer-list constructor (not copy constructor)}

Some compilers (e.g., gcc 10) only consider conversion from a pointer or a pointer-to-member tobool narrowing in C++20 mode.

[edit]Example

#include <iostream>#include <map>#include <string>#include <vector> struct Foo{std::vector<int> mem={1,2,3};// list-initialization of a non-static memberstd::vector<int> mem2;     Foo(): mem2{-1,-2,-3}{}// list-initialization of a member in constructor}; std::pair<std::string,std::string> f(std::pair<std::string,std::string> p){return{p.second, p.first};// list-initialization in return statement} int main(){int n0{};// value-initialization (to zero)int n1{1};// direct-list-initialization std::string s1{'a','b','c','d'};// initializer-list constructor callstd::string s2{s1,2,2};// regular constructor callstd::string s3{0x61,'a'};// initializer-list ctor is preferred to (int, char) int n2={1};// copy-list-initializationdouble d=double{1.2};// list-initialization of a prvalue, then copy-initauto s4=std::string{"HelloWorld"};// same as above, no temporary// created since C++17 std::map<int,std::string> m=// nested list-initialization{{1,"a"},{2,{'a','b','c'}},{3, s1}}; std::cout<< f({"hello","world"}).first// list-initialization in function call<<'\n'; constint(&ar)[2]={1,2};// binds an lvalue reference to a temporary arrayint&& r1={1};// binds an rvalue reference to a temporary int//  int& r2 = {2}; // error: cannot bind rvalue to a non-const lvalue ref //  int bad{1.0}; // error: narrowing conversionunsignedchar uc1{10};// okay//  unsigned char uc2{-1}; // error: narrowing conversion     Foo f; std::cout<< n0<<' '<< n1<<' '<< n2<<'\n'<< s1<<' '<< s2<<' '<< s3<<'\n';for(auto p: m)std::cout<< p.first<<' '<< p.second<<'\n';for(auto n: f.mem)std::cout<< n<<' ';for(auto n: f.mem2)std::cout<< n<<' ';std::cout<<'\n'; [](...){}(d, ar, r1, uc1);// has effect of [[maybe_unused]]}

world0 1 1abcd cd aa1 a2 abc3 abcd1 2 3 -1 -2 -3

[edit]Defect reports

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

[edit]See also

• constructor
• converting constructor
• copy assignment
• copy constructor
• copy elision
• default constructor
• explicit
• initialization
  • aggregate initialization
  • constant initialization
  • copy initialization
  • direct initialization
  • reference initialization
  • value initialization
  • zero initialization
• move assignment
• move constructor
• new

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文