# `saturating_cast`
[](https://github.com/okaneco/saturating_cast)
[](https://crates.io/crates/saturating_cast)
[](https://docs.rs/saturating_cast)
Library for saturating casts between integer primitives.
## Features
- `no_std` by default
- Saturating casts implemented between all of the following:
- `u8`, `u16`, `u32`, `u64`, `u128`, `usize`
- `i8`, `i16`, `i32`, `i64`, `i128`, `isize`
- Saturating traits can be implemented for user types
## Description
A saturating cast is a combined [`clamp`][clamp] and cast from one type to
another, conceptually `value.clamp(T::MIN, T::MAX) as T`.
[clamp]: https://doc.rust-lang.org/stable/std/cmp/trait.Ord.html#method.clamp
## Example
In the following code, the `i32` value is clamped to `255` since `u8` has a
range of `0..=255` and `1024` is larger than the maximum value that `u8` can
represent.
In the second snippet, an `i8` with negative sign is saturated to `0` when cast
to `u16` because unsigned integers cannot be negative.
```rust
use saturating_cast::SaturatingCast;
let x: i32 = 1024;
let y: u8 = 10;
let z = x.saturating_cast::<u8>() - y;
assert_eq!(245, z);
let a = -128_i8;
let b: u16 = a.saturating_cast();
assert_eq!(0, b);
```
Saturation **does not** preserve the original value if the source type value
is out of range for the target type: the resulting value will be the minimum or
maximum of the target type.
This crate only casts and returns primitive integers. Saturating arithmetic is
still required to avoid wraparound in `release` and panicking in `debug` mode
(or with overflow checks on in `release`).
## License
This crate is licensed under either
- the [MIT License](LICENSE-MIT), or
- the [Apache License (Version 2.0)](LICENSE-APACHE)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.