From 13010d6ed9777afb23766b53635f3ae180c8f548 Mon Sep 17 00:00:00 2001 From: Trevor Spiteri Date: Sun, 10 May 2020 18:43:22 +0200 Subject: [PATCH] docs: change wording from truncate to discard fractional bits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Truncation might be interpreted to mean rounding towards zero, which is not what happens in negative two's-complement fixed-point numbers. So "extra fractional bits are truncated" is better as "extra fractional bits are discarded, which rounds towards −∞." --- src/convert.rs | 12 +++++------ src/macros_from_to.rs | 45 +++++++++++++++++++++++++------------- src/traits.rs | 50 +++++++++++++++++++++---------------------- src/wrapping.rs | 9 +++++--- 4 files changed, 67 insertions(+), 49 deletions(-) diff --git a/src/convert.rs b/src/convert.rs index 9514bc6..590864e 100644 --- a/src/convert.rs +++ b/src/convert.rs @@ -146,7 +146,7 @@ macro_rules! convert_lossy { /// This conversion never fails (infallible) but may lose /// precision (lossy). Any fractional bits in the source /// that cannot be represented in the destination are - /// truncated. + /// discarded, which rounds towards −∞. #[inline] fn lossy_from(src: $SrcU) -> Self { src.to_num() @@ -165,7 +165,7 @@ macro_rules! convert_lossy { /// This conversion never fails (infallible) but may lose /// precision (lossy). Any fractional bits in the source /// that cannot be represented in the destination are - /// truncated. + /// discarded, which rounds towards −∞. #[inline] fn lossy_from(src: $SrcI) -> Self { src.to_num() @@ -184,7 +184,7 @@ macro_rules! convert_lossy { /// This conversion never fails (infallible) but may lose /// precision (lossy). Any fractional bits in the source /// that cannot be represented in the destination are - /// truncated. + /// discarded, which rounds towards −∞. #[inline] fn lossy_from(src: $SrcU) -> Self { src.to_num() @@ -618,7 +618,7 @@ macro_rules! fixed_to_int_lossy { /// /// This conversion never fails (infallible) but may lose /// precision (lossy). Any fractional bits in the source - /// are truncated. + /// are discarded, which rounds towards −∞. #[inline] fn lossy_from(src: $SrcU) -> Self { src.to_num() @@ -634,7 +634,7 @@ macro_rules! fixed_to_int_lossy { /// /// This conversion never fails (infallible) but may lose /// precision (lossy). Any fractional bits in the source - /// are truncated. + /// are discarded, which rounds towards −∞. #[inline] fn lossy_from(src: $SrcI) -> Self { src.to_num() @@ -650,7 +650,7 @@ macro_rules! fixed_to_int_lossy { /// /// This conversion never fails (infallible) but may lose /// precision (lossy). Any fractional bits in the source - /// are truncated. + /// are discarded, which rounds towards −∞. #[inline] fn lossy_from(src: $SrcU) -> Self { src.to_num() diff --git a/src/macros_from_to.rs b/src/macros_from_to.rs index 7fe0d22..e7010f9 100644 --- a/src/macros_from_to.rs +++ b/src/macros_from_to.rs @@ -20,7 +20,8 @@ macro_rules! fixed_from_to { The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or [`usize`]. @@ -102,10 +103,12 @@ assert_eq!(Fix::from_num(", The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or - [`usize`]. Any fractional bits are truncated. + [`usize`]. Any fractional bits are discarded, which rounds towards + −∞. * A floating-point number of type [`f32`] or [`f64`]. If the [`f16` feature] is enabled, it can also be of type [`f16`] or [`bf16`]. For this conversion, the method rounds to the nearest, with ties @@ -189,7 +192,8 @@ fits, otherwise returns [`None`]. The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or [`usize`]. @@ -276,10 +280,12 @@ fits, otherwise returns [`None`]. The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or - [`usize`]. Any fractional bits are truncated. + [`usize`]. Any fractional bits are discarded, which rounds towards + −∞. * A floating-point number of type [`f32`] or [`f64`]. If the [`f16` feature] is enabled, it can also be of type [`f16`] or [`bf16`]. For this conversion, the method rounds to the nearest, with ties @@ -362,7 +368,8 @@ saturating if it does not fit. The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or [`usize`]. @@ -456,10 +463,12 @@ saturating the value if it does not fit. The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or - [`usize`]. Any fractional bits are truncated. + [`usize`]. Any fractional bits are discarded, which rounds towards + −∞. * A floating-point number of type [`f32`] or [`f64`]. If the [`f16` feature] is enabled, it can also be of type [`f16`] or [`bf16`]. For this conversion, the method rounds to the nearest, with ties @@ -543,7 +552,8 @@ wrapping the value on overflow. The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or [`usize`]. @@ -623,10 +633,12 @@ wrapping the value on overflow. The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or - [`usize`]. Any fractional bits are truncated. + [`usize`]. Any fractional bits are discarded, which rounds towards + −∞. * A floating-point number of type [`f32`] or [`f64`]. If the [`f16` feature] is enabled, it can also be of type [`f16`] or [`bf16`]. For this conversion, the method rounds to the nearest, with ties @@ -713,7 +725,8 @@ returned. The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or [`usize`]. @@ -799,10 +812,12 @@ overflow has occurred. On overflow, the wrapped value is returned. The other number can be: - * Another fixed-point number. Any extra fractional bits are truncated. + * Another fixed-point number. Any extra fractional bits are + discarded, which rounds towards −∞. * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or - [`usize`]. Any fractional bits are truncated. + [`usize`]. Any fractional bits are discarded, which rounds towards + −∞. * A floating-point number of type [`f32`] or [`f64`]. If the [`f16` feature] is enabled, it can also be of type [`f16`] or [`bf16`]. For this conversion, the method rounds to the nearest, with ties diff --git a/src/traits.rs b/src/traits.rs index 382fad0..f5c7ea2 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -1363,7 +1363,7 @@ where pub trait FromFixed { /// Converts from a fixed-point number. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// # Panics /// @@ -1378,7 +1378,7 @@ pub trait FromFixed { /// Converts from a fixed-point number if it fits, otherwise returns [`None`]. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None fn checked_from_fixed(src: F) -> Option @@ -1387,12 +1387,12 @@ pub trait FromFixed { /// Converts from a fixed-point number, saturating if it does not fit. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. fn saturating_from_fixed(src: F) -> Self; /// Converts from a fixed-point number, wrapping if it does not fit. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. fn wrapping_from_fixed(src: F) -> Self; /// Converts from a fixed-point number. @@ -1401,7 +1401,7 @@ pub trait FromFixed { /// an overflow has occurred. On overflow, the wrapped value is /// returned. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// [`bool`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html /// [tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html @@ -1436,7 +1436,7 @@ pub trait FromFixed { pub trait ToFixed { /// Converts to a fixed-point number. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// # Panics /// @@ -1454,14 +1454,14 @@ pub trait ToFixed { /// Converts to a fixed-point number if it fits, otherwise returns [`None`]. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None fn checked_to_fixed(self) -> Option; /// Converts to a fixed-point number, saturating if it does not fit. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// # Panics /// @@ -1472,7 +1472,7 @@ pub trait ToFixed { /// Converts to a fixed-point number, wrapping if it does not fit. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// # Panics /// @@ -1487,7 +1487,7 @@ pub trait ToFixed { /// indicating whether an overflow has occurred. On overflow, the /// wrapped value is returned. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// # Panics /// @@ -1561,7 +1561,7 @@ macro_rules! impl_int { impl FromFixed for $Int { /// Converts a fixed-point number to an integer. /// - /// Any fractional bits are truncated. + /// Any fractional bits are discarded, which rounds towards −∞. /// /// # Panics /// @@ -1580,7 +1580,7 @@ macro_rules! impl_int { /// Converts a fixed-point number to an integer if it fits, otherwise returns [`None`]. /// - /// Any fractional bits are truncated. + /// Any fractional bits are discarded, which rounds towards −∞. /// /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None #[inline] @@ -1590,7 +1590,7 @@ macro_rules! impl_int { /// Converts a fixed-point number to an integer, saturating if it does not fit. /// - /// Any fractional bits are truncated. + /// Any fractional bits are discarded, which rounds towards −∞. #[inline] fn saturating_from_fixed(src: F) -> Self { $Int::from_repr_fixed(FromFixed::saturating_from_fixed(src)) @@ -1598,7 +1598,7 @@ macro_rules! impl_int { /// Converts a fixed-point number to an integer, wrapping if it does not fit. /// - /// Any fractional bits are truncated. + /// Any fractional bits are discarded, which rounds towards −∞. #[inline] fn wrapping_from_fixed(src: F) -> Self { $Int::from_repr_fixed(FromFixed::wrapping_from_fixed(src)) @@ -1610,7 +1610,7 @@ macro_rules! impl_int { /// an overflow has occurred. On overflow, the wrapped value is /// returned. /// - /// Any fractional bits are truncated. + /// Any fractional bits are discarded, which rounds towards −∞. /// /// [`bool`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html /// [tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html @@ -2064,7 +2064,7 @@ macro_rules! impl_fixed { impl FromFixed for $Fixed { /// Converts a fixed-point number. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. #[inline] fn from_fixed(src: F) -> Self { let (wrapped, overflow) = FromFixed::overflowing_from_fixed(src); @@ -2075,7 +2075,7 @@ macro_rules! impl_fixed { /// Converts a fixed-point number if it fits, otherwise returns [`None`]. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None #[inline] @@ -2088,7 +2088,7 @@ macro_rules! impl_fixed { /// Converts a fixed-point number, saturating if it does not fit. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. #[inline] fn saturating_from_fixed(src: F) -> Self { let conv = src.private_to_fixed_helper(Self::FRAC_NBITS, Self::INT_NBITS); @@ -2118,7 +2118,7 @@ macro_rules! impl_fixed { /// Converts a fixed-point number, wrapping if it does not fit. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. #[inline] fn wrapping_from_fixed(src: F) -> Self { let (wrapped, _) = FromFixed::overflowing_from_fixed(src); @@ -2131,7 +2131,7 @@ macro_rules! impl_fixed { /// indicating whether an overflow has occurred. On /// overflow, the wrapped value is returned. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// [`bool`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html /// [tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html @@ -2165,7 +2165,7 @@ macro_rules! impl_fixed { impl ToFixed for $Fixed { /// Converts a fixed-point number. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. #[inline] fn to_fixed(self) -> F { FromFixed::from_fixed(self) @@ -2173,7 +2173,7 @@ macro_rules! impl_fixed { /// Converts a fixed-point number if it fits, otherwise returns [`None`]. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None #[inline] @@ -2183,7 +2183,7 @@ macro_rules! impl_fixed { /// Converts a fixed-point number, saturating if it does not fit. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. #[inline] fn saturating_to_fixed(self) -> F { FromFixed::saturating_from_fixed(self) @@ -2191,7 +2191,7 @@ macro_rules! impl_fixed { /// Converts a fixed-point number, wrapping if it does not fit. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. #[inline] fn wrapping_to_fixed(self) -> F { FromFixed::wrapping_from_fixed(self) @@ -2203,7 +2203,7 @@ macro_rules! impl_fixed { /// indicating whether an overflow has occurred. On /// overflow, the wrapped value is returned. /// - /// Any extra fractional bits are truncated. + /// Any extra fractional bits are discarded, which rounds towards −∞. /// /// [`bool`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html /// [tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html diff --git a/src/wrapping.rs b/src/wrapping.rs index 7aaa416..a99b660 100644 --- a/src/wrapping.rs +++ b/src/wrapping.rs @@ -124,7 +124,8 @@ impl Wrapping { /// /// The other number can be: /// - /// * A fixed-point number. Any extra fractional bits are truncated. + /// * A fixed-point number. Any extra fractional bits are + /// discarded, which rounds towards −∞. /// * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], /// [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or /// [`usize`]. @@ -195,10 +196,12 @@ impl Wrapping { /// /// The other number can be: /// - /// * Another fixed-point number. Any extra fractional bits are truncated. + /// * Another fixed-point number. Any extra fractional bits are + /// discarded, which rounds towards −∞. /// * An integer of type [`i8`], [`i16`], [`i32`], [`i64`], [`i128`], /// [`isize`], [`u8`], [`u16`], [`u32`], [`u64`], [`u128`], or - /// [`usize`]. Any fractional bits are truncated. + /// [`usize`]. Any fractional bits are discarded, which rounds + /// towards −∞. /// * A floating-point number of type [`f32`] or [`f64`]. If the /// [`f16` feature] is enabled, it can also be of type [`f16`] /// or [`bf16`]. For this conversion, the method rounds to the