wrapping add ExamplesUse the wrapping add, wrapping sub, and saturating methods to safely add and subtract numbers.
This page was last reviewed on May 10, 2023.
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.
This page was last updated on May 10, 2023 (new).
© 2007-2023 Sam Allen.