diff --git a/src/lib.rs b/src/lib.rs index 6789d47..6b408eb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2243,6 +2243,98 @@ macro_rules! fixed { } } + doc_comment! { + concat!(r#" +Saturating ceil. Rounds towards +∞, saturating on overflow. + +# Examples + +```rust +use fixed::frac; +use fixed::"#, stringify!($Fixed), r#"; +type Fix = "#, stringify!($Fixed), r#"; +let two_half = Fix::from_int(5) / 2; +assert_eq!(two_half.saturating_ceil(), Fix::from_int(3));"#, +if_signed_unsigned!($Signedness, r#" +assert_eq!((-two_half).saturating_ceil(), Fix::from_int(-2));"#, "" +), r#" +assert_eq!(Fix::max_value().saturating_ceil(), Fix::max_value()); +``` +"#, + ), + #[inline] + pub fn saturating_ceil(self) -> $Fixed { + let saturated = $Fixed::max_value(); + let (ceil, overflow) = self.overflowing_ceil(); + if overflow { saturated } else { ceil } + } + } + + doc_comment! { + concat!(if_signed_unsigned!($Signedness, r#" +Saturating floor. Rounds towards −∞, saturating on overflow. + +Overflow can only occur when there are zero integer bits. +"#, r#" +Saturating floor. Rounds towards −∞. Cannot overflow for unsigned values. +"#), r#" + +# Examples + +```rust +use fixed::frac; +use fixed::"#, stringify!($Fixed), r#"; +type Fix = "#, stringify!($Fixed), r#"; +let two_half = Fix::from_int(5) / 2; +assert_eq!(two_half.saturating_floor(), Fix::from_int(2));"#, +if_signed_unsigned!($Signedness, concat!(r#" +assert_eq!((-two_half).saturating_floor(), Fix::from_int(-3)); +type AllFrac = "#, stringify!($Fixed), "; +assert_eq!(AllFrac::min_value().saturating_floor(), AllFrac::min_value());"#), "" +), r#" +``` +"#, + ), + #[inline] + pub fn saturating_floor(self) -> $Fixed { + let saturated = $Fixed::min_value(); + let (floor, overflow) = self.overflowing_floor(); + if overflow { saturated } else { floor } + } + } + + doc_comment! { + concat!(r#" +Saturating round. Rounds to the nearest, with ties rounded away from +zero, and saturating on overflow. + +# Examples + +```rust +use fixed::frac; +use fixed::"#, stringify!($Fixed), r#"; +type Fix = "#, stringify!($Fixed), r#"; +let two_half = Fix::from_int(5) / 2; +assert_eq!(two_half.saturating_round(), Fix::from_int(3));"#, +if_signed_unsigned!($Signedness, r#" +assert_eq!((-two_half).saturating_round(), Fix::from_int(-3));"#, "" +), r#" +assert_eq!(Fix::max_value().saturating_round(), Fix::max_value()); +``` +"#, + ), + #[inline] + pub fn saturating_round(self) -> $Fixed { + let saturated = if self.to_bits() > 0 { + $Fixed::max_value() + } else { + $Fixed::min_value() + }; + let (round, overflow) = self.overflowing_round(); + if overflow { saturated } else { round } + } + } + doc_comment! { concat!(r#" Wrapping ceil. Rounds towards +∞, wrapping on overflow.