std::transform

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 ou des plages d'entrée données, 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 d'éléments std::distance(first1, last1) + 1 commençant à d_first.

3) L'opération binaire binary_op est appliquée à des paires d'éléments de deux plages : [first1, last1) et une autre plage d'éléments std::distance(first1, last1) 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 d'éléments std::distance(first1, last1) + 1 commençant à first2.
La plage d'éléments std::distance(first1, last1) + 1 commençant à d_first.

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

Ces surcharges ne participent à la résolution de surcharge que si la valeur de l'expression suivante est true :

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

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 unaire objet fonction aux éléments d'une plage (modèle de fonction & objet fonction d'algorithme)
ranges::for_each (C++20)
ranges::transform (C++20)	applique une fonction à une plage d'éléments (objet fonction d'algorithme)

Support du compilateur
Environnements autonomes et hébergés
Langage
Bibliothèque standard
En-têtes de la bibliothèque standard
Exigences nommées
Macros de test de fonctionnalités (C++20)
Bibliothèque de support du langage
Bibliothèque de concepts (C++20)
Bibliothèque de diagnostics
Bibliothèque de gestion de mémoire
Bibliothèque de métaprogrammation (C++11)
Bibliothèque d'utilitaires généraux
Bibliothèque de conteneurs
Bibliothèque d'itérateurs
Bibliothèque de Ranges (C++20)
Bibliothèque d'algorithmes
Bibliothèque de chaînes
Bibliothèque de traitement de texte
Bibliothèque numérique
Bibliothèque de date et heure
Bibliothèque d'entrée/sortie
Bibliothèque de système de fichiers (C++17)
Bibliothèque de support de la concurrence (C++11)
Bibliothèque de contrôle d'exécution (C++26)
Spécifications techniques
Index des symboles
Bibliothèques externes

fr.cppreference.net

Namespaces

Variants