Difference between revisions of "cpp/utility/initializer list"
From cppreference.com
m |
m (→Example: extended) |
||
(30 intermediate revisions by 18 users not shown) | |||
Line 1: | Line 1: | ||
{{cpp/title|initializer_list}} | {{cpp/title|initializer_list}} | ||
{{cpp/utility/initializer_list/navbar}} | {{cpp/utility/initializer_list/navbar}} | ||
− | (not to be confused with [[cpp/language/initializer list|member initializer list]]) | + | {{petty|(not to be confused with [[cpp/language/initializer list|member initializer list]])}} |
− | {{ddcl | header = initializer_list | since=c++11 | | + | {{ddcl|header=initializer_list|since=c++11| |
template< class T > | template< class T > | ||
class initializer_list; | class initializer_list; | ||
}} | }} | ||
− | An object of type {{tt|std::initializer_list<T>}} is a lightweight proxy object that provides access to an array of objects of type {{ | + | An object of type {{tt|std::initializer_list<T>}} is a lightweight proxy object that provides access to an array of objects of type {{c/core|const T}} (that may be allocated in read-only memory). |
A {{tt|std::initializer_list}} object is automatically constructed when: | A {{tt|std::initializer_list}} object is automatically constructed when: | ||
− | * a | + | * a [[cpp/language/initialization|brace-enclosed initializer list]] is used to [[cpp/language/list initialization|list-initialize]] an object, where the corresponding constructor accepts an {{tt|std::initializer_list}} parameter, |
− | * a | + | * a brace-enclosed initializer list is used as the right operand of [[cpp/language/operator assignment#Builtin direct assignment|assignment]] or as a [[cpp/language/overload resolution#Implicit conversion sequence in list-initialization|function call argument]], and the corresponding assignment operator/function accepts an {{tt|std::initializer_list}} parameter, |
+ | * a brace-enclosed initializer list is bound to {{ltt|cpp/language/auto}}, including in a [[cpp/language/range-for|ranged for loop]]. | ||
− | + | {{tt|std::initializer_list}} may be implemented as a pair of pointers or pointer and length. Copying a {{tt|std::initializer_list}} does not copy the [[cpp/language/list initialization#List-initializing std::initializer_list|backing array]] of the corresponding initializer list. | |
− | |||
− | |||
− | |||
− | |||
− | |||
The program is ill-formed if an explicit or partial specialization of {{tt|std::initializer_list}} is declared. | The program is ill-formed if an explicit or partial specialization of {{tt|std::initializer_list}} is declared. | ||
− | |||
− | |||
===Member types=== | ===Member types=== | ||
{{dsc begin}} | {{dsc begin}} | ||
− | {{dsc hitem | | + | {{dsc hitem|Name|Definition}} |
− | {{dsc | {{tt|value_type}} | {{ | + | {{dsc|{{tt|value_type}}|{{tt|T}}}} |
− | {{dsc | {{tt|reference}} | {{c|const T&}}}} | + | {{dsc|{{tt|reference}}|{{c/core|const T&}}}} |
− | {{dsc | {{tt|const_reference}} | {{c|const T&}}}} | + | {{dsc|{{tt|const_reference}}|{{c/core|const T&}}}} |
− | {{dsc | {{tt|size_type}} | {{ | + | {{dsc|{{tt|size_type}}|{{lc|std::size_t}}}} |
− | {{dsc | {{tt|iterator}} | {{c|const T*}}}} | + | {{dsc|{{tt|iterator}}|{{c/core|const T*}}}} |
− | {{dsc | {{tt|const_iterator}} | {{c|const T*}}}} | + | {{dsc|{{tt|const_iterator}}|{{c/core|const T*}}}} |
{{dsc end}} | {{dsc end}} | ||
===Member functions=== | ===Member functions=== | ||
{{dsc begin}} | {{dsc begin}} | ||
− | {{dsc inc | cpp/utility/initializer_list/dsc constructor}} | + | {{dsc inc|cpp/utility/initializer_list/dsc constructor}} |
− | {{dsc h2 | Capacity}} | + | {{dsc h2|Capacity}} |
− | {{dsc inc | cpp/utility/initializer_list/dsc size}} | + | {{dsc inc|cpp/utility/initializer_list/dsc size}} |
− | {{dsc h2 | Iterators}} | + | {{dsc h2|Iterators}} |
− | {{dsc inc | cpp/utility/initializer_list/dsc begin}} | + | {{dsc inc|cpp/utility/initializer_list/dsc begin}} |
− | {{dsc inc | cpp/utility/initializer_list/dsc end}} | + | {{dsc inc|cpp/utility/initializer_list/dsc end}} |
{{dsc end}} | {{dsc end}} | ||
===Non-member functions=== | ===Non-member functions=== | ||
{{dsc begin}} | {{dsc begin}} | ||
− | {{dsc inc | cpp/utility/initializer_list/dsc begin2}} | + | {{dsc inc|cpp/utility/initializer_list/dsc begin2}} |
− | {{dsc inc | cpp/utility/initializer_list/dsc end2}} | + | {{dsc inc|cpp/utility/initializer_list/dsc end2}} |
− | {{dsc | + | {{dsc h2|Free function templates overloaded for {{tt|std::initializer_list}}}} |
− | {{dsc inc | cpp/ | + | {{dsc inc|cpp/iterator/dsc rbegin}} |
− | {{dsc inc | cpp/ | + | {{dsc inc|cpp/iterator/dsc rend}} |
+ | {{dsc inc|cpp/iterator/dsc empty}} | ||
+ | {{dsc inc|cpp/iterator/dsc data}} | ||
{{dsc end}} | {{dsc end}} | ||
+ | |||
+ | ===Notes=== | ||
+ | {{feature test macro|std=C++11|value=200806L|__cpp_initializer_lists|[[cpp/language/list initialization|List-initialization]] and {{tt|std::initializer_list}}}} | ||
===Example=== | ===Example=== | ||
{{example | {{example | ||
− | + | |code= | |
− | + | #include <cassert> | |
+ | #include <initializer_list> | ||
#include <iostream> | #include <iostream> | ||
#include <vector> | #include <vector> | ||
− | + | ||
− | + | template<class T> | |
− | template <class T> | + | struct S |
− | struct S { | + | { |
std::vector<T> v; | std::vector<T> v; | ||
− | S(std::initializer_list<T> l) : v(l) { | + | |
+ | S(std::initializer_list<T> l) : v(l) | ||
+ | { | ||
std::cout << "constructed with a " << l.size() << "-element list\n"; | std::cout << "constructed with a " << l.size() << "-element list\n"; | ||
} | } | ||
− | void append(std::initializer_list<T> l) { | + | |
+ | void append(std::initializer_list<T> l) | ||
+ | { | ||
v.insert(v.end(), l.begin(), l.end()); | v.insert(v.end(), l.begin(), l.end()); | ||
} | } | ||
− | std::pair<const T*, std::size_t> c_arr() const { | + | |
− | return {&v[0], v.size()}; | + | 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> | + | template<typename T> |
void templated_fn(T) {} | void templated_fn(T) {} | ||
− | + | ||
int main() | int main() | ||
{ | { | ||
S<int> s = {1, 2, 3, 4, 5}; // copy list-initialization | S<int> s = {1, 2, 3, 4, 5}; // copy list-initialization | ||
− | s.append({6, 7, 8}); | + | s.append({6, 7, 8}); // list-initialization in function call |
− | + | ||
− | std::cout << "The vector | + | std::cout << "The vector now has " << s.c_arr().second << " ints:\n"; |
− | + | ||
for (auto n : s.v) | for (auto n : s.v) | ||
− | std::cout << | + | std::cout << n << ' '; |
std::cout << '\n'; | std::cout << '\n'; | ||
− | + | ||
std::cout << "Range-for over brace-init-list: \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 | for (int x : {-1, -2, -3}) // the rule for auto makes this ranged-for work | ||
std::cout << x << ' '; | std::cout << x << ' '; | ||
std::cout << '\n'; | std::cout << '\n'; | ||
− | + | ||
− | auto al = {10, 11, 12}; | + | auto al = {10, 11, 12}; // special rule for auto |
− | + | ||
std::cout << "The list bound to auto has size() = " << al.size() << '\n'; | 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<int> 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 | // it has no type, and so T cannot be deduced | ||
templated_fn<std::initializer_list<int>>({1, 2, 3}); // OK | templated_fn<std::initializer_list<int>>({1, 2, 3}); // OK | ||
templated_fn<std::vector<int>>({1, 2, 3}); // also OK | templated_fn<std::vector<int>>({1, 2, 3}); // also OK | ||
} | } | ||
− | + | |output= | |
constructed with a 5-element list | constructed with a 5-element list | ||
− | The vector | + | The vector now has 8 ints: |
− | + | 1 2 3 4 5 6 7 8 | |
− | Range-for over brace-init-list: | + | Range-for over brace-init-list: |
− | -1 -2 -3 | + | -1 -2 -3 |
The list bound to auto has size() = 3 | The list bound to auto has size() = 3 | ||
}} | }} | ||
− | + | ===Defect reports=== | |
− | + | {{dr list begin}} | |
− | + | {{dr list item|wg=lwg|dr=2129|std=C++11|before={{tt|std::initializer_list}} could have explicit<br>specializations or partial specializations|after=the program is<br>ill-formed in this case}} | |
− | + | {{dr list end}} | |
− | + | ||
− | + | ===See also=== | |
− | + | {{dsc begin}} | |
− | + | {{dsc inc|cpp/container/dsc span}} | |
+ | {{dsc inc|cpp/string/dsc basic_string_view}} | ||
+ | {{dsc end}} | ||
+ | |||
+ | {{langlinks|de|es|fr|it|ja|pt|ru|zh}} |
Latest revision as of 16:01, 20 October 2024
(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 (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 |
[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
creates an empty initializer list (public member function) | |
Capacity | |
returns the number of elements in the initializer list (public member function) | |
Iterators | |
returns a pointer to the first element (public member function) | |
returns a pointer to one past the last element (public member function) |
[edit] Non-member functions
overloads std::begin (function template) | |
specializes std::end (function template) | |
Free function templates overloaded for
| |
(C++14) |
returns a reverse iterator to the beginning of a container or array (function template) |
(C++14) |
returns a reverse end iterator for a container or array (function template) |
(C++17) |
checks whether the container is empty (function template) |
(C++17) |
obtains the pointer to the underlying array (function template) |
[edit] Notes
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_initializer_lists |
200806L | (C++11) | List-initialization and std::initializer_list
|
[edit] Example
Run this code
#include <cassert> #include <initializer_list> #include <iostream> #include <vector> 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 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<int> 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<int>>({1, 2, 3}); // OK templated_fn<std::vector<int>>({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 is ill-formed in this case |
[edit] See also
(C++20) |
a non-owning view over a contiguous sequence of objects (class template) |
(C++17) |
read-only string view (class template) |