Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/utility/initializer list"

From cppreference.com
< cpp‎ | utility
m
m (Example: extended)
 
(36 intermediate revisions by 20 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 {{tt|const T}}.
+
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 ''braced-init-list'' is used in [[cpp/language/list_initialization |list-initialization]], including function-call list initialization and assignment expressions
+
* 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 ''braced-init-list'' is bound to {{c|auto}}, including in a [[cpp/language/range-for | ranged for loop]]
+
* 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]].
  
Initializer lists may be implemented as a pair of pointers or pointer and length. Copying a {{tt|std::initializer_list}} does not copy the underlying objects.
+
{{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.
  
{{rev begin}}
+
The program is ill-formed if an explicit or partial specialization of {{tt|std::initializer_list}} is declared.
{{rev|until=c++14|The underlying array is not guaranteed to exist after the lifetime of the original initializer list object has ended.  The storage for {{tt|std::initializer_list}} is unspecified (i.e. it could be automatic, temporary, or static read-only memory, depending on the situation).}}
+
{{rev|since=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 [[cpp/language/lifetime#Temporary_object_lifetime|temporary object]], except that initializing an initializer_list object from the array extends the lifetime of the array exactly like [[cpp/language/reference_initialization#Lifetime_of_a_temporary|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.
+
}}
+
{{rev end}}
+
  
 
===Member types===
 
===Member types===
 
{{dsc begin}}
 
{{dsc begin}}
{{dsc hitem | Member type | Definition}}
+
{{dsc hitem|Name|Definition}}
{{dsc | {{tt|value_type}} | {{c|T}}}}
+
{{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}} | {{c|std::size_t}}}}
+
{{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 header|iterator}}
+
{{dsc h2|Free function templates overloaded for {{tt|std::initializer_list}}}}
{{dsc inc | cpp/utility/initializer_list/dsc rbegin2}}
+
{{dsc inc|cpp/iterator/dsc rbegin}}
{{dsc inc | cpp/utility/initializer_list/dsc rend2}}
+
{{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=
| code=
+
#include <cassert>
 +
#include <initializer_list>
 
#include <iostream>
 
#include <iostream>
 
#include <vector>
 
#include <vector>
#include <initializer_list>
 
  
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()}; // copy-list-initialization in return statement
+
     std::pair<const T*, std::size_t> c_arr() const
                                  // this is NOT a use of std::initializer_list
+
    {
 +
         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}; // direct list-initialization
+
     S<int> s = {1, 2, 3, 4, 5}; // copy list-initialization
     s.append({6, 7, 8});     // list-initialization in function call
+
     s.append({6, 7, 8});       // list-initialization in function call
 
+
   
     std::cout << "The vector size is now " << s.c_arr().second << " ints:\n";
+
     std::cout << "The vector now has " << s.c_arr().second << " ints:\n";  
 
+
     for (auto n : s.v)
     for (auto n : s.v) std::cout << ' ' << n;
+
        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};   // special rule for auto
+
     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
  
//   templated_fn({1, 2, 3}); // compiler error! "{1, 2, 3}" is not an expression,
+
    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=
+
|output=
 
constructed with a 5-element list
 
constructed with a 5-element list
The vector size is now 8 ints:
+
The vector now has 8 ints:
1 2 3 4 5 6 7 8
+
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
 
}}
 
}}
  
[[de:cpp/utility/initializer list]]
+
===Defect reports===
[[es:cpp/utility/initializer list]]
+
{{dr list begin}}
[[fr:cpp/utility/initializer list]]
+
{{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}}
[[it:cpp/utility/initializer list]]
+
{{dr list end}}
[[ja:cpp/utility/initializer list]]
+
 
[[pt:cpp/utility/initializer list]]
+
===See also===
[[ru:cpp/utility/initializer list]]
+
{{dsc begin}}
[[zh:cpp/utility/initializer list]]
+
{{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

 
 
Utilities library
General utilities
Relational operators (deprecated in C++20)
 
 

(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:

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) [edit]
Capacity
returns the number of elements in the initializer list
(public member function) [edit]
Iterators
returns a pointer to the first element
(public member function) [edit]
returns a pointer to one past the last element
(public member function) [edit]

[edit] Non-member functions

overloads std::begin
(function template) [edit]
specializes std::end
(function template) [edit]
Free function templates overloaded for std::initializer_list
returns a reverse iterator to the beginning of a container or array
(function template) [edit]
(C++14)
returns a reverse end iterator for a container or array
(function template) [edit]
(C++17)
checks whether the container is empty
(function template) [edit]
(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 <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 explicit
specializations 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) [edit]
read-only string view
(class template) [edit]