Clamp in C++

In this article, you will learn about the clamp in C++ with its syntax, examples, and several methods.

Introduction to std::clamp:

One useful function in C++ that helps you maintain a value within the specified range is std::clamp. Its main objective is to constrain a value to stay within predetermined bounds. It is especially helpful to ensure that a value in your program stays within certain bounds or imposes restrictions on input.

The <algorithm> header contains the definition of std::clamp, which is a component of the C++ Standard Library. Std::clamp is one of the many helpful functions and algorithms in this header. You can use std::clamp and many other algorithms and tools in your C++ program when you include this header.

Objective:

C++'s std::clamp function clamps a value within a specified range. Stated differently, it ensures that the value falls between a given minimum and maximum value. It can be helpful in several circumstances, including:

• Authenticating user data
• Keeping values from exceeding or falling short of expectations
• Maintaining values for graphical or audio processing within a specific range

Syntax:

The std::clamp function has the following syntax:

template<typename T>


constexpr T clamp(const T& value, const T& min, const T& max);

Where:

T is the type of the value to be clamped.

value is the value to be clamped.

min is the minimum value of the range.

max is the maximum value of the range.

Parameters:

The std::clamp function takes three parameters:

value: The value to be clamped. It can be any type that supports the <operator>.

min: The minimum value of the range. It must be of the same type as value.

max: The maximum value of the range. It must be of the same type as value.

Return value:

The std::clamp function returns a link to the clamped value. The function returns a reference to the initial value if the value is already inside the range. If not, the process refers back to the value closest to the minimum or maximum.

Example:

Let us take an example to demonstrate the use of std::clamp. Use the clamp function to confine a floating-point value to the interval [0, 1]:

#include <algorithm>


#include <iostream>


int main() {


  float inputValue = 10.0f;


  float minimumLimit = 0.0f;


  float maximumLimit = 1.0f;


  // Clamp the input value to the range [0, 1]


  float clampedResult = std::clamp(inputValue, minimumLimit, maximumLimit);


  std::cout << "Clamped value: " << clampedResult << std::endl;


  return 0;


}

Output:

Here are some instances of how to restrict a value within a given range using std::clamp:

#include <algorithm>


#include <iostream>


#include <string>


int main() {


  // Example 1: Clamping a temperature within a valid range


  float temperature = 25.5f;


  float minTemperature = 0.0f;


  float maxTemperature = 100.0f;


  float clampedTemperature = std::clamp(temperature, minTemperature, maxTemperature);


  // Example 2: Clamping a speed value within safe limits


  double currentSpeed = 90.5;


  double minSpeed = 0.0;


  double maxSpeed = 120.0;


  double clampedSpeed = std::clamp(currentSpeed, minSpeed, maxSpeed);


  // Example 3: Clamping a username to a reasonable length


  std::string username = "coding_enthusiast2023";


  int maxUsernameLength = 15;


  // Ensure the string does not exceed the maximum length


  if (username.length() > maxUsernameLength) {


    username = username.substr(0, maxUsernameLength);


  }


  // Print the clamped values


  std::cout << "Clamped temperature: " << clampedTemperature << " degrees Celsius" << std::endl;


  std::cout << "Clamped speed: " << clampedSpeed << " km/h" << std::endl;


  std::cout << "Clamped username: " << username << std::endl;


  return 0;


}

Output:

Other instances:

• Before processing, a user-input value must be clamped to a valid range.
• Clamping a sound file's volume to avoid clipping.
• Adjusting an image's brightness to avoid over- or underexposure.
• Clamping an object's position in a video game so that it stays inside the game's boundaries.

If the custom type supports the <operator>, it can be used with a wide range of data types, including integers, floating-point numbers, and custom types, using the std::clamp function.

Integers:

You only need to pass the integer to the std::clamp function along with the range's minimum and maximum values to clamp an integer to a given range. A reference to the clamped integer will be the function's return value.

An example of clamping an integer to the range [0, 100] is given below:

#include <iostream>


#include <algorithm>


int main() {


  int value = 50;


  int min = 0;


  int max = 100;


  int clampedValue = std::clamp(value, min, max);


  std::cout << "Original value: " << value << std::endl;


  std::cout << "Clamped value: " << clampedValue << std::endl;


  return 0;


}

Output:

Numerical floating points:

The same method for integers can also clamp a floating-point number to a given range. It is crucial to remember that floating-point numbers are prone to rounding errors, so the clamped value might not match the range's minimum or maximum value exactly.

#include <iostream>


#include <algorithm> // Include the algorithm header for std::clamp


int main() {


  float value = 0.5f;


  float min = -1.0f;


  float max = 1.0f;


  float clampedValue = std::clamp(value, min, max);


  std::cout << "Clamped value: " << clampedValue << std::endl;


  return 0;


}

Output:

Custom types:

A custom type needs to support the <operator> to use std::clamp with it. Thus, it is necessary that the type can be compared to other values of the same type.

An illustration of a custom type that works with std::clamp is provided here:

struct MyCustomType {


int value;


  bool operator<(const MyCustomType& other) const {


    return value < other.value;


  }


};

You can easily use the std::clamp function to clamp a MyCustomType to a given range by passing it along its minimum and maximum values. The function will return the clamped MyCustomType reference.

Here is an illustration of how to clamp a MyCustomType to the [0, 100] range:

#include <iostream>


#include <algorithm>


class MyCustomType {


public:


  int value;


  MyCustomType(int val) : value(val) {}


  bool operator<(const MyCustomType& other) const {


    return value < other.value;


  }


};


int main() {


  MyCustomType value{50};


  MyCustomType min{0};


  MyCustomType max{100};


  MyCustomType clampedValue = std::clamp(value, min, max);


  std::cout << "Clamped value: " << clampedValue.value << std::endl;


  return 0;


}

Output:

Useful scenarios for std::clamp:

Std::clamp's input validation function can be used to verify that user input falls inside a valid range. For instance, you could use std::clamp to verify that an integer input is between 0 and 100.

int value = std::clamp(user_input, 0, 100);

Data normalization: Use std::clamp to normalize data to a specified range. For instance, you could use std::clamp to normalize sensor data to the range [0, 1].

float normalized_value = std::clamp(sensor_value, 0.0f, 1.0f);

Stopping overflow and underflow: You can stop integer and floating-point numbers from overflowing or underflowing using std::clamp. For instance, you could use std::clamp to make sure a pixel value in an image is between 0 and 255.

unsigned char pixel_value = std::clamp(pixel_value, 0, 255);

Maintaining values for visual or audio processing within a specific range: For graphical or audio processing, values can be maintained within a range using std::clamp. For instance, you could ensure that a sound file's volume is within a comfortable range by using std::clamp.

float clamped_volume = std::clamp(volume, -1.0f, 1.0f);

Other use cases:

• Maintaining an object's position in a video game within the boundaries of the real world.
• Keeping an image's brightness from rising above a specific level.
• Putting a cap on the quantity of items in a queue or list.
• Guaranteeing that a value is always a specific distance away from another value.

Ranges and Comparators:

Use the overload of the std::clamp function, which accepts a range iterator and a comparator as arguments, to use custom comparators or specify ranges besides the default min and max values.

template<typename T, typename InputIterator, typename Comparator>


constexpr T clamp(InputIterator first, InputIterator last, Comparator comp);

Whereas:

• T is the type of value that needs to be clamped.
• A forward iterator to the start of the range is called an inputiterator, and a forward iterator to the end of the range is called a last one.
• A binary predicate called a comparator accepts two values of type T as arguments and outputs a bool. If the first value is less than the second value, the predicate should return true; if not, it should return false.
• You only need to pass an instance of the custom comparator to the std::clamp function to use it. The comparator will be used to compare the values in the range to decide which value should be returned.

Here is an illustration of how to clamp a range of integers to the range [0, 100] using a custom comparator:

#include <algorithm>


#include <iostream>


#include <vector>


struct MyComparator {


  bool operator()(int a, int b) const {


    return a < b;


  }


};


int main() {


  std::vector<int> values = {50, 100, -10, 200, 300};


  // Sort the values using the custom comparator


  std::sort(values.begin(), values.end(), MyComparator());


  // Clamp the values to the range [0, 100]


  std::vector<int>::iterator min_it = std::lower_bound(values.begin(), values.end(), 0);


  std::vector<int>::iterator max_it = std::upper_bound(values.begin(), values.end(), 100);


  std::vector<int> clamped_values(min_it, max_it);


  // Print the clamped values


  for (int value : clamped_values) {


    std::cout << value << " ";


  }


  std::cout << std::endl;


  return 0;


}

Output:

Finally, custom comparators and defined ranges with std::clamp are helpful for several applications, such as:

• Verifying information provided by the user.
• Data standardization.
• Stopping both overflow and underflow.
• Directing the processing of images or sounds.
• Limiting where objects are located in video games.
• Controlling thresholds for image brightness.
• Items in a queue or list are limited.
• Keeping one value constant with another at a given distance.