std:: transform

From cppreference.net

Definiert im Header `<algorithm>`
template < class InputIt, class OutputIt, class UnaryOp > OutputIt transform ( InputIt first1, InputIt last1, OutputIt d_first, UnaryOp unary_op ) ;	(1)	(constexpr seit C++20)
template < class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class UnaryOp > ForwardIt2 transform ( ExecutionPolicy && policy, ForwardIt1 first1, ForwardIt1 last1, ForwardIt2 d_first, UnaryOp unary_op ) ;	(2)	(seit C++17)
template < class InputIt1, class InputIt2, class OutputIt, class BinaryOp > OutputIt transform ( InputIt1 first1, InputIt1 last1, InputIt2 first2, OutputIt d_first, BinaryOp binary_op ) ;	(3)	(constexpr seit C++20)
template < class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class ForwardIt3, class BinaryOp > ForwardIt3 transform ( ExecutionPolicy && policy, ForwardIt1 first1, ForwardIt1 last1, ForwardIt2 first2, ForwardIt3 d_first, BinaryOp binary_op ) ;	(4)	(seit C++17)

std::transform wendet die gegebene Funktion auf die Elemente des gegebenen Eingabebereichs (oder der Bereiche) an und speichert das Ergebnis in einem Ausgabebereich, beginnend bei d_first .

1) Die unäre Operation unary_op wird auf die Elemente von

first1

last1

angewendet.

Falls unary_op einen Iterator ungültig macht oder ein Element in einem der folgenden Bereiche modifiziert, ist das Verhalten undefiniert:

[ first1 , last1 ] .
Der Bereich von std:: distance ( first1, last1 ) + 1 Elementen beginnend bei d_first .

3) Die binäre Operation binary_op wird auf Elementpaare aus zwei Bereichen angewendet:

first1

last1

und einem weiteren Bereich von std:: distance ( first1, last1 ) Elementen beginnend bei first2 .

Falls binary_op einen Iterator ungültig macht oder ein Element in einem der folgenden Bereiche modifiziert, ist das Verhalten undefiniert:

[ first1 , last1 ] .
Der Bereich von std:: distance ( first1, last1 ) + 1 Elementen beginnend bei first2 .
Der Bereich von std:: distance ( first1, last1 ) + 1 Elementen beginnend bei d_first .

2,4) Gleich wie (1,3) , aber ausgeführt gemäß policy .

Diese Überladungen nehmen nur dann an der Überladungsauflösung teil, wenn alle folgenden Bedingungen erfüllt sind:

std:: is_execution_policy_v < std:: decay_t < ExecutionPolicy >> ist true .	(bis C++20)
std:: is_execution_policy_v < std:: remove_cvref_t < ExecutionPolicy >> ist true .	(seit C++20)

Inhaltsverzeichnis

Parameter

first1, last1	-	das Iteratorpaar, das den Quell- Bereich der zu transformierenden Elemente definiert
first2	-	der Beginn des zweiten Bereichs der zu transformierenden Elemente, ( 3,4 ) nur
d_first	-	der Beginn des Zielbereichs, kann gleich first1 oder first2 sein
policy	-	die zu verwendende Ausführungsrichtlinie
unary_op	-	unäres Funktionsobjekt, das angewendet wird. Die Signatur der Funktion sollte äquivalent zu Folgendem sein: Ret fun ( const Type & a ) ; Die Signatur muss nicht const & haben. Der Typ Type muss so beschaffen sein, dass ein Objekt vom Typ InputIt dereferenziert und dann implizit in Type konvertiert werden kann. Der Typ Ret muss so beschaffen sein, dass ein Objekt vom Typ OutputIt dereferenziert und ein Wert vom Typ Ret zugewiesen werden kann.
binary_op	-	binäres Funktionsobjekt, das angewendet wird. Die Signatur der Funktion sollte äquivalent zu Folgendem sein: Ret fun ( const Type1 & a, const Type2 & b ) ; Die Signatur muss nicht const & haben. Die Typen Type1 und Type2 müssen so beschaffen sein, dass Objekte der Typen InputIt1 und InputIt2 dereferenziert und dann implizit in Type1 bzw. Type2 konvertiert werden können. Der Typ Ret muss so beschaffen sein, dass ein Objekt vom Typ OutputIt dereferenziert und ein Wert vom Typ Ret zugewiesen werden kann.
Typanforderungen
- `InputIt, InputIt1, InputIt2` müssen die Anforderungen von LegacyInputIterator erfüllen.
- `OutputIt` müssen die Anforderungen von LegacyOutputIterator erfüllen.
- `ForwardIt1, ForwardIt2, ForwardIt3` müssen die Anforderungen von LegacyForwardIterator erfüllen.

Rückgabewert

Ausgabeiterator auf das Element, das auf das letzte transformierte Element folgt.

Komplexität

Gegeben $\scriptsize N$ $N$ als std:: distance ( first1, last1 ) :

1,2) Genau

N

Anwendungen von unary_op .

3,4) Genau

N

Anwendungen von binary_op .

Exceptions

Die Überladungen mit einem Template-Parameter namens ExecutionPolicy melden Fehler wie folgt:

Wenn die Ausführung einer als Teil des Algorithmus aufgerufenen Funktion eine Exception wirft und ExecutionPolicy einer der Standard-Policies ist, wird std::terminate aufgerufen. Für jede andere ExecutionPolicy ist das Verhalten implementierungsdefiniert.
Wenn der Algorithmus keinen Speicher allokieren kann, wird std::bad_alloc geworfen.

Mögliche Implementierung

transform (1)

template<class InputIt, class OutputIt, class UnaryOp>
constexpr //< since C++20
OutputIt transform(InputIt first1, InputIt last1,
                   OutputIt d_first, UnaryOp unary_op)
{
    for (; first1 != last1; ++d_first, ++first1)
        *d_first = unary_op(*first1);
    return d_first;
}

transform (3)

template<class InputIt1, class InputIt2, 
         class OutputIt, class BinaryOp>
constexpr //< since C++20
OutputIt transform(InputIt1 first1, InputIt1 last1, InputIt2 first2,
                   OutputIt d_first, BinaryOp binary_op)
{
    for (; first1 != last1; ++d_first, ++first1, ++first2)
        *d_first = binary_op(*first1, *first2);
    return d_first;
}

Hinweise

std::transform garantiert keine geordnete Anwendung von unary_op oder binary_op . Um eine Funktion geordnet auf eine Sequenz anzuwenden oder eine Funktion zu verwenden, die Elemente einer Sequenz verändert, verwenden Sie std::for_each .

Beispiel

Diesen Code ausführen

#include <algorithm>
#include <cctype>
#include <iomanip>
#include <iostream>
#include <string>
#include <utility>
#include <vector>
void print_ordinals(const std::vector<unsigned>& ordinals)
{
    std::cout << "ordinals: ";
    for (unsigned ord : ordinals)
        std::cout << std::setw(3) << ord << ' ';
    std::cout << '\n';
}
char to_uppercase(unsigned char c)
{
    return std::toupper(c);
}
void to_uppercase_inplace(char& c)
{
    c = to_uppercase(c);
}
void unary_transform_example(std::string& hello, std::string world)
{
    // Zeichenkette in-place in Großbuchstaben umwandeln
    std::transform(hello.cbegin(), hello.cend(), hello.begin(), to_uppercase);
    std::cout << "hello = " << std::quoted(hello) << '\n';
    // for_each-Version (siehe Hinweise oben)
    std::for_each(world.begin(), world.end(), to_uppercase_inplace);
    std::cout << "world = " << std::quoted(world) << '\n';
}
void binary_transform_example(std::vector<unsigned> ordinals)
{
    // Zahlen in verdoppelte Werte umwandeln
    print_ordinals(ordinals);
    std::transform(ordinals.cbegin(), ordinals.cend(), ordinals.cbegin(),
                   ordinals.begin(), std::plus<>{});
    print_ordinals(ordinals);
}
int main()
{
    std::string hello("hello");
    unary_transform_example(hello, "world");
    std::vector<unsigned> ordinals;
    std::copy(hello.cbegin(), hello.cend(), std::back_inserter(ordinals));
    binary_transform_example(std::move(ordinals));
}

Ausgabe:

hello = "HELLO"
world = "WORLD"
ordinals:  72  69  76  76  79 
ordinals: 144 138 152 152 158

Fehlerberichte

Die folgenden verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR	Angewendet auf	Verhalten wie veröffentlicht	Korrektes Verhalten
LWG 242	C++98	unary_op und binary_op durften keine Nebeneffekte haben	sie können die beteiligten Bereiche nicht modifizieren

Siehe auch

for_each	wendet ein unäres Funktionsobjekt auf Elemente eines Bereichs an (Funktions-Template)
ranges::transform (C++20)	wendet eine Funktion auf einen Elementbereich an (Algorithmus-Funktionsobjekt)

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Diagnostics library
Memory management library
Metaprogramming library (C++11)
General utilities library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.net

Namespaces

Variants