std::initializer_list (3) - Linux Manuals

std::initializer_list: std::initializer_list

NAME

std::initializer_list - std::initializer_list

Synopsis

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

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 to list-initialize an object, where the corresponding constructor accepts an std::initializer_list parameter
* a braced-init-list is used as the right operand of assignment or as a function_call_argument, and the corresponding assignment operator/function accepts an std::initializer_list parameter
* 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 of type const T[N], 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

              creates an empty initializer list
constructor (public member function)

Capacity

              returns the number of elements in the initializer list
size (public member function)

Iterators

              returns a pointer to the first element
begin (public member function)
              returns a pointer to one past the last element
end (public member function)

Non-member functions

std::begin(std::initializer_list) specializes std::begin
                                  (function template)
(C++11)

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

rbegin(std::initializer_list) specializes std::rbegin
                                  (function)
(C++14)

rend(std::initializer_list) specializes std::rend
                                  (function)
(C++14)

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