Wrapping add. In a fixed-size numeric type (like u8 or usize) we have a maximum and minimum value. At some point, further adds or subtracts will cause the representation to wrap around.
In debug mode, Rust programs will panic if a numeric wrapping occurs in an unexpected location. We can use wrapping_add and wrapping_sub (along with saturating versions) to help here.
First example. Here we use the u8 type, which is just 1 byte, to demonstrate the wrapping_add and wrapping_sub methods. We observe the effects of the methods.
Part 1 We invoke wrapping_sub on a u8 variable with the value 10. This subtracts 1, and gives us the value 9.
Part 2 Here we start with the value 250, which is near the max of 255. The value wraps to 0 when we add 1 to 255.
fn main() {
// Part 1: subtract 1 with wrapping sub.
let mut value = 10u8;
value = value.wrapping_sub(1);
println!("{value}");
// Part 2: add 1 with wrapping add 20 times.
let mut value = 250u8;
for _ in 0..20 {
value = value.wrapping_add(1);
println!("{value}");
}
}9
251
252
253
254
255
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Saturating. Instead of wrapping, we can specify the saturating behavior with saturating_add and sub. This "maxes" out the values but does not allow them to wrap to 0.
Here We use saturating_add on the starting value of 250 for a u8. This goes to 255, and then stays there when we keep adding.
fn main() {
// Use saturating add on u8.
let mut value = 250u8;
for _ in 0..10 {
value = value.saturating_add(1);
println!("{value}");
}
}251
252
253
254
255
255
255
255
255
255
For fixing panics in debug Rust programs, wrapping_add and wrapping_sub can be useful. This helps clarify the program's logic and eliminate unwanted behavior and bugs.
Dot Net Perls is a collection of tested code examples. Pages are continually updated to stay current, with code correctness a top priority.
Sam Allen is passionate about computer languages. In the past, his work has been recommended by Apple and Microsoft and he has studied computers at a selective university in the United States.