std:: transform

From cppreference.net

Défini dans l'en-tête `<algorithm>`
template < class InputIt, class OutputIt, class UnaryOp > OutputIt transform ( InputIt first1, InputIt last1, OutputIt d_first, UnaryOp unary_op ) ;	(1)	(constexpr depuis 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)	(depuis 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 depuis 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)	(depuis C++17)

std::transform applique la fonction donnée aux éléments de la/des plage(s) d'entrée spécifiée(s), et stocke le résultat dans une plage de sortie commençant à d_first .

1) L'opération unaire unary_op est appliquée aux éléments de

first1

last1

Si unary_op invalide un itérateur ou modifie un élément dans l'une des plages suivantes, le comportement est indéfini :

[ first1 , last1 ] .
La plage de std:: distance ( first1, last1 ) + 1 éléments commençant à partir de d_first .

3) L'opération binaire binary_op est appliquée à des paires d'éléments provenant de deux plages :

first1

last1

et une autre plage de std:: distance ( first1, last1 ) éléments commençant à first2 .

Si binary_op invalide un itérateur ou modifie un élément dans l'une des plages suivantes, le comportement est indéfini :

[ first1 , last1 ] .
La plage de std:: distance ( first1, last1 ) + 1 éléments commençant à first2 .
La plage de std:: distance ( first1, last1 ) + 1 éléments commençant à d_first .

2,4) Identique à (1,3) , mais exécuté selon la policy .

Ces surcharges participent à la résolution de surcharge seulement si toutes les conditions suivantes sont satisfaites :

std:: is_execution_policy_v < std:: decay_t < ExecutionPolicy >> est true .	(jusqu'à C++20)
std:: is_execution_policy_v < std:: remove_cvref_t < ExecutionPolicy >> est true .	(depuis C++20)

Table des matières

Paramètres

first1, last1	-	la paire d'itérateurs définissant la plage source des éléments à transformer
first2	-	le début de la deuxième plage d'éléments à transformer, ( 3,4 ) uniquement
d_first	-	le début de la plage de destination, peut être égal à first1 ou first2
policy	-	la politique d'exécution à utiliser
unary_op	-	objet de fonction d'opération unaire qui sera appliqué. La signature de la fonction doit être équivalente à : Ret fun ( const Type & a ) ; La signature n'a pas besoin d'avoir const & . Le type Type doit être tel qu'un objet de type InputIt puisse être déréférencé puis implicitement converti en Type . Le type Ret doit être tel qu'un objet de type OutputIt puisse être déréférencé et se voir assigner une valeur de type Ret .
binary_op	-	objet de fonction d'opération binaire qui sera appliqué. La signature de la fonction doit être équivalente à : Ret fun ( const Type1 & a, const Type2 & b ) ; La signature n'a pas besoin d'avoir const & . Les types Type1 et Type2 doivent être tels que les objets de types InputIt1 et InputIt2 puissent être déréférencés puis implicitement convertis en Type1 et Type2 respectivement. Le type Ret doit être tel qu'un objet de type OutputIt puisse être déréférencé et se voir assigner une valeur de type Ret .
Exigences de type
- `InputIt, InputIt1, InputIt2` doivent satisfaire aux exigences de LegacyInputIterator .
- `OutputIt` doit satisfaire aux exigences de LegacyOutputIterator .
- `ForwardIt1, ForwardIt2, ForwardIt3` doivent satisfaire aux exigences de LegacyForwardIterator .

Valeur de retour

Itérateur de sortie vers l'élément qui suit le dernier élément transformé.

Complexité

Étant donné $\scriptsize N$ $N$ comme std:: distance ( first1, last1 ) :

1,2) Exactement

N

applications de unary_op .

3,4) Exactement

N

applications de binary_op .

Exceptions

Les surcharges avec un paramètre de modèle nommé ExecutionPolicy signalent les erreurs comme suit :

Si l'exécution d'une fonction invoquée dans le cadre de l'algorithme lève une exception et que ExecutionPolicy fait partie des politiques standard , std::terminate est appelé. Pour tout autre ExecutionPolicy , le comportement est défini par l'implémentation.
Si l'algorithme ne parvient pas à allouer de la mémoire, std::bad_alloc est levé.

Implémentation possible

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;
}

Notes

std::transform ne garantit pas l'application dans l'ordre de unary_op ou binary_op . Pour appliquer une fonction à une séquence dans l'ordre ou pour appliquer une fonction qui modifie les éléments d'une séquence, utilisez std::for_each .

Exemple

Exécuter ce code

#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)
{
    // Transformer la chaîne en majuscules en place
    std::transform(hello.cbegin(), hello.cend(), hello.begin(), to_uppercase);
    std::cout << "hello = " << std::quoted(hello) << '\n';
    // Version for_each (voir Notes ci-dessus)
    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)
{
    // Transformer les nombres en valeurs doublées
    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));
}

Sortie :

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

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

DR	S'applique à	Comportement tel que publié	Comportement correct
LWG 242	C++98	unary_op et binary_op ne pouvaient pas avoir d'effets secondaires	ils ne peuvent pas modifier les plages impliquées

Voir aussi

for_each	applique un objet fonction unaire aux éléments d'un intervalle (modèle de fonction)
ranges::transform (C++20)	applique une fonction à un intervalle d'éléments (objet fonction d'algorithme)

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