blockworks-foundation
/
fixed
mirror of https://github.com/blockworks-foundation/fixed.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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:
Trevor Spiteri 2020-05-10 18:43:22 +02:00
parent 1eca782f60
commit 13010d6ed9
4 changed files with 67 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
src/convert.rs
View File

@ -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()

45
src/macros_from_to.rs
View File

@ -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

50
src/traits.rs
View File

@ -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<F: Fixed>(src: F) -> Option<Self>
@ -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<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.
@ -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<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
///
@ -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<F: 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<F: 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<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);
@ -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<F: 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<F: 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<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)
@ -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<F: 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<F: 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

9
src/wrapping.rs
View File

@ -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