std::clamp

Défini dans l'en-tête `<algorithm>`
template< class T > constexpr const T& clamp( const T& v, const T& lo, const T& hi );	(1)	(depuis C++17)
template< class T, class Compare > constexpr const T& clamp( const T& v, const T& lo, const T& hi, Compare comp );	(2)	(depuis C++17)

Si la valeur de v est dans [lo, hi], renvoie v ; sinon renvoie la limite la plus proche.

1) Utilise operator<(jusqu'à C++20)std::less{}(depuis C++20) pour comparer les valeurs.

Si T n'est pas LessThanComparable, le comportement est indéfini.^[1]

2) Utilise la fonction de comparaison comp pour comparer les valeurs.

Si lo est supérieur à hi, le comportement est indéfini.

↑ Si NaN est évité, T peut être un type à virgule flottante.

Paramètres

v - la valeur à contraindre

lo, hi - les limites entre lesquelles contraindre v

comp

-

objet fonction de comparaison (c'est-à-dire un objet qui satisfait aux exigences de Compare) qui renvoie true si le premier argument est inférieur au second.

La signature de la fonction de comparaison doit être équivalente à ce qui suit :

bool cmp(const Type1& a, const Type2& b);

Bien que la signature n'ait pas besoin d'avoir const&, la fonction ne doit pas modifier les objets qui lui sont passés et doit pouvoir accepter toutes les valeurs de type (éventuellement const) Type1 et Type2 quelle que soit la catégorie de valeur (donc, Type1& n'est pas autorisé, ni Type1 sauf si Type1 un déplacement équivaut à une copie(depuis C++11)).
Les types Type1 et Type2 doivent être tels qu'un objet de type T puisse être implicitement converti vers les deux.

Valeur de retour

Référence à lo si v est inférieur à lo, référence à hi si hi est inférieur à v, sinon référence à v.

Complexité

1) Au plus deux comparaisons utilisant operator<(jusqu'à C++20)std::less{}(depuis C++20).

2) Au plus deux applications de la fonction de comparaison comp.

Implémentation possible

clamp (1)

template<class T>
constexpr const T& clamp(const T& v, const T& lo, const T& hi)
{
    return clamp(v, lo, hi, less{});
}

clamp (2)

template<class T, class Compare>
constexpr const T& clamp(const T& v, const T& lo, const T& hi, Compare comp)
{
    return comp(v, lo) ? lo : comp(hi, v) ? hi : v;
}

Notes

Capturer le résultat de std::clamp par référence produit une référence pendante si l'un des paramètres est une temporaire et que ce paramètre est renvoyé :

int n = -1;
const int& r = std::clamp(n, 0, 255); // r is dangling

Si v est équivalent à l'une des bornes, renvoie une référence à v, pas à la borne.

Macro de test de fonctionnalité	Valeur	Std	Fonctionnalité
`__cpp_lib_clamp`	`201603L`	(C++17)	`std::clamp`

Exemple

Exécuter ce code

#include <algorithm>
#include <cstdint>
#include <iomanip>
#include <iostream>

int main()
{
    std::cout << "[raw] "
                 "[" << INT8_MIN << ',' << INT8_MAX << "] "
                 "[0," << UINT8_MAX << "]\n";

    for (const int v : {-129, -128, -1, 0, 42, 127, 128, 255, 256})
        std::cout << std::setw(4) << v
                  << std::setw(11) << std::clamp(v, INT8_MIN, INT8_MAX)
                  << std::setw(8) << std::clamp(v, 0, UINT8_MAX) << '\n';
}

Sortie :

[raw] [-128,127] [0,255]
-129       -128       0
-128       -128       0
  -1         -1       0
   0          0       0
  42         42      42
 127        127     127
 128        127     128
 255        127     255
 256        127     255

Voir aussi

min	renvoie la plus petite des valeurs données (modèle de fonction & objet fonction d'algorithme)
ranges::min (C++20)
max	renvoie la plus grande des valeurs données (modèle de fonction & objet fonction d'algorithme)
ranges::max (C++20)
in_range (C++20)	vérifie si une valeur entière est dans la plage d'un type entier donné (modèle de fonction)
ranges::clamp (C++20)	contraint une valeur entre une paire de valeurs limites (objet fonction d'algorithme)

[1] Si NaN est évité, T peut être un type à virgule flottante.

[1]

Support du compilateur
Libre et hébergé
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 la 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 plages (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