Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | string‎ | basic string
(Added LWG issue #403 DR.)
(Added LWG issue #2151 DR.)
 
(5 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
|until1=c++17|dcl1=
 
|until1=c++17|dcl1=
 
void swap( basic_string& other );
 
void swap( basic_string& other );
−
|until2=c++20|dcl2=
+
|notes2={{mark constexpr since c++20}}|dcl2=
 
void swap( basic_string& other ) noexcept(/* see below */);
 
void swap( basic_string& other ) noexcept(/* see below */);
−
|dcl3=
 
−
constexpr void swap( basic_string& other ) noexcept(/* see below */);
 
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
Line 15: Line 13:
  
 
{{rrev|since=c++11|
 
{{rrev|since=c++11|
−
{{anchor|ub}}
+
If {{c multi|std::allocator_traits<Allocator>::|    propagate_on_container_swap::value &&|get_allocator() {{==}} s.get_allocator()}} is {{c|false}}, the behavior is undefined.
−
The behavior is undefined if {{tt|Allocator}} does not propagate on swap and the allocators of {{c|*this}} and {{c|other}} are unequal.
+
 
}}
 
}}
  
Line 23: Line 20:
 
{{par|other|string to exchange the contents with}}
 
{{par|other|string to exchange the contents with}}
 
{{par end}}
 
{{par end}}
−
 
−
===Return value===
 
−
(none)
 
  
 
===Complexity===
 
===Complexity===
Line 31: Line 25:
  
 
===Exceptions===
 
===Exceptions===
−
No exception is thrown{{rev inl|since=c++11|, except in the case where the behavior is undefined (see [[#ub|above]])}}.
+
{{rev begin}}
 +
{{rev|until=c++11|
 +
No exception is thrown.
 +
}}
 +
{{rev|since=c++11|
 +
No exception is thrown, unless the behavior is undefined.
 +
 
 +
{{cpp/strong exception safety guarantee}}
 +
}}
 +
{{rev end}}
 +
 
  
 
{{rrev|since=c++17|
 
{{rrev|since=c++17|
−
{{noexcept|std::allocator_traits<Allocator>::propagate_on_container_swap::value
+
{{noexcept|std::allocator_traits<Allocator>::propagate_on_container_swap::value {{!!}}
−
{{!!}} std::allocator_traits<Allocator>::is_always_equal::value}}
+
        std::allocator_traits<Allocator>::is_always_equal::value}}
 
}}
 
}}
  
Line 41: Line 45:
 
{{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=
 
|output=
−
before swap
+
Before swap:
−
a: AAA
+
a = AAA
−
b: BBB
+
b = BBBB
−
after swap
+
 
−
a: BBB
+
After swap:
−
b: AAA
+
a = BBBB
 +
b = AAA
 
}}
 
}}
  
Line 71: Line 76:
 
{{dr list begin}}
 
{{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=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}}
 
{{dr list end}}
  

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"