Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/string/basic string/swap"

From cppreference.com
< cpp‎ | string‎ | basic string
(conditionally-noexcept in 17)
(Added LWG issue #2151 DR.)
 
(12 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
{{cpp/string/basic_string/title | swap}}
+
{{cpp/string/basic_string/title|swap}}
 
{{cpp/string/basic_string/navbar}}
 
{{cpp/string/basic_string/navbar}}
−
{{ddcl |  
+
{{dcl begin}}
 +
{{dcl rev multi
 +
|until1=c++17|dcl1=
 
void swap( basic_string& other );
 
void swap( basic_string& other );
 +
|notes2={{mark constexpr since c++20}}|dcl2=
 +
void swap( basic_string& other ) noexcept(/* see below */);
 
}}
 
}}
 +
{{dcl end}}
  
−
Exchanges the contents of the string with those of {{tt|other}}. All iterators and references may be invalidated.
+
Exchanges the contents of the string with those of {{c|other}}. All iterators and references may be invalidated.
 +
 
 +
{{rrev|since=c++11|
 +
If {{c multi|std::allocator_traits<Allocator>::|    propagate_on_container_swap::value &&|get_allocator() {{==}} s.get_allocator()}} is {{c|false}}, the behavior is undefined.
 +
}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | other | string to exchange the contents with}}
+
{{par|other|string to exchange the contents with}}
 
{{par end}}
 
{{par end}}
  
−
===Return value===
+
===Complexity===
−
(none)
+
Constant.
  
 
===Exceptions===
 
===Exceptions===
 
{{rev begin}}
 
{{rev begin}}
−
{{rev|since=c++17|
+
{{rev|until=c++11|
−
{{noexcept|std::allocator_traits<Allocator>::propagate_on_container_swap::value
+
No exception is thrown.
−
{{!!}} std::allocator_traits<Allocator>::is_always_equal::value}}
+
}}
 +
{{rev|since=c++11|
 +
No exception is thrown, unless the behavior is undefined.
 +
 
 +
{{cpp/strong exception safety guarantee}}
 
}}
 
}}
 
{{rev end}}
 
{{rev end}}
 +
 +
 +
{{rrev|since=c++17|
 +
{{noexcept|std::allocator_traits<Allocator>::propagate_on_container_swap::value {{!!}}
 +
        std::allocator_traits<Allocator>::is_always_equal::value}}
 +
}}
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
| code=
+
|code=
−
#include <string>
+
 
#include <iostream>
 
#include <iostream>
 +
#include <string>
  
 
int main()  
 
int main()  
 
{
 
{
 
     std::string a = "AAA";
 
     std::string a = "AAA";
−
     std::string b = "BBB";
+
     std::string b = "BBBB";
−
 
+
   
−
     std::cout << "before swap" << '\n';
+
     std::cout << "Before swap:\n"
−
    std::cout << "a: " << a << '\n';
+
                "a = " << a << "\n"
−
    std::cout << "b: " << b << '\n';
+
                "b = " << b << "\n\n";
−
 
+
   
 
     a.swap(b);
 
     a.swap(b);
−
 
+
   
−
     std::cout << "after swap" << '\n';
+
     std::cout << "After swap:\n"
−
    std::cout << "a: " << a << '\n';
+
                "a = " << a << "\n"
−
    std::cout << "b: " << b << '\n';
+
                "b = " << b << '\n';
 
}
 
}
 +
|output=
 +
Before swap:
 +
a = AAA
 +
b = BBBB
  
−
| output=
+
After swap:
−
before swap
+
a = BBBB
−
a: AAA
+
b = AAA
−
b: BBB
+
−
after swap
+
−
a: BBB
+
−
b: AAA
+
 
}}
 
}}
  
−
===Complexity===
+
===Defect reports===
−
Constant.
+
{{dr list begin}}
 +
{{dr list item|wg=lwg|dr=403|std=C++98|before={{tt|swap()}} might throw an exception|after=no exception is thrown}}
 +
{{dr list item|wg=lwg|dr=535|std=C++98|before=swapping strings did not preserve the character orders|after=orders are also preserved}}
 +
{{dr list item|wg=lwg|dr=2151|paper=P1148R0|std=C++11|before=no exception was thrown in the case<br>of unequal non-propagating allocators|after=the behavior is<br>undefined in this case}}
 +
{{dr list end}}
 +
 
 +
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/algorithm/dsc swap}}
 +
{{dsc inc|cpp/algorithm/dsc swap_ranges}}
 +
{{dsc inc|cpp/string/basic_string_view/dsc {{SUBPAGENAMEE}}}}
 +
{{dsc end}}
  
−
[[de:cpp/string/basic string/swap]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/string/basic string/swap]]
+
−
[[fr:cpp/string/basic string/swap]]
+
−
[[it:cpp/string/basic string/swap]]
+
−
[[ja:cpp/string/basic string/swap]]
+
−
[[pt:cpp/string/basic string/swap]]
+
−
[[ru:cpp/string/basic string/swap]]
+
−
[[zh:cpp/string/basic string/swap]]
+

Latest revision as of 22:55, 15 October 2024

 
C++
 
Strings library
 
std::basic_string
Member functions
(C++23)
Element access
(DR*)
(DR*)
(C++17)
Iterators
(C++11)
(C++11)
(C++11)
(C++11)
Capacity
(DR*)
Modifiers
(C++23)
(DR*)
(C++23)
(C++23)
(C++23)  
basic_string::swap
Search
Operations
(C++20)
(C++20)
(C++23)
Constants
Non-member functions
(C++20)(C++20)
I/O
Comparison
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Numeric conversions
(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)
(C++11)
(C++11)
Literals
(C++14)
Helper classes
(C++11)
Deduction guides (C++17)

 
void swap( basic_string& other );
 (until C++17)
void swap( basic_string& other ) noexcept(/* see below */);
 (since C++17)
(constexpr since C++20)

Exchanges the contents of the string with those of other. All iterators and references may be invalidated.

If std::allocator_traits<Allocator>::
    propagate_on_container_swap::value &&
get_allocator() == s.get_allocator() is false, the behavior is undefined.

(since C++11)

Contents

[edit] Parameters

other - string to exchange the contents with

[edit] Complexity

Constant.

[edit] Exceptions

No exception is thrown.

(until C++11)

No exception is thrown, unless the behavior is undefined.

If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).

(since C++11)


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

[edit] Example

Run this code
#include <iostream>
#include <string>
 
int main() 
{
    std::string a = "AAA";
    std::string b = "BBBB";
 
    std::cout << "Before swap:\n"
                 "a = " << a << "\n"
                 "b = " << b << "\n\n";
 
    a.swap(b);
 
    std::cout << "After swap:\n"
                 "a = " << a << "\n"
                 "b = " << b << '\n';
}

Output: 

Before swap:
a = AAA
b = BBBB
 
After swap:
a = BBBB
b = AAA

[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 403 C++98 swap() might throw an exception no exception is thrown
LWG 535 C++98 swapping strings did not preserve the character orders orders are also preserved
LWG 2151
(P1148R0) 		C++11 no exception was thrown in the case
of unequal non-propagating allocators 		the behavior is
undefined in this case

[edit] See also

 swaps the values of two objects
(function template) [edit]
swaps two ranges of elements
(function template) [edit]
swaps the contents
(public member function of std::basic_string_view<CharT,Traits>) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/swap&oldid=177085"