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)

 

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)

Swap, forward and move

swap

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

 

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 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 (not to be confused with constructor initializer lists)
• 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).

Member types

Member type	Definition
value_type	T
reference	const T&
const_reference	const T&
size_type	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 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)

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()};  // 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}; // direct 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