std::initializer_list

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Utilities library

Type support (basic types, RTTI, type traits)

Dynamic memory management

Error handling

Program utilities

Variadic functions

Date and time

Function objects

initializer_list (C++11)

bitset

hash (C++11)

Relational operators

rel_ops::operator!=rel_ops::operator>rel_ops::operator<=rel_ops::operator>=

Pairs and tuples

pair

tuple (C++11)

piecewise_construct_t (C++11)

piecewise_construct (C++11)

integer_sequence (C++14)

Swap, forward and move

swap

exchange (C++14)

forward (C++11)

move (C++11)

move_if_noexcept (C++11)

declval (C++11)

 

std::initializer_list

Member functions

initializer_list::initializer_list

Capacity

initializer_list::size

Iterators

initializer_list::begin

initializer_list::end

Non-member functions

std::begin

std::end

std::rbegin (C++14)

std::rend (C++14)

 

(not to be confused with member initializer list)

Defined in header <initializer_list>
template< class T > class initializer_list;		(since C++11)

An object of type std::initializer_list<T> is a lightweight proxy object that provides access to an array of objects of type const T.

A std::initializer_list object is automatically constructed when:

• a braced-init-list is used in list-initialization, including function-call list initialization and assignment expressions
• a braced-init-list is bound to auto, including in a ranged for loop

Initializer lists may be implemented as a pair of pointers or pointer and length. Copying a std::initializer_list does not copy the underlying objects.

The underlying array is not guaranteed to exist after the lifetime of the original initializer list object has ended. The storage for std::initializer_list is unspecified (i.e. it could be automatic, temporary, or static read-only memory, depending on the situation).	(until C++14)
The underlying array is a temporary array, in which each element is copy-initialized (except that narrowing conversions are invalid) from the corresponding element of the original initializer list. The lifetime of the underlying array is the same as any other temporary object, except that initializing an initializer_list object from the array extends the lifetime of the array exactly like binding a reference to a temporary (with the same exceptions, such as for initializing a non-static class member). The underlying array may be allocated in read-only memory.	(since C++14)
The program is ill-formed if an explicit or partial specialization of std::initializer_list is declared.	(since C++17)

Member types

Member type	Definition
value_type	T
reference	const T&
const_reference	const T&
size_type	std::size_t
iterator	const T*
const_iterator	const T*

Member functions

(constructor)	creates an empty initializer list (public member function)
Capacity
size	returns the number of elements in the initializer list (public member function)
Iterators
begin	returns a pointer to the first element (public member function)
end	returns a pointer to one past the last element (public member function)

Non-member functions

std::begin(std::initializer_list) (C++11)	specializes std::begin (function template)
std::end(std::initializer_list) (C++11)	specializes std::end (function template)
Defined in header <iterator>
rbegin(std::initializer_list) (C++14)	specializes std::rbegin (function)
rend(std::initializer_list) (C++14)	specializes std::rend (function)

Example

Run this code

#include <iostream>
#include <vector>
#include <initializer_list>
 
template <class T>
struct S {
    std::vector<T> v;
    S(std::initializer_list<T> l) : v(l) {
         std::cout << "constructed with a " << l.size() << "-element list\n";
    }
    void append(std::initializer_list<T> l) {
        v.insert(v.end(), l.begin(), l.end());
    }
    std::pair<const T*, std::size_t> c_arr() const {
        return {&v[0], v.size()};  // copy list-initialization in return statement
                                   // this is NOT a use of std::initializer_list
    }
};
 
template <typename T>
void templated_fn(T) {}
 
int main()
{
    S<int> s = {1, 2, 3, 4, 5}; // copy list-initialization
    s.append({6, 7, 8});      // list-initialization in function call
 
    std::cout << "The vector size is now " << s.c_arr().second << " ints:\n";
 
    for (auto n : s.v)
        std::cout << n << ' ';
    std::cout << '\n';
 
    std::cout << "Range-for over brace-init-list: \n";
 
    for (int x : {-1, -2, -3}) // the rule for auto makes this ranged-for work
        std::cout << x << ' ';
    std::cout << '\n';
 
    auto al = {10, 11, 12};   // special rule for auto
 
    std::cout << "The list bound to auto has size() = " << al.size() << '\n';
 
//    templated_fn({1, 2, 3}); // compiler error! "{1, 2, 3}" is not an expression,
                             // it has no type, and so T cannot be deduced
    templated_fn<std::initializer_list<int>>({1, 2, 3}); // OK
    templated_fn<std::vector<int>>({1, 2, 3});           // also OK
}

Output:

constructed with a 5-element list
The vector size is now 8 ints:
1 2 3 4 5 6 7 8
Range-for over brace-init-list: 
-1 -2 -3 
The list bound to auto has size() = 3