truncate-integer: integer truncation for Rust
There are several ways one might want to do integer truncation in Rust:
- Unchecked: truncation may result in a changed value. You only get the low-order N bits.
- Checked: if truncation would result in a changed value, return
- Panicking: if truncation would result in a changed value, ‘panic!’
This is equivalent to checked truncation with
.unwrap(), but with a nicer panic message.
- Saturating: if truncation would result in a changed value, return the maximum value that would fit in the target type.
It’s possible to get all of these in Rust without importing additional crates or writing much code, for example:
let x = 257u16; let unchecked = x as u8; assert_eq!(unchecked, 1u8); let checked = u8::try_from(x); assert!(checked.is_err()); // This would panic // let value = x.try_from().unwrap(); let saturating = u8::try_from(x).unwrap_or(u8::MAX); assert_eq!(saturating, 255);
If those are good enough for you, then you don’t need this crate. However, if you would prefer to call a function to communicate your intent, then you might find this crate useful.
It provides a trait that implements each of the truncation forms listed above:
TruncateUncheckedperforms unchecked truncation.
TryTruncateperforms checked truncation.
Chopperforms panicking truncation.
Shrinkperforms saturating truncation.
It’s sometimes desirable to invert this logic, e.g. in trait bounds, so there is an inverse of each of the above:
All of the truncations are implemented for both signed and unsigned
integers (including signed-to-unsigned and vice versa), except
TruncateFromUnchecked, because it’s not immediately clear what the
correct output would be when then input is outside the output bounds.