Namespaces
Variants
Views
Actions

Difference between revisions of "Template:cpp/container/swap"

From cppreference.com
(past the end iterator is invalidated)
m (Added {{#var:cont}} to simplify page testing.)
 
(35 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
{{cpp/container/{{{1|}}}/title | swap}}
+
{{#vardefine:cont|{{{1|list}}}}}<!--
−
{{cpp/container/{{{1|}}}/navbar}}
+
-->{{cpp/container/{{#var:cont}}/title|swap}}
−
{{ddcl | notes={{cpp/container/mark since c++11 | {{{1|}}} }} |
+
{{cpp/container/{{#var:cont}}/navbar}}
−
void swap( {{{1}}}& other );
+
{{dcl begin}}
 +
{{#switch:{{#var:cont}}
 +
|vector=
 +
{{dcl rev multi
 +
|dcl1=
 +
void swap( vector& other );
 +
|since2=c++17|dcl2=
 +
void swap( vector& other ) noexcept(/* see below */);
 +
|since3=c++20|dcl3=
 +
constexpr void swap( vector& other ) noexcept(/* see below */);
 
}}
 
}}
 +
|
 +
{{dcl rev multi
 +
|since1={{cpp/std|{{#var:cont}}}}|dcl1=
 +
void swap( {{#var:cont}}& other );
 +
|since2=c++17|dcl2=
 +
void swap( {{#var:cont}}& other ) noexcept(/* see below */);
 +
}}
 +
}}
 +
{{dcl end}}
  
−
{{#ifeq: {{{1|}}} | array
+
Exchanges the contents {{#switch:{{#var:cont}}|vector=and capacity}} of the container with those of {{c|other}}. Does not invoke any move, copy, or swap operations on individual elements.
−
| Exchanges the contents of the container with those of {{tt|other}}. Does not cause iterators and references to associate with the other container.
+
−
| Exchanges the contents of the container with those of {{tt|other}}. All iterators and references remain valid. The past-the-end iterator is invalidated.
+
  
−
The behavior is undefined if {{c|1=get_allocator() != other.get_allocator()}} and {{c|1=std::allocator_traits<allocator_type>::propagate_on_container_swap::value != true}}.
+
{{cpp/container/note iterator invalidation|{{#var:cont}}|swap}}
 +
<!---->
 +
{{#switch:{{#var:cont}}
 +
|map|set|multimap|multiset=The {{tt|Compare}} objects must be {{named req|Swappable}}, and they are exchanged using unqualified call to non-member {{tt|swap}}.
 +
|unordered_map|unordered_set|unordered_multimap|unordered_multiset=The {{tt|Hash}} and {{tt|KeyEqual}} objects must be {{named req|Swappable}}, and they are exchanged using unqualified calls to non-member {{tt|swap}}.
 
}}
 
}}
 +
{{rrev|since=c++11|
 +
If {{c|std::allocator_traits<allocator_type>::propagate_on_container_swap::value}} is {{c|true}}, then the allocators are exchanged using an unqualified call to non-member {{tt|swap}}. Otherwise, they are not swapped (and if {{c|1=get_allocator() != other.get_allocator()}}, the behavior is undefined).}}
  
 
===Parameters===
 
===Parameters===
−
{{param list begin}}
+
{{par begin}}
−
{{param list item | other | container to exchange the contents with}}
+
{{par|other|container to exchange the contents with}}
−
{{param list end}}
+
{{par end}}
  
 
===Return value===
 
===Return value===
Line 21: Line 43:
  
 
===Exceptions===
 
===Exceptions===
−
{{#ifeq: {{{1|}}} |array
+
{{rrev multi|until1=c++17
−
|{{noexcept|noexcept(std::swap(declval<T&>(), declval<T&>()))}}
+
|rev1=
−
|{{noexcept}}
+
{{#switch:{{#var:cont}}
 +
|map|set|multimap|multiset=Any exception thrown by the swap of the {{tt|Compare}} objects.
 +
|unordered_map|unordered_set|unordered_multimap|unordered_multiset=Any exception thrown by the swap of the {{tt|Hash}} or {{tt|KeyEqual}} objects.
 +
|(none)
 +
}}
 +
|rev2=
 +
{{#switch:{{#var:cont}}|deque|forward_list|list=
 +
{{noexcept|std::allocator_traits<Allocator>::is_always_equal::value}}
 +
|vector=
 +
{{noexcept|std::allocator_traits<Allocator>::propagate_on_container_swap::value
 +
{{!!}} std::allocator_traits<Allocator>::is_always_equal::value}}
 +
|set|multiset|map|multimap=
 +
{{noexcept|std::allocator_traits<Allocator>::is_always_equal::value
 +
&& std::is_nothrow_swappable<Compare>::value}}
 +
|unordered_map|unordered_multimap|unordered_set|unordered_multiset=
 +
{{noexcept|std::allocator_traits<Allocator>::is_always_equal::value
 +
&& std::is_nothrow_swappable<Hash>::value
 +
&& std::is_nothrow_swappable<key_equal>::value}}
 +
|{{included}}
 +
}}
 
}}
 
}}
  
 
===Complexity===
 
===Complexity===
−
{{#ifeq: {{{1|}}} | array
+
Constant.
−
|Linear in size of the container.
+
 
−
|Constant
+
===Example===
 +
{{#switch:{{#var:cont}}
 +
|vector|deque|list|forward_list=
 +
{{example
 +
|code=
 +
#include <iostream>
 +
#include <{{#var:cont}}>
 +
 
 +
template<class Os, class Co>
 +
Os& operator<<(Os& os, const Co& co)
 +
{
 +
    os << '{';
 +
    for (auto const& i : co)
 +
        os << ' ' << i;
 +
    return os << " } ";
 +
}
 +
 
 +
int main()
 +
{
 +
    std::{{#var:cont}}<int> a1{1, 2, 3}, a2{4, 5};
 +
   
 +
    auto it1 = std::next(a1.begin());
 +
    auto it2 = std::next(a2.begin());
 +
   
 +
    int& ref1 = a1.front();
 +
    int& ref2 = a2.front();
 +
   
 +
    std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\n';
 +
    a1.swap(a2);
 +
    std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\n';
 +
   
 +
    // Note that after swap the iterators and references stay associated with their
 +
    // original elements, e.g. it1 that pointed to an element in 'a1' with value 2
 +
    // still points to the same element, though this element was moved into 'a2'.
 +
}
 +
|output=
 +
{ 1 2 3 } { 4 5 } 2 5 1 4
 +
{ 4 5 } { 1 2 3 } 2 5 1 4
 
}}
 
}}
 +
|set|multiset=
 +
{{example
 +
|code=
 +
#include <functional>
 +
#include <iostream>
 +
#include <set>
  
 +
template<class Os, class Co>
 +
Os& operator<<(Os& os, const Co& co)
 +
{
 +
    os << '{';
 +
    for (auto const& i : co)
 +
        os << ' ' << i;
 +
    return os << " } ";
 +
}
 +
 +
int main()
 +
{
 +
    std::{{#var:cont}}<int> a1{3, 1, 3, 2}, a2{5, 4, 5};
 +
   
 +
    auto it1 = std::next(a1.begin());
 +
    auto it2 = std::next(a2.begin());
 +
   
 +
    const int& ref1 = *(a1.begin());
 +
    const int& ref2 = *(a2.begin());
 +
   
 +
    std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\n';
 +
    a1.swap(a2);
 +
    std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\n';
 +
   
 +
    // Note that every iterator referring to an element in one container before the swap
 +
    // refers to the same element in the other container after the swap. Same is true
 +
    // for references.
 +
   
 +
    struct Cmp : std::less<int>
 +
    {
 +
        int id{};
 +
        Cmp(int i) : id{i} {}
 +
    };
 +
   
 +
    std::{{#var:cont}}<int, Cmp> s1{{2, 2, 1, 1}, Cmp{6}}, s2{{4, 4, 3, 3}, Cmp{9}};
 +
   
 +
    std::cout << s1 << s2 << s1.key_comp().id << ' ' << s2.key_comp().id << '\n';
 +
    s1.swap(s2);
 +
    std::cout << s1 << s2 << s1.key_comp().id << ' ' << s2.key_comp().id << '\n';
 +
   
 +
    // So, comparator objects (Cmp) are also exchanged after the swap.
 +
}
 +
|output=
 +
{{#switch:{{#var:cont}}
 +
|set=
 +
{ 1 2 3 } { 4 5 } 2 5 1 4
 +
{ 4 5 } { 1 2 3 } 2 5 1 4
 +
{ 1 2 } { 3 4 } 6 9
 +
{ 3 4 } { 1 2 } 9 6
 +
|multiset=
 +
{ 1 2 3 3 } { 4 5 5 } 2 5 1 4
 +
{ 4 5 5 } { 1 2 3 3 } 2 5 1 4
 +
{ 1 1 2 2 } { 3 3 4 4 } 6 9
 +
{ 3 3 4 4 } { 1 1 2 2 } 9 6
 +
}}
 +
}}
 +
|unordered_set|unordered_multiset=
 +
{{example
 +
|code=
 +
#include <iostream>
 +
#include <unordered_set>
 +
 +
template<class Os, class Co> Os& operator<<(Os& os, const Co& co)
 +
{
 +
    os << '{';
 +
    for (auto const& i : co)
 +
        os << ' ' << i;
 +
    return os << " } ";
 +
}
 +
 +
int main()
 +
{
 +
    std::{{#var:cont}}<int> a1{3, 1, 3, 2}, a2{5, 4, 5};
 +
   
 +
    auto it1 = std::next(a1.begin());
 +
    auto it2 = std::next(a2.begin());
 +
   
 +
    const int& ref1 = *(a1.begin());
 +
    const int& ref2 = *(a2.begin());
 +
   
 +
    std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\n';
 +
    a1.swap(a2);
 +
    std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\n';
 +
   
 +
    // Note that every iterator referring to an element in one container before the swap
 +
    // refers to the same element in the other container after the swap. Same is true
 +
    // for references.
 +
}
 +
|p=true
 +
|output=
 +
{{#switch:{{#var:cont}}
 +
|unordered_set=
 +
{ 2 1 3 } { 4 5 } 1 5 2 4
 +
{ 4 5 } { 2 1 3 } 1 5 2 4
 +
|unordered_multiset=
 +
{ 2 3 3 1 } { 4 5 5 } 3 5 2 4
 +
{ 4 5 5 } { 2 3 3 1 } 3 5 2 4
 +
}}
 +
}}
 +
|map|multimap|unordered_map|unordered_multimap=
 +
{{example|code=
 +
#include <iostream>
 +
#include <string>
 +
#include <utility>
 +
{{#switch:{{#var:cont}}
 +
|map|multimap=
 +
#include <map>
 +
|unordered_map|unordered_multimap=
 +
#include <unordered_map>
 +
}}
 +
 +
// print out a std::pair
 +
template<class Os, class U, class V>
 +
Os& operator<<(Os& os, const std::pair<U, V>& p)
 +
{
 +
    return os << p.first << ':' << p.second;
 +
}
 +
 +
// print out a container
 +
template<class Os, class Co>
 +
Os& operator<<(Os& os, const Co& co)
 +
{
 +
    os << '{';
 +
    for (auto const& i : co)
 +
        os << ' ' << i;
 +
    return os << " }\n";
 +
}
 +
 +
int main()
 +
{
 +
    std::{{#var:cont}}<std::string, std::string>
 +
        m1{{"γ", "gamma"}, {"β", "beta"}, {"α", "alpha"}, {"γ", "gamma"}},
 +
        m2{{"ε", "epsilon"}, {"δ", "delta"}, {"ε", "epsilon"}};
 +
   
 +
    const auto& ref = *(m1.begin());
 +
    const auto iter = std::next(m1.cbegin());
 +
   
 +
    std::cout << "──────── before swap ────────\n"
 +
              << "m1: " << m1 << "m2: " << m2 << "ref: " << ref
 +
              << "\niter: " << *iter << '\n';
 +
   
 +
    m1.swap(m2);
 +
   
 +
    std::cout << "──────── after swap ────────\n"
 +
              << "m1: " << m1 << "m2: " << m2 << "ref: " << ref
 +
              << "\niter: " << *iter << '\n';
 +
   
 +
    // Note that every iterator referring to an element in one container before
 +
    // the swap refers to the same element in the other container after the swap.
 +
    // Same is true for references.
 +
}
 +
|p={{cpp/container/if unord|{{#var:cont}}|true|}}
 +
|output=
 +
{{#switch:{{#var:cont}}
 +
|map|unordered_map=
 +
──────── before swap ────────
 +
m1: { α:alpha β:beta γ:gamma }
 +
m2: { δ:delta ε:epsilon }
 +
ref: α:alpha
 +
iter: β:beta
 +
──────── after swap ────────
 +
m1: { δ:delta ε:epsilon }
 +
m2: { α:alpha β:beta γ:gamma }
 +
ref: α:alpha
 +
iter: β:beta
 +
|multimap|unordered_multimap=
 +
──────── before swap ────────
 +
m1: { α:alpha β:beta γ:gamma γ:gamma }
 +
m2: { δ:delta ε:epsilon ε:epsilon }
 +
ref: α:alpha
 +
iter: β:beta
 +
──────── after swap ────────
 +
m1: { δ:delta ε:epsilon ε:epsilon }
 +
m2: { α:alpha β:beta γ:gamma γ:gamma }
 +
ref: α:alpha
 +
iter: β:beta
 +
}}
 +
}}
 +
}}
 +
<!---->
 +
{{#switch:{{#var:cont}}
 +
|vector=
 +
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|wg=lwg|dr=341|std=C++98|before=the capacities of {{tt|std::vector}} could not be swapped|after=they are also swapped}}
 +
{{dr list end}}
 +
}}
 +
<!---->
 
===See also===
 
===See also===
−
{{dcl list begin}}
+
{{dsc begin}}
−
{{dcl list template | cpp/container/dcl list swap2 |{{{1|}}}}}
+
{{dsc inc|cpp/container/dsc swap2|{{#var:cont}}}}
−
{{dcl list end}}
+
{{dsc end}}

Latest revision as of 21:51, 16 August 2024

 
C++
 
Containers library
 
std::list
Member functions
Non-member functions
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)
Deduction guides(C++17)
 
void swap( list& other );
 (until C++17)
void swap( list& other ) noexcept(/* see below */);
 (since C++17)

Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements.

All iterators and references remain valid. It is unspecified whether an iterator holding the end() value in this container will refer to this or the other container after the operation.

If std::allocator_traits<allocator_type>::propagate_on_container_swap::value is true, then the allocators are exchanged using an unqualified call to non-member swap. Otherwise, they are not swapped (and if get_allocator() != other.get_allocator(), the behavior is undefined).

(since C++11)

Contents

[edit] Parameters

other - container to exchange the contents with

[edit] Return value

(none)

[edit] Exceptions

(none)

(until C++17)
noexcept specification:  
noexcept(std::allocator_traits<Allocator>::is_always_equal::value)
 (since C++17)

[edit] Complexity

Constant.

[edit] Example

Run this code
#include <iostream>
#include <list>
 
template<class Os, class Co>
Os& operator<<(Os& os, const Co& co)
{
    os << '{';
    for (auto const& i : co)
        os << ' ' << i;
    return os << " } ";
}
 
int main()
{
    std::list<int> a1{1, 2, 3}, a2{4, 5};
 
    auto it1 = std::next(a1.begin());
    auto it2 = std::next(a2.begin());
 
    int& ref1 = a1.front();
    int& ref2 = a2.front();
 
    std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\n';
    a1.swap(a2);
    std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\n';
 
    // Note that after swap the iterators and references stay associated with their
    // original elements, e.g. it1 that pointed to an element in 'a1' with value 2
    // still points to the same element, though this element was moved into 'a2'.
}

Output: 

{ 1 2 3 } { 4 5 } 2 5 1 4
{ 4 5 } { 1 2 3 } 2 5 1 4

[edit] See also

 specializes the std::swap algorithm
(function template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=Template:cpp/container/swap&oldid=175275"