Namespaces
Variants
Views
Actions

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

From cppreference.com
m (revbox the POCS rules)
m (Added {{#var:cont}} to simplify page testing.)
 
(29 intermediate revisions by 7 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}}
 +
{{cpp/container/{{#var:cont}}/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl | since={{cpp/std|{{{1|}}}}} |
+
{{#switch:{{#var:cont}}
−
void swap( {{{1}}}& other );
+
|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}}
 
{{dcl end}}
  
−
Exchanges the contents of the container with those of {{tt|other}}. Does not invoke any move, copy, or swap operations on individual elements.
+
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.
  
−
{{cpp/container/note iterator invalidation|{{{1|}}}|swap}}
+
{{cpp/container/note iterator invalidation|{{#var:cont}}|swap}}
−
 
+
<!---->
−
{{#switch:{{{1|}}}
+
{{#switch:{{#var:cont}}
−
|map | set | multimap | multiset=The {{tt|Pred}} objects must be {{concept|Swappable}}, and they are exchanged using unqualified call to non-member {{tt|swap}}.
+
|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 {{concept|Swappable}}, and they are exchanged using unqualified calls 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}}.
 
}}
 
}}
−
{{rev inl|since=c++11|
+
{{rrev|since=c++11|
−
If {{c|std::allocator_traits<allocator_type>::propagate_on_container_swap::value}} is 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).}}
+
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===
 
{{par begin}}
 
{{par begin}}
−
{{par | other | container to exchange the contents with}}
+
{{par|other|container to exchange the contents with}}
 
{{par end}}
 
{{par end}}
  
Line 27: Line 43:
  
 
===Exceptions===
 
===Exceptions===
−
{{#switch:{{{1|}}}
+
{{rrev multi|until1=c++17
−
|map | set | multimap | multiset=Any exception thrown by the swap of the {{tt|Compare}} objects.
+
|rev1=
−
|unordered_map | unordered_set | unordered_multimap| unordered_multiset=Any exception thrown by the swap {{tt|Hash}} or {{tt|KeyEqual}} objects.
+
{{#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)
 
|(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}}
 +
}}
 
}}
 
}}
  
Line 36: Line 70:
 
Constant.
 
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===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/container/dsc swap2 |{{{1|}}}}}
+
{{dsc inc|cpp/container/dsc swap2|{{#var:cont}}}}
 
{{dsc 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"