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 pages with code examples, which are updated to stay current. Programming is an art, and it can be learned from examples.
Donate to this site to help offset the costs of running the server. Sites like this will cease to exist if there is no financial support for them.
Sam Allen is passionate about computer languages, and he maintains 100% of the material available on this website. He hopes it makes the world a nicer place.