https://github.com/okaneco/saturating_cast
Library for saturating casts between integer primitives
https://github.com/okaneco/saturating_cast
no-std rust rust-library saturating-casts
Last synced: 2 months ago
JSON representation
Library for saturating casts between integer primitives
- Host: GitHub
- URL: https://github.com/okaneco/saturating_cast
- Owner: okaneco
- License: apache-2.0
- Created: 2023-10-11T01:37:50.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2023-10-13T17:00:37.000Z (almost 2 years ago)
- Last Synced: 2025-05-12T23:09:14.654Z (2 months ago)
- Topics: no-std, rust, rust-library, saturating-casts
- Language: Rust
- Homepage:
- Size: 11.7 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# `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::() - 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.