docs: change wording from truncate to discard fractional bits
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 −∞."
This commit is contained in:
parent
961d36aa2a
commit
5b7d05b775
|
@ -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<FracSrc>) -> 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<FracSrc>) -> 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<FracSrc>) -> 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<FracSrc>) -> 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<FracSrc>) -> 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<FracSrc>) -> Self {
|
||||
src.to_num()
|
||||
|
|
|
@ -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`].
|
||||
|
@ -275,10 +279,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
|
||||
|
@ -361,7 +367,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`].
|
||||
|
@ -450,10 +457,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
|
||||
|
@ -532,7 +541,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`].
|
||||
|
@ -612,10 +622,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
|
||||
|
@ -697,7 +709,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`].
|
||||
|
@ -783,10 +796,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
|
||||
|
|
|
@ -1306,7 +1306,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
|
||||
///
|
||||
|
@ -1321,7 +1321,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<F: Fixed>(src: F) -> Option<Self>
|
||||
|
@ -1330,12 +1330,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<F: 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<F: Fixed>(src: F) -> Self;
|
||||
|
||||
/// Converts from a fixed-point number.
|
||||
|
@ -1344,7 +1344,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
|
||||
|
@ -1379,7 +1379,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
|
||||
///
|
||||
|
@ -1397,14 +1397,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<F: Fixed>(self) -> Option<F>;
|
||||
|
||||
/// 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
|
||||
///
|
||||
|
@ -1415,7 +1415,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
|
||||
///
|
||||
|
@ -1430,7 +1430,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
|
||||
///
|
||||
|
@ -1504,7 +1504,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
|
||||
///
|
||||
|
@ -1523,7 +1523,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]
|
||||
|
@ -1533,7 +1533,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<F: Fixed>(src: F) -> Self {
|
||||
$Int::from_repr_fixed(FromFixed::saturating_from_fixed(src))
|
||||
|
@ -1541,7 +1541,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<F: Fixed>(src: F) -> Self {
|
||||
$Int::from_repr_fixed(FromFixed::wrapping_from_fixed(src))
|
||||
|
@ -1553,7 +1553,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
|
||||
|
@ -2007,7 +2007,7 @@ macro_rules! impl_fixed {
|
|||
impl<Frac: $LeEqU> FromFixed for $Fixed<Frac> {
|
||||
/// Converts a fixed-point number.
|
||||
///
|
||||
/// Any extra fractional bits are truncated.
|
||||
/// Any extra fractional bits are discarded, which rounds towards −∞.
|
||||
#[inline]
|
||||
fn from_fixed<F: Fixed>(src: F) -> Self {
|
||||
let (wrapped, overflow) = FromFixed::overflowing_from_fixed(src);
|
||||
|
@ -2018,7 +2018,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]
|
||||
|
@ -2031,7 +2031,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<F: Fixed>(src: F) -> Self {
|
||||
let conv = src.private_to_fixed_helper(Self::FRAC_NBITS, Self::INT_NBITS);
|
||||
|
@ -2061,7 +2061,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<F: Fixed>(src: F) -> Self {
|
||||
let (wrapped, _) = FromFixed::overflowing_from_fixed(src);
|
||||
|
@ -2074,7 +2074,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
|
||||
|
@ -2108,7 +2108,7 @@ macro_rules! impl_fixed {
|
|||
impl<Frac: $LeEqU> ToFixed for $Fixed<Frac> {
|
||||
/// Converts a fixed-point number.
|
||||
///
|
||||
/// Any extra fractional bits are truncated.
|
||||
/// Any extra fractional bits are discarded, which rounds towards −∞.
|
||||
#[inline]
|
||||
fn to_fixed<F: Fixed>(self) -> F {
|
||||
FromFixed::from_fixed(self)
|
||||
|
@ -2116,7 +2116,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]
|
||||
|
@ -2126,7 +2126,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<F: Fixed>(self) -> F {
|
||||
FromFixed::saturating_from_fixed(self)
|
||||
|
@ -2134,7 +2134,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<F: Fixed>(self) -> F {
|
||||
FromFixed::wrapping_from_fixed(self)
|
||||
|
@ -2146,7 +2146,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
|
||||
|
|
|
@ -124,7 +124,8 @@ impl<F: Fixed> Wrapping<F> {
|
|||
///
|
||||
/// 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<F: Fixed> Wrapping<F> {
|
|||
///
|
||||
/// 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
|
||||
|
|
Loading…
Reference in New Issue