std::list::operator=(3)

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<T> 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 that of other. If the allocator of *this after assignment would compare unequal to its old value, the old (since allocator is used to deallocate the memory, then the new allocator is used to C++11) allocate it before copying the elements. Otherwise, the memory owned by *this may be reused when possible. In any case, the elements originally belong 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 belong 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
   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.requirements.general]/12, and a more direct guarantee is under
   consideration via LWG 2321.

Example
   The following code uses operator= to assign one std::list to another: // Run this code
 #include <list>
 #include <iterator>
 #include <iostream>
 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)