std::initializer_list - cppreference.com (original) (raw)
(not to be confused with member 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 (that may be allocated in read-only memory).
A std::initializer_list
object is automatically constructed when:
- a brace-enclosed initializer list is used to list-initialize an object, where the corresponding constructor accepts an
std::initializer_list
parameter, - a brace-enclosed initializer 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 brace-enclosed initializer list is bound to auto, including in a ranged for loop.
std::initializer_list
may be implemented as a pair of pointers or pointer and length. Copying a std::initializer_list
does not copy the backing array of the corresponding initializer list.
The program is ill-formed if an explicit or partial specialization of std::initializer_list
is declared.
Contents
- 1 Member types
- 2 Member functions
- 3 Non-member functions
- 4 Notes
- 5 Example
- 6 Defect reports
- 7 See also
[edit] Member types
Name | Definition |
---|---|
value_type | T |
reference | const T& |
const_reference | const T& |
size_type | std::size_t |
iterator | const T* |
const_iterator | const T* |
[edit] Member functions
(constructor) | creates an empty initializer list (public member function) [edit] |
---|---|
Capacity | |
size | returns the number of elements in the initializer list (public member function) [edit] |
Iterators | |
begin | returns a pointer to the first element (public member function) [edit] |
end | returns a pointer to one past the last element (public member function) [edit] |
[edit] Non-member functions
std::begin(std::initializer_list)(C++11) | overloads std::begin (function template) [edit] |
---|---|
std::end(std::initializer_list)(C++11) | specializes std::end (function template) [edit] |
Free function templates overloaded for std::initializer_list | |
rbegincrbegin(C++14) | returns a reverse iterator to the beginning of a container or array (function template) [edit] |
rendcrend(C++14) | returns a reverse end iterator for a container or array (function template) [edit] |
empty(C++17) | checks whether the container is empty (function template) [edit] |
data(C++17) | obtains the pointer to the underlying array (function template) [edit] |
[edit] Notes
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_initializer_lists | 200806L | (C++11) | List-initialization and std::initializer_list |
[edit] Example
#include
#include
#include
#include
template
struct S
{
std::vector v;
S(std::initializer_list l) : v(l)
{
std::cout << "constructed with a " << l.size() << "-element list\n";
}
void append(std::initializer_list 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
void templated_fn(T) {}
int main()
{
S s = {1, 2, 3, 4, 5}; // copy list-initialization
s.append({6, 7, 8}); // list-initialization in function call
std::cout << "The vector now has " << 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';
auto la = al; // a shallow-copy of top-level proxy object
assert(la.begin() == al.begin()); // guaranteed: backing array is the same
std::initializer_list il{-3, -2, -1};
assert(il.begin()[2] == -1); // note the replacement for absent operator[]
il = al; // shallow-copy
assert(il.begin() == al.begin()); // guaranteed
// 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>({1, 2, 3}); // OK
templated_fn<std::vector>({1, 2, 3}); // also OK
}
Output:
constructed with a 5-element list The vector now has 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
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 2129 | C++11 | std::initializer_list could have explicitspecializations or partial specializations | the program isill-formed in this case |