NAME¶

std::list::operator= - std::list::operator=

Synopsis¶

list& operator=( const list& other ); (1)
list& operator=( list&& other ); (since C++11)
(2) (until C++17)
list& operator=( list&& other ) noexcept(/* see below */); (since C++17)
list& operator=( std::initializer_list<value_type> ilist ); (3) (since C++11)

Replaces the contents of the container.

1) Copy assignment operator. Replaces the contents with a copy of the contents of
other.

If std::allocator_traits<allocator_type>::propagate_on_container_copy_assignment::value is true, the allocator of *this is replaced by a copy of other. If the allocator of *this after assignment would compare unequal to its old value, the old allocator is (since used to deallocate the memory, then the new allocator is used to allocate it before C++11) copying the elements. Otherwise, the memory owned by *this may be reused when possible. In any case, the elements originally belonging to *this may be either destroyed or replaced by element-wise copy-assignment.

2) Move assignment operator. Replaces the contents with those of other using move
semantics (i.e. the data in other is moved from other into this container). other is
in a valid but unspecified state afterwards.
If
std::allocator_traits<allocator_type>::propagate_on_container_move_assignment::value
is true, the allocator of *this is replaced by a copy of that of other. If it is
false and the allocators of *this and other do not compare equal, *this cannot take
ownership of the memory owned by other and must move-assign each element
individually, allocating additional memory using its own allocator as needed. In any
case, all elements originally belonging to *this are either destroyed or replaced by
element-wise move-assignment.
3) Replaces the contents with those identified by initializer list ilist.

Parameters¶

other - another container to use as data source
ilist - initializer list to use as data source

Return value¶

*this

Complexity¶

1) Linear in the size of *this and other.
2) Linear in the size of *this unless the allocators do not compare equal and do not
propagate, in which case linear in the size of *this and other.
3) Linear in the size of *this and ilist.

Exceptions¶

1-3) May throw implementation-defined exceptions. (until C++17)
1,3) May throw implementation-defined exceptions.
2) (since C++17)
noexcept specification:
noexcept(std::allocator_traits<Allocator>::is_always_equal::value)

Notes¶

After container move assignment (overload (2)), unless element-wise move assignment
is forced by incompatible allocators, references, pointers, and iterators (other
than the end iterator) to other remain valid, but refer to elements that are now in
*this. The current standard makes this guarantee via the blanket statement in
[container.reqmts]/67, and a more direct guarantee is under consideration via LWG
issue 2321.

Example¶

The following code uses operator= to assign one std::list to another:

// Run this code

#include <initializer_list>
#include <iostream>
#include <iterator>
#include <list>

void print(auto const comment, auto const& container)
{
auto size = std::size(container);
std::cout << comment << "{ ";
for (auto const& element : container)
std::cout << element << (--size ? ", " : " ");
std::cout << "}\n";
}

int main()
{
std::list<int> x{1, 2, 3}, y, z;
const auto w = {4, 5, 6, 7};

std::cout << "Initially:\n";
print("x = ", x);
print("y = ", y);
print("z = ", z);

std::cout << "Copy assignment copies data from x to y:\n";
y = x;
print("x = ", x);
print("y = ", y);

std::cout << "Move assignment moves data from x to z, modifying both x and z:\n";
z = std::move(x);
print("x = ", x);
print("z = ", z);

std::cout << "Assignment of initializer_list w to z:\n";
z = w;
print("w = ", w);
print("z = ", z);
}

Output:¶

Initially:
x = { 1, 2, 3 }
y = { }
z = { }
Copy assignment copies data from x to y:
x = { 1, 2, 3 }
y = { 1, 2, 3 }
Move assignment moves data from x to z, modifying both x and z:
x = { }
z = { 1, 2, 3 }
Assignment of initializer_list w to z:
w = { 4, 5, 6, 7 }
z = { 4, 5, 6, 7 }

See also¶

constructor constructs the list
(public member function)
assign assigns values to the container
(public member function)

Category:¶

* conditionally noexcept