Difference between revisions of "cpp/algorithm/replace"
m (Text replace - "<!-- ======== --> " to "") |
m (FTM.) |
||
(45 intermediate revisions by 11 users not shown) | |||
Line 1: | Line 1: | ||
− | {{cpp/title|replace | replace_if}} | + | {{cpp/title|replace|replace_if}} |
− | {{cpp/algorithm/ | + | {{cpp/algorithm/navbar}} |
− | {{ | + | {{dcl begin}} |
− | {{ | + | {{dcl header|algorithm}} |
− | {{ | + | {{dcl rev begin|num=1}} |
− | template< class | + | {{dcla|anchor=1|constexpr=c++20|until=c++26| |
− | void replace( | + | template< class ForwardIt, class T > |
+ | void replace( ForwardIt first, ForwardIt last, | ||
const T& old_value, const T& new_value ); | const T& old_value, const T& new_value ); | ||
}} | }} | ||
− | {{ | + | {{dcl|since=c++26|1= |
− | template< class | + | template< class ForwardIt, class T = typename std::iterator_traits |
− | void | + | <ForwardIt>::value_type > |
− | + | constexpr void replace( ForwardIt first, ForwardIt last, | |
+ | const T& old_value, const T& new_value ); | ||
}} | }} | ||
− | {{ | + | {{dcl rev end}} |
+ | {{dcl rev begin|num=2}} | ||
+ | {{dcl|since=c++17|until=c++26| | ||
+ | template< class ExecutionPolicy, class ForwardIt, class T > | ||
+ | void replace( ExecutionPolicy&& policy, | ||
+ | ForwardIt first, ForwardIt last, | ||
+ | const T& old_value, const T& new_value ); | ||
+ | }} | ||
+ | {{dcl|since=c++26|1= | ||
+ | template< class ExecutionPolicy, class ForwardIt, | ||
+ | class T = typename std::iterator_traits | ||
+ | <ForwardIt>::value_type > | ||
+ | void replace( ExecutionPolicy&& policy, | ||
+ | ForwardIt first, ForwardIt last, | ||
+ | const T& old_value, const T& new_value ); | ||
+ | }} | ||
+ | {{dcl rev end}} | ||
+ | {{dcl rev begin|num=3}} | ||
+ | {{dcla|anchor=3|constexpr=c++20|until=c++26| | ||
+ | template< class ForwardIt, class UnaryPred, class T > | ||
+ | void replace_if( ForwardIt first, ForwardIt last, | ||
+ | UnaryPred p, const T& new_value ); | ||
+ | }} | ||
+ | {{dcl|since=c++26|1= | ||
+ | template< class ForwardIt, class UnaryPred, | ||
+ | class T = typename std::iterator_traits | ||
+ | <ForwardIt>::value_type> > | ||
+ | constexpr void replace_if( ForwardIt first, ForwardIt last, | ||
+ | UnaryPred p, const T& new_value ); | ||
+ | }} | ||
+ | {{dcl rev end}} | ||
+ | {{dcl rev begin|num=4}} | ||
+ | {{dcl|since=c++17|until=c++26| | ||
+ | template< class ExecutionPolicy, | ||
+ | class ForwardIt, class UnaryPred, class T > | ||
+ | void replace_if( ExecutionPolicy&& policy, | ||
+ | ForwardIt first, ForwardIt last, | ||
+ | UnaryPred p, const T& new_value ); | ||
+ | }} | ||
+ | {{dcl|since=c++26|1= | ||
+ | template< class ExecutionPolicy, | ||
+ | class ForwardIt, class UnaryPred, | ||
+ | class T = typename std::iterator_traits | ||
+ | <ForwardIt>::value_type> > | ||
+ | void replace_if( ExecutionPolicy&& policy, | ||
+ | ForwardIt first, ForwardIt last, | ||
+ | UnaryPred p, const T& new_value ); | ||
+ | }} | ||
+ | {{dcl end}} | ||
+ | |||
+ | Replaces all elements in the range {{range|first|last}} with {{c|new_value}} if they satisfy specific criteria. | ||
+ | |||
+ | @1@ Replaces all elements that are equal to {{c|old_value}} (using {{c/core|1=operator==}}). | ||
+ | |||
+ | @3@ Replaces all elements for which predicate {{c|p}} returns {{c|true}}. | ||
+ | |||
+ | @2,4@ Same as {{v|1,3}}, but executed according to {{c|policy}}. | ||
+ | @@ {{cpp/algorithm/parallel overload precondition|plural=yes}} | ||
− | + | If {{rev inl|until=c++20|{{c|1=*first = new_value}} is invalid}}{{rev inl|since=c++20|{{c|new_value}} is not [[cpp/iterator#Types and writability|writable]] to {{c|first}}}}, the program is ill-formed. | |
===Parameters=== | ===Parameters=== | ||
− | {{ | + | {{par begin}} |
− | {{ | + | {{par|first, last|the range of elements to process}} |
− | {{ | + | {{par|old_value|the value of elements to replace}} |
− | {{ | + | {{par exec pol}} |
− | {{ | + | {{par pred1|p|if the element value should be replaced|p1=ForwardIt}} |
− | {{ | + | {{par|new_value|the value to use as replacement}} |
+ | {{par hreq}} | ||
+ | {{par req named|ForwardIt|ForwardIterator}} | ||
+ | {{par req named|UnaryPred|Predicate}} | ||
+ | {{par end}} | ||
===Return value=== | ===Return value=== | ||
− | + | (none) | |
===Complexity=== | ===Complexity=== | ||
+ | Given {{mathjax-or|\(\scriptsize N\)|N}} as {{c|std::distance(first, last)}}: | ||
+ | @1,2@ Exactly {{mathjax-or|\(\scriptsize N\)|N}} comparisons using {{c/core|1=operator==}}. | ||
+ | @3,4@ Exactly {{mathjax-or|\(\scriptsize N\)|N}} applications of the predicate {{c|p}}. | ||
− | + | ===Exceptions=== | |
+ | {{cpp/algorithm/parallel exceptions reporting behavior|singular=no}} | ||
− | === | + | ===Notes=== |
− | {{ | + | Because the algorithm takes {{c|old_value}} and {{c|new_value}} by reference, it can have unexpected behavior if either is a reference to an element of the range {{range|first|last}}. |
− | + | ||
− | template<class | + | {{feature test macro|__cpp_lib_algorithm_default_value_type|value=202403|std=C++26|[[cpp/language/list initialization|List-initialization]] for algorithms {{vl|1-4}}}} |
− | void replace( | + | |
+ | ===Possible implementation=== | ||
+ | {{eq impl | ||
+ | |title1=replace|ver1=1|1= | ||
+ | template<class ForwardIt, | ||
+ | class T = typename std::iterator_traits<ForwardIt>::value_type> | ||
+ | void replace(ForwardIt first, ForwardIt last, | ||
const T& old_value, const T& new_value) | const T& old_value, const T& new_value) | ||
{ | { | ||
− | for (; first != last; ++first) | + | for (; first != last; ++first) |
− | if (*first == old_value) | + | if (*first == old_value) |
*first = new_value; | *first = new_value; | ||
− | |||
− | |||
} | } | ||
− | + | |title2=replace_if|ver2=3|2= | |
− | template<class | + | template<class ForwardIt, class UnaryPred, |
− | void replace_if( | + | class T = typename std::iterator_traits<ForwardIt>::value_type> |
− | + | void replace_if(ForwardIt first, ForwardIt last, | |
+ | UnaryPred p, const T& new_value) | ||
{ | { | ||
− | for (; first != last; ++first) | + | for (; first != last; ++first) |
− | if(p(*first)) | + | if (p(*first)) |
*first = new_value; | *first = new_value; | ||
− | |||
− | |||
} | } | ||
}} | }} | ||
===Example=== | ===Example=== | ||
− | {{example | + | {{example |
− | + | |code= | |
− | + | ||
#include <algorithm> | #include <algorithm> | ||
#include <array> | #include <array> | ||
− | #include < | + | #include <complex> |
#include <functional> | #include <functional> | ||
+ | #include <iostream> | ||
+ | |||
+ | void println(const auto& seq) | ||
+ | { | ||
+ | for (const auto& e : seq) | ||
+ | std::cout << e << ' '; | ||
+ | std::cout << '\n'; | ||
+ | } | ||
int main() | int main() | ||
{ | { | ||
− | std::array<int> s{5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; | + | std::array<int, 10> s{5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; |
+ | |||
+ | // Replace all occurrences of 8 with 88. | ||
+ | std::replace(s.begin(), s.end(), 8, 88); | ||
+ | println(s); | ||
− | std:: | + | // Replace all values less than 5 with 55. |
+ | std::replace_if(s.begin(), s.end(), | ||
+ | std::bind(std::less<int>(), std::placeholders::_1, 5), 55); | ||
+ | println(s); | ||
− | + | std::array<std::complex<double>, 2> nums{<!---->{<!---->{1, 3}, {1, 3}<!---->}<!---->}; | |
− | + | #ifdef __cpp_lib_algorithm_default_value_type | |
− | + | std::replace(nums.begin(), nums.end(), {1, 3}, {4, 2}); | |
− | + | #else | |
− | + | std::replace(nums.begin(), nums.end(), std::complex<double>{1, 3}, | |
− | std:: | + | std::complex<double>{4, 2}); |
− | + | #endif | |
− | + | println(nums); | |
− | + | ||
− | + | ||
− | + | ||
} | } | ||
− | + | |output= | |
− | 5 7 4 2 | + | 5 7 4 2 88 6 1 9 0 3 |
− | 5 7 | + | 5 7 55 55 88 6 55 9 55 55 |
+ | (4,2), (4,2) | ||
}} | }} | ||
+ | |||
+ | ===Defect reports=== | ||
+ | {{dr list begin}} | ||
+ | {{dr list item|wg=lwg|dr=283|std=C++98|before={{tt|T}} was required to be {{named req|CopyAssignable}} (and {{named req|EqualityComparable}}<br>for {{tt|replace}}), but the value type of {{tt|ForwardIt}} is not<br>always {{tt|T}} and {{tt|T}} is not always writable to {{tt|ForwardIt}}|after=required {{c|1=*first = new_value}}<br>to be valid instead}} | ||
+ | {{dr list end}} | ||
===See also=== | ===See also=== | ||
− | {{ | + | {{dsc begin}} |
− | {{ | + | {{dsc inc|cpp/algorithm/dsc replace_copy}} |
− | {{ | + | {{dsc inc|cpp/algorithm/ranges/dsc replace}} |
+ | {{dsc end}} | ||
+ | |||
+ | {{langlinks|de|es|fr|it|ja|pt|ru|zh}} |
Latest revision as of 21:20, 20 May 2024
Defined in header <algorithm>
|
||
(1) | ||
template< class ForwardIt, class T > void replace( ForwardIt first, ForwardIt last, |
(constexpr since C++20) (until C++26) |
|
template< class ForwardIt, class T = typename std::iterator_traits <ForwardIt>::value_type > |
(since C++26) | |
(2) | ||
template< class ExecutionPolicy, class ForwardIt, class T > void replace( ExecutionPolicy&& policy, |
(since C++17) (until C++26) |
|
template< class ExecutionPolicy, class ForwardIt, class T = typename std::iterator_traits |
(since C++26) | |
(3) | ||
template< class ForwardIt, class UnaryPred, class T > void replace_if( ForwardIt first, ForwardIt last, |
(constexpr since C++20) (until C++26) |
|
template< class ForwardIt, class UnaryPred, class T = typename std::iterator_traits |
(since C++26) | |
(4) | ||
template< class ExecutionPolicy, class ForwardIt, class UnaryPred, class T > |
(since C++17) (until C++26) |
|
template< class ExecutionPolicy, class ForwardIt, class UnaryPred, |
(since C++26) | |
Replaces all elements in the range [
first,
last)
with new_value if they satisfy specific criteria.
std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true. |
(until C++20) |
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> is true. |
(since C++20) |
If *first = new_value is invalid(until C++20)new_value is not writable to first(since C++20), the program is ill-formed.
Contents |
[edit] Parameters
first, last | - | the range of elements to process |
old_value | - | the value of elements to replace |
policy | - | the execution policy to use. See execution policy for details. |
p | - | unary predicate which returns true if the element value should be replaced. The expression p(v) must be convertible to bool for every argument |
new_value | - | the value to use as replacement |
Type requirements | ||
-ForwardIt must meet the requirements of LegacyForwardIterator.
| ||
-UnaryPred must meet the requirements of Predicate.
|
[edit] Return value
(none)
[edit] Complexity
Given N as std::distance(first, last):
[edit] Exceptions
The overloads with a template parameter named ExecutionPolicy
report errors as follows:
- If execution of a function invoked as part of the algorithm throws an exception and
ExecutionPolicy
is one of the standard policies, std::terminate is called. For any otherExecutionPolicy
, the behavior is implementation-defined. - If the algorithm fails to allocate memory, std::bad_alloc is thrown.
[edit] Notes
Because the algorithm takes old_value and new_value by reference, it can have unexpected behavior if either is a reference to an element of the range [
first,
last)
.
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_lib_algorithm_default_value_type |
202403 | (C++26) | List-initialization for algorithms (1-4) |
[edit] Possible implementation
replace |
---|
template<class ForwardIt, class T = typename std::iterator_traits<ForwardIt>::value_type> void replace(ForwardIt first, ForwardIt last, const T& old_value, const T& new_value) { for (; first != last; ++first) if (*first == old_value) *first = new_value; } |
replace_if |
template<class ForwardIt, class UnaryPred, class T = typename std::iterator_traits<ForwardIt>::value_type> void replace_if(ForwardIt first, ForwardIt last, UnaryPred p, const T& new_value) { for (; first != last; ++first) if (p(*first)) *first = new_value; } |
[edit] Example
#include <algorithm> #include <array> #include <complex> #include <functional> #include <iostream> void println(const auto& seq) { for (const auto& e : seq) std::cout << e << ' '; std::cout << '\n'; } int main() { std::array<int, 10> s{5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; // Replace all occurrences of 8 with 88. std::replace(s.begin(), s.end(), 8, 88); println(s); // Replace all values less than 5 with 55. std::replace_if(s.begin(), s.end(), std::bind(std::less<int>(), std::placeholders::_1, 5), 55); println(s); std::array<std::complex<double>, 2> nums{{{1, 3}, {1, 3}}}; #ifdef __cpp_lib_algorithm_default_value_type std::replace(nums.begin(), nums.end(), {1, 3}, {4, 2}); #else std::replace(nums.begin(), nums.end(), std::complex<double>{1, 3}, std::complex<double>{4, 2}); #endif println(nums); }
Output:
5 7 4 2 88 6 1 9 0 3 5 7 55 55 88 6 55 9 55 55 (4,2), (4,2)
[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 283 | C++98 | T was required to be CopyAssignable (and EqualityComparablefor replace ), but the value type of ForwardIt is notalways T and T is not always writable to ForwardIt
|
required *first = new_value to be valid instead |
[edit] See also
copies a range, replacing elements satisfying specific criteria with another value (function template) | |
(C++20)(C++20) |
replaces all values satisfying specific criteria with another value (niebloid) |