diff --git a/README.md b/README.md
index 666f64c..553445f 100644
--- a/README.md
+++ b/README.md
@@ -15,10 +15,22 @@ The [*fixed* crate] provides fixed-point numbers.
* [`FixedI64`] and [`FixedU64`] are 64-bit fixed-point numbers.
* [`FixedI128`] and [`FixedU128`] are 128-bit fixed-point numbers.
-These types can have `Frac` fractional bits, where
-0 ≤ `Frac` ≤ n and n is the total number of bits. When
-`Frac` = 0, the fixed-point number behaves like an n-bit
-integer. When `Frac` = n, the value x lies in the range
+These types can have f = `Frac` fractional bits, where
+0 ≤ f ≤ n and n is the total number of bits. For
+example, [`FixedI32`] is a 32-bit signed fixed-point number with
+n = 32. The value x can lie in the range
+−2n − f − 1 ≤ x < 2n − f − 1
+for signed numbers, and in the range
+0 ≤ x < 2n − f for unsigned numbers. The
+difference between successive numbers is constant throughout the
+range: Δ = 2−f.
+
+When f = 0, Δ = 1 and the fixed-point number behaves
+like an n-bit integer with the value lying in the range
+−2n − 1 ≤ x < 2n − 1 for signed
+numbers, and in the range 0 ≤ x < 2n for
+unsigned numbers. When f = n,
+Δ = 2−n and the value lies in the range
−0.5 ≤ x < 0.5 for signed numbers, and in the range
0 ≤ x < 1 for unsigned numbers.
diff --git a/src/lib.rs b/src/lib.rs
index 013ccb5..e1b8395 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -24,10 +24,22 @@ The [*fixed* crate] provides fixed-point numbers.
* [`FixedI64`] and [`FixedU64`] are 64-bit fixed-point numbers.
* [`FixedI128`] and [`FixedU128`] are 128-bit fixed-point numbers.
-These types can have `Frac` fractional bits, where
-0 ≤ `Frac` ≤ n and n is the total number of bits. When
-`Frac` = 0, the fixed-point number behaves like an n-bit
-integer. When `Frac` = n, the value x lies in the range
+These types can have f = `Frac` fractional bits, where
+0 ≤ f ≤ n and n is the total number of bits. For
+example, [`FixedI32`] is a 32-bit signed fixed-point number with
+n = 32. The value x can lie in the range
+−2n − f − 1 ≤ x < 2n − f − 1
+for signed numbers, and in the range
+0 ≤ x < 2n − f for unsigned numbers. The
+difference between successive numbers is constant throughout the
+range: Δ = 2−f.
+
+When f = 0, Δ = 1 and the fixed-point number behaves
+like an n-bit integer with the value lying in the range
+−2n − 1 ≤ x < 2n − 1 for signed
+numbers, and in the range 0 ≤ x < 2n for
+unsigned numbers. When f = n,
+Δ = 2−n and the value lies in the range
−0.5 ≤ x < 0.5 for signed numbers, and in the range
0 ≤ x < 1 for unsigned numbers.
@@ -401,12 +413,42 @@ macro_rules! fixed {
$Double:ident, $DoubleInner:ty, $HasDouble:tt
) => {
comment! {
- $description,
+ $description, "-bit ",
+ if_signed_unsigned!($Signedness, "signed", "unsigned"),
" number with `Frac` fractional bits.
+The number has ", $s_nbits, " bits, of which f = `Frac` are
+fractional bits and ", $s_nbits, " − f are integer bits. The
+value x can lie in the range ",
+ if_signed_unsigned!(
+ $Signedness,
+ concat!("−2", $s_nbits_m1, " − f"),
+ "0",
+ ),
+ " ≤ x < 2",
+ if_signed_unsigned!($Signedness, $s_nbits_m1, $s_nbits),
+ " − f. The difference between successive
+numbers is constant throughout the range:
+Δ = 2−f.
+
+When f = 0, Δ = 1 and the fixed-point number behaves
+like an ", $s_nbits, "-bit integer ([`", $s_inner, "`]) with the value
+lying in the range ",
+ if_signed_unsigned!(
+ $Signedness,
+ concat!("−2", $s_nbits_m1, ""),
+ "0",
+ ),
+ " ≤ x < 2",
+ if_signed_unsigned!($Signedness, $s_nbits_m1, $s_nbits),
+ ". When f = ", $s_nbits, ",
+Δ = 2−", $s_nbits, " and the value lies in the range ",
+ if_signed_unsigned!($Signedness, "−0.5 ≤ x < 0.5", "0 ≤ x < 1"),
+ ".
+
`Frac` is an [`Unsigned`] as provided by the [*typenum* crate]; the
-plan is to move to [const generics] in version 2 when they are
-supported by the Rust compiler.
+plan is to to have a major version 2 with [const generics] instead
+when the Rust compiler support for them is powerful enough.
# Examples
@@ -482,7 +524,7 @@ assert_eq!(two_point_75.to_string(), \"2.8\");
}
fixed! {
- "An eight-bit fixed-point unsigned",
+ "An eight",
FixedU8(u8, LeEqU8, "8", "7", "6", "5", "4"),
1, "0x12", "0x12", "[0x12]", "[0x12]",
FixedU8, u8, Unsigned,
@@ -490,7 +532,7 @@ fixed! {
FixedU16, u16, True
}
fixed! {
- "A 16-bit fixed-point unsigned",
+ "A 16",
FixedU16(u16, LeEqU16, "16", "15", "14", "13", "12"),
2, "0x1234", "0x3412", "[0x12, 0x34]", "[0x34, 0x12]",
FixedU16, u16, Unsigned,
@@ -498,7 +540,7 @@ fixed! {
FixedU32, u32, True
}
fixed! {
- "A 32-bit fixed-point unsigned",
+ "A 32",
FixedU32(u32, LeEqU32, "32", "31", "30", "29", "28"),
4, "0x1234_5678", "0x7856_3412", "[0x12, 0x34, 0x56, 0x78]", "[0x78, 0x56, 0x34, 0x12]",
FixedU32, u32, Unsigned,
@@ -506,7 +548,7 @@ fixed! {
FixedU64, u64, True
}
fixed! {
- "A 64-bit fixed-point unsigned",
+ "A 64",
FixedU64(u64, LeEqU64, "64", "63", "62", "61", "60"),
8, "0x1234_5678_9ABC_DE0F", "0x0FDE_BC9A_7856_3412",
"[0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0x0F]",
@@ -516,7 +558,7 @@ fixed! {
FixedU128, u128, True
}
fixed! {
- "A 128-bit fixed-point unsigned",
+ "A 128",
FixedU128(u128, LeEqU128, "128", "127", "126", "125", "124"),
16, "0x1234_5678_9ABC_DEF0_0102_0304_0506_0708",
"0x0807_0605_0403_0201_F0DE_BC9A_7856_3412",
@@ -529,7 +571,7 @@ fixed! {
FixedU128, u128, False
}
fixed! {
- "An eight-bit fixed-point signed",
+ "An eight",
FixedI8(i8, LeEqU8, "8", "7", "6", "5", "4"),
1, "0x12", "0x12", "[0x12]", "[0x12]",
FixedU8, u8, Signed,
@@ -537,7 +579,7 @@ fixed! {
FixedI16, i16, True
}
fixed! {
- "A 16-bit fixed-point signed",
+ "A 16",
FixedI16(i16, LeEqU16, "16", "15", "14", "13", "12"),
2, "0x1234", "0x3412", "[0x12, 0x34]", "[0x34, 0x12]",
FixedU16, u16, Signed,
@@ -545,7 +587,7 @@ fixed! {
FixedI32, i32, True
}
fixed! {
- "A 32-bit fixed-point signed",
+ "A 32",
FixedI32(i32, LeEqU32, "32", "31", "30", "29", "28"),
4, "0x1234_5678", "0x7856_3412", "[0x12, 0x34, 0x56, 0x78]", "[0x78, 0x56, 0x34, 0x12]",
FixedU32, u32, Signed,
@@ -553,7 +595,7 @@ fixed! {
FixedI64, i64, True
}
fixed! {
- "A 64-bit fixed-point signed",
+ "A 64",
FixedI64(i64, LeEqU64, "64", "63", "62", "61", "60"),
8, "0x1234_5678_9ABC_DE0F", "0x0FDE_BC9A_7856_3412",
"[0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0x0F]",
@@ -563,7 +605,7 @@ fixed! {
FixedI128, i128, True
}
fixed! {
- "A 128-bit fixed-point signed",
+ "A 128",
FixedI128(i128, LeEqU128, "128", "127", "126", "125", "124"),
16, "0x1234_5678_9ABC_DEF0_0102_0304_0506_0708",
"0x0807_0605_0403_0201_F0DE_BC9A_7856_3412",
diff --git a/src/macros_no_frac.rs b/src/macros_no_frac.rs
index e381c9c..01cf3fd 100644
--- a/src/macros_no_frac.rs
+++ b/src/macros_no_frac.rs
@@ -37,6 +37,22 @@ assert_eq!(Fix::ZERO, Fix::from_bits(0));
pub const ZERO: $Fixed = Self::from_bits(0);
}
+ comment! {
+ "The difference between any two successive representable numbers, Δ.
+
+# Examples
+
+```rust
+use fixed::{types::extra::U4, ", $s_fixed, "};
+type Fix = ", $s_fixed, ";
+assert_eq!(Fix::DELTA, Fix::from_bits(1));
+// binary 0.0001 is decimal 0.0625
+assert_eq!(Fix::DELTA, 0.0625);
+```
+";
+ pub const DELTA: $Fixed = Self::from_bits(1);
+ }
+
comment! {
"The smallest value that can be represented.
@@ -65,22 +81,6 @@ assert_eq!(Fix::MAX, Fix::from_bits(", $s_inner, "::MAX));
pub const MAX: $Fixed = Self::from_bits(<$Inner>::MAX);
}
- comment! {
- "The smallest positive value that can be represented.
-
-# Examples
-
-```rust
-use fixed::{types::extra::U4, ", $s_fixed, "};
-type Fix = ", $s_fixed, ";
-assert_eq!(Fix::DELTA, Fix::from_bits(1));
-// binary 0.0001 is decimal 0.0625
-assert_eq!(Fix::DELTA, 0.0625);
-```
-";
- pub const DELTA: $Fixed = Self::from_bits(1);
- }
-
comment! {
if_signed_unsigned!($Signedness, "[`true`]", "[`false`]"),
"[`bool`] because the [`", $s_fixed, "`] type is ",
diff --git a/src/traits.rs b/src/traits.rs
index c8c75a3..1dad7e0 100644
--- a/src/traits.rs
+++ b/src/traits.rs
@@ -304,15 +304,15 @@ where
/// Zero.
const ZERO: Self;
+ /// The difference between any two successive representable numbers, Δ.
+ const DELTA: Self;
+
/// The smallest value that can be represented.
const MIN: Self;
/// The largest value that can be represented.
const MAX: Self;
- /// The smallest positive value that can be represented.
- const DELTA: Self;
-
/// [`true`] if the type is signed.
const IS_SIGNED: bool;
@@ -2258,9 +2258,9 @@ macro_rules! impl_fixed {
type Bytes = [u8; mem::size_of::<$Bits>()];
type Frac = Frac;
const ZERO: Self = Self::ZERO;
+ const DELTA: Self = Self::DELTA;
const MIN: Self = Self::MIN;
const MAX: Self = Self::MAX;
- const DELTA: Self = Self::DELTA;
const IS_SIGNED: bool = Self::IS_SIGNED;
const INT_NBITS: u32 = Self::INT_NBITS;
const FRAC_NBITS: u32 = Self::FRAC_NBITS;
diff --git a/src/unwrapped.rs b/src/unwrapped.rs
index f1a7bcc..70a0fd1 100644
--- a/src/unwrapped.rs
+++ b/src/unwrapped.rs
@@ -62,6 +62,16 @@ impl Unwrapped {
/// ```
pub const ZERO: Unwrapped = Unwrapped(F::ZERO);
+ /// The difference between any two successive representable numbers, Δ.
+ ///
+ /// # Examples
+ ///
+ /// ```rust
+ /// use fixed::{types::I16F16, Unwrapped};
+ /// assert_eq!(Unwrapped::::DELTA, Unwrapped(I16F16::DELTA));
+ /// ```
+ pub const DELTA: Unwrapped = Unwrapped(F::DELTA);
+
/// The smallest value that can be represented.
///
/// # Examples
@@ -82,16 +92,6 @@ impl Unwrapped {
/// ```
pub const MAX: Unwrapped = Unwrapped(F::MAX);
- /// The smallest positive value that can be represented.
- ///
- /// # Examples
- ///
- /// ```rust
- /// use fixed::{types::I16F16, Unwrapped};
- /// assert_eq!(Unwrapped::::DELTA, Unwrapped(I16F16::DELTA));
- /// ```
- pub const DELTA: Unwrapped = Unwrapped(F::DELTA);
-
/// [`true`] if the type is signed.
///
/// # Examples
diff --git a/src/wrapping.rs b/src/wrapping.rs
index 72f695d..48fce95 100644
--- a/src/wrapping.rs
+++ b/src/wrapping.rs
@@ -59,6 +59,16 @@ impl Wrapping {
/// ```
pub const ZERO: Wrapping = Wrapping(F::ZERO);
+ /// The difference between any two successive representable numbers, Δ.
+ ///
+ /// # Examples
+ ///
+ /// ```rust
+ /// use fixed::{types::I16F16, Wrapping};
+ /// assert_eq!(Wrapping::::DELTA, Wrapping(I16F16::DELTA));
+ /// ```
+ pub const DELTA: Wrapping = Wrapping(F::DELTA);
+
/// The smallest value that can be represented.
///
/// # Examples
@@ -79,16 +89,6 @@ impl Wrapping {
/// ```
pub const MAX: Wrapping = Wrapping(F::MAX);
- /// The smallest positive value that can be represented.
- ///
- /// # Examples
- ///
- /// ```rust
- /// use fixed::{types::I16F16, Wrapping};
- /// assert_eq!(Wrapping::::DELTA, Wrapping(I16F16::DELTA));
- /// ```
- pub const DELTA: Wrapping = Wrapping(F::DELTA);
-
/// [`true`] if the type is signed.
///
/// # Examples