diff --git a/README.md b/README.md
index ccc8e51..5197aa5 100644
--- a/README.md
+++ b/README.md
@@ -30,10 +30,9 @@ range −0.5 ≤ x < 0.5 for signed numbers like
[FixedI32]\<[U32]>
, and in the range 0 ≤ x < 1 for unsigned
numbers like [FixedU32]\<[U32]>
.
-In version 1 the [*typenum* crate] is used for the fractional bit
-count `Frac`; the plan is to to have a major version 2 with [const
-generics] instead when the Rust compiler support for them is powerful
-enough.
+In version 1 the [*typenum* crate] is used for the fractional bit count `Frac`;
+the plan is to to have a major version 2 with [const generics] instead when the
+Rust compiler support for them is powerful enough.
The main features are
@@ -46,46 +45,42 @@ The main features are
This crate does *not* provide general analytic functions.
- * No algebraic functions are provided, for example no `sqrt` or
- `pow`.
- * No trigonometric functions are provided, for example no `sin` or
- `cos`.
- * No other transcendental functions are provided, for example no
- `log` or `exp`.
+ * No algebraic functions are provided, for example no `sqrt` or `pow`.
+ * No trigonometric functions are provided, for example no `sin` or `cos`.
+ * No other transcendental functions are provided, for example no `log` or
+ `exp`.
-These functions are not provided because different implementations can
-have different trade-offs, for example trading some correctness for
-speed. Implementations can be provided in other crates.
+These functions are not provided because different implementations can have
+different trade-offs, for example trading some correctness for speed.
+Implementations can be provided in other crates.
* The [*fixed-sqrt* crate] provides the square root operation.
- * The [*cordic* crate] provides various functions implemented using
- the [CORDIC] algorithm.
+ * The [*cordic* crate] provides various functions implemented using the
+ [CORDIC] algorithm.
The conversions supported cover the following cases.
- * Infallible lossless conversions between fixed-point numbers and
- numeric primitives are provided using [`From`] and [`Into`]. These
- never fail (infallible) and do not lose any bits (lossless).
- * Infallible lossy conversions between fixed-point numbers and
- numeric primitives are provided using the [`LossyFrom`] and
- [`LossyInto`] traits. The source can have more fractional bits
- than the destination.
- * Checked lossless conversions between fixed-point numbers and
- numeric primitives are provided using the [`LosslessTryFrom`] and
- [`LosslessTryInto`] traits. The source cannot have more fractional
- bits than the destination.
- * Checked conversions between fixed-point numbers and numeric
- primitives are provided using the [`FromFixed`] and [`ToFixed`]
- traits, or using the [`from_num`] and [`to_num`] methods and
- [their checked versions][`checked_from_num`].
- * Fixed-point numbers can be parsed from decimal strings using
- [`FromStr`], and from binary, octal and hexadecimal strings using
- the [`from_str_binary`], [`from_str_octal`] and [`from_str_hex`]
- methods. The result is rounded to the nearest, with ties rounded
- to even.
+ * Infallible lossless conversions between fixed-point numbers and numeric
+ primitives are provided using [`From`] and [`Into`]. These never fail
+ (infallible) and do not lose any bits (lossless).
+ * Infallible lossy conversions between fixed-point numbers and numeric
+ primitives are provided using the [`LossyFrom`] and [`LossyInto`] traits.
+ The source can have more fractional bits than the destination.
+ * Checked lossless conversions between fixed-point numbers and numeric
+ primitives are provided using the [`LosslessTryFrom`] and
+ [`LosslessTryInto`] traits. The source cannot have more fractional bits than
+ the destination.
+ * Checked conversions between fixed-point numbers and numeric primitives are
+ provided using the [`FromFixed`] and [`ToFixed`] traits, or using the
+ [`from_num`] and [`to_num`] methods and [their checked
+ versions][`checked_from_num`].
+ * Fixed-point numbers can be parsed from decimal strings using [`FromStr`],
+ and from binary, octal and hexadecimal strings using the
+ [`from_str_binary`], [`from_str_octal`] and [`from_str_hex`] methods. The
+ result is rounded to the nearest, with ties rounded to even.
* Fixed-point numbers can be converted to strings using [`Display`],
- [`Binary`], [`Octal`], [`LowerHex`] and [`UpperHex`]. The output
- is rounded to the nearest, with ties rounded to even.
+ [`Binary`], [`Octal`], [`LowerHex`] and [`UpperHex`]. The output is rounded
+ to the nearest, with ties rounded to even.
## What’s new
@@ -96,25 +91,22 @@ The conversions supported cover the following cases.
[`Unwrapped`][u-1-8] wrappers:
* [`ZERO`][f-z-1-8], [`DELTA`][f-d-1-8]
* [`mul_acc`][f-ma-1-8]
- * The [`ONE`][f-o-1-8] constant was added to all fixed-point numbers
- that can represent the value 1.
- * The following methods were added to all fixed-point numbers and to
- the [`Fixed`][tf-1-8] trait:
+ * The [`ONE`][f-o-1-8] constant was added to all fixed-point numbers that can
+ represent the value 1.
+ * The following methods were added to all fixed-point numbers and to the
+ [`Fixed`][tf-1-8] trait:
* [`checked_mul_acc`][f-cma-1-8], [`saturating_mul_acc`][f-sma-1-8],
[`wrapping_mul_acc`][f-wma-1-8], [`unwrapped_mul_acc`][f-uma-1-8],
[`overflowing_mul_acc`][f-oma-1-8]
* [`saturating_div_euclid_int`][f-sdei-1-8],
[`saturating_rem_euclid_int`][f-srei-1-8]
- * [`unwrapped_rem`][f-ur-1-8],
- [`unwrapped_rem_euclid`][f-ure-1-8]
+ * [`unwrapped_rem`][f-ur-1-8], [`unwrapped_rem_euclid`][f-ure-1-8]
* [`unwrapped_rem_int`][f-uri-1-8]
* The following methods are now `const` functions:
* [`checked_rem`][f-cr-1-8]
* [`rem_euclid`][f-re-1-8], [`checked_rem_euclid`][f-cre-1-8]
- * [`checked_div_int`][f-cdi-1-8],
- [`wrapping_div_int`][f-wdi-1-8],
- [`unwrapped_div_int`][f-udi-1-8],
- [`overflowing_div_int`][f-odi-1-8]
+ * [`checked_div_int`][f-cdi-1-8], [`wrapping_div_int`][f-wdi-1-8],
+ [`unwrapped_div_int`][f-udi-1-8], [`overflowing_div_int`][f-odi-1-8]
* The following methods were added to all fixed-point numbers:
* [`const_not`][f-cn-1-8]
* [`const_bitand`][f-cba-1-8], [`const_bitor`][f-cbo-1-8],
@@ -157,9 +149,9 @@ The conversions supported cover the following cases.
* [`next_power_of_two`][f-npot-1-7],
[`checked_next_power_of_two`][f-cnpot-1-7],
[`wrapping_next_power_of_two`][f-wnpot-1-7]
- * The following constant and methods were added to all fixed-point
- numbers, to the [`Fixed`][tf-1-7] trait, and to the
- [`Wrapping`][w-1-7] and [`Unwrapped`][u-1-7] wrappers:
+ * The following constant and methods were added to all fixed-point numbers, to
+ the [`Fixed`][tf-1-7] trait, and to the [`Wrapping`][w-1-7] and
+ [`Unwrapped`][u-1-7] wrappers:
* [`IS_SIGNED`][f-is-1-7]
* [`from_be`][f-fb-1-7], [`from_le`][f-fl-1-7]
* [`to_be`][f-tb-1-7], [`to_le`][f-tl-1-7]
@@ -172,36 +164,33 @@ The conversions supported cover the following cases.
[`from_ne_bytes`][f-fnb-1-7]
* [`to_be_bytes`][f-tbb-1-7], [`to_le_bytes`][f-tlb-1-7],
[`to_ne_bytes`][f-tnb-1-7]
- * The following methods were added to all unsigned fixed-point
- types, to the [`FixedUnsigned`][tfu-1-7] trait, and to the
- [`Wrapping`][w-1-7] and [`Unwrapped`][u-1-7] wrappers for unsigned
- numbers:
+ * The following methods were added to all unsigned fixed-point types, to the
+ [`FixedUnsigned`][tfu-1-7] trait, and to the [`Wrapping`][w-1-7] and
+ [`Unwrapped`][u-1-7] wrappers for unsigned numbers:
* [`significant_bits`][f-signi-1-7]
* [`highest_one`][f-ho-1-7]
- * The [`signed_bits`][f-signe-1-7] method was added to all signed
- fixed-point types, to the [`FixedSigned`][tfs-1-7] trait, and to
- the [`Wrapping`][w-1-7] and [`Unwrapped`][u-1-7] wrappers for
- signed numbers.
- * The following constants, which are available in other programming
- language standard libraries, were added to the [`consts`][c-1-7]
- module and as associated constants to fixed-point types:
+ * The [`signed_bits`][f-signe-1-7] method was added to all signed fixed-point
+ types, to the [`FixedSigned`][tfs-1-7] trait, and to the [`Wrapping`][w-1-7]
+ and [`Unwrapped`][u-1-7] wrappers for signed numbers.
+ * The following constants, which are available in other programming language
+ standard libraries, were added to the [`consts`][c-1-7] module and as
+ associated constants to fixed-point types:
* [`SQRT_PI`][c-rp-1-7] (Go), [`FRAC_1_SQRT_PI`][c-1rp-1-7] (C++)
* [`SQRT_3`][c-r3-1-7] (C++), [`FRAC_1_SQRT_3`][c-1r3-1-7] (C++)
* [`SQRT_E`][c-re-1-7] (Go)
* [`SQRT_PHI`][c-rf-1-7] (Go)
* [`GAMMA`][c-g-1-7] (C++)
* [`CATALAN`][c-c-1-7] (Julia)
- * [`Sum`] and [`Product`] are now supertraits of the
- [`Fixed`][tf-1-7] trait.
- * The [`F128Bits`][f128-1-7] type was added to support conversions
- and comparisons between fixed-point numbers and *binary128*
- floating-point numbers.
+ * [`Sum`] and [`Product`] are now supertraits of the [`Fixed`][tf-1-7] trait.
+ * The [`F128Bits`][f128-1-7] type was added to support conversions and
+ comparisons between fixed-point numbers and *binary128* floating-point
+ numbers.
* The features that previously required the [`az`][feat-dep-1-7] and
- [`f16`][feat-dep-1-7] optional features are now always provided.
- The [`az`][feat-dep-1-7] and [`f16`][feat-dep-1-7] optional
- features are now deprecated and have no effect.
- * For the experimental feature [`num-traits`][feat-exp-1-7], the
- following traits were implemented for all fixed-point numbers:
+ [`f16`][feat-dep-1-7] optional features are now always provided. The
+ [`az`][feat-dep-1-7] and [`f16`][feat-dep-1-7] optional features are now
+ deprecated and have no effect.
+ * For the experimental feature [`num-traits`][feat-exp-1-7], the following
+ traits were implemented for all fixed-point numbers:
* [`OverflowingAdd`][nt-0-2-oa], [`OverflowingSub`][nt-0-2-os],
[`OverflowingMul`][nt-0-2-om]
@@ -251,10 +240,9 @@ The conversions supported cover the following cases.
### Version 1.6.0 news (2021-02-05)
* The crate now requires rustc version 1.47.0 or later.
- * The optional [*az* crate] dependency was updated to
- [version 1.1][az-1-1].
- * The [`unsigned_abs`][f-ua-1-6] method was added to all signed
- fixed-point types and to the [`FixedSigned`][tfs-1-6] trait.
+ * The optional [*az* crate] dependency was updated to [version 1.1][az-1-1].
+ * The [`unsigned_abs`][f-ua-1-6] method was added to all signed fixed-point
+ types and to the [`FixedSigned`][tfs-1-6] trait.
* The following methods are now `const` functions:
* [`checked_neg`][f-cn-1-6], [`checked_add`][f-cad-1-6],
[`checked_sub`][f-cs-1-6], [`checked_mul_int`][f-cmi-1-6],
@@ -302,12 +290,11 @@ assert_eq!(six_and_third.ceil().to_num::(), 7);
assert_eq!(six_and_third.ceil(), 7);
```
-The type [`I20F12`] is a 32-bit fixed-point signed number with 20
-integer bits and 12 fractional bits. It is an alias to
-[FixedI32][`FixedI32`]<[U12][`U12`]>
. The unsigned
-counterpart would be [`U20F12`]. Aliases are provided for all
-combinations of integer and fractional bits adding up to a total of
-eight, 16, 32, 64 or 128 bits.
+The type [`I20F12`] is a 32-bit fixed-point signed number with 20 integer bits
+and 12 fractional bits. It is an alias to [FixedI32]\<[U12]>
. The
+unsigned counterpart would be [`U20F12`]. Aliases are provided for all
+combinations of integer and fractional bits adding up to a total of eight, 16,
+32, 64 or 128 bits.
```rust
use fixed::types::{I4F4, I4F12};
@@ -329,23 +316,22 @@ assert_eq!(ans2, I4F4::from_bits((3 << 4) + 6));
assert_eq!(ans2.to_string(), "3.4");
```
-The second example shows some precision and conversion issues. The low
-precision of `a` means that `a / 5` is 3⁄16 instead of 1⁄5, leading to
-an inaccurate result `ans1` = 3 3⁄16 (~3.2). With a higher precision,
-we get `wider_a / 5` equal to 819⁄4096, leading to a more accurate
-intermediate result `wider_ans` = 3 1635⁄4096. When we convert back to
-four fractional bits, we get `ans2` = 3 6⁄16 (~3.4).
+The second example shows some precision and conversion issues. The low precision
+of `a` means that `a / 5` is 3⁄16 instead of 1⁄5, leading to an inaccurate
+result `ans1` = 3 3⁄16 (~3.2). With a higher precision, we get `wider_a / 5`
+equal to 819⁄4096, leading to a more accurate intermediate result `wider_ans` =
+3 1635⁄4096. When we convert back to four fractional bits, we get `ans2` = 3
+6⁄16 (~3.4).
-Note that we can convert from [`I4F4`] to [`I4F12`] using [`From`], as
-the target type has the same number of integer bits and a larger
-number of fractional bits. Converting from [`I4F12`] to [`I4F4`]
-cannot use [`From`] as we have less fractional bits, so we use
-[`from_num`] instead.
+Note that we can convert from [`I4F4`] to [`I4F12`] using [`From`], as the
+target type has the same number of integer bits and a larger number of
+fractional bits. Converting from [`I4F12`] to [`I4F4`] cannot use [`From`] as we
+have less fractional bits, so we use [`from_num`] instead.
## Writing fixed-point constants and values literally
-The [*fixed-macro* crate] provides a convenient macro to write down
-fixed-point constants literally in the code.
+The [*fixed-macro* crate] provides a convenient macro to write down fixed-point
+constants literally in the code.
```rust
use fixed::types::I16F16;
@@ -358,8 +344,8 @@ assert_eq!(num2, 25.875);
## Using the *fixed* crate
-The *fixed* crate is available on [crates.io][*fixed* crate]. To use
-it in your crate, add it as a dependency inside [*Cargo.toml*]:
+The *fixed* crate is available on [crates.io][*fixed* crate]. To use it in your
+crate, add it as a dependency inside [*Cargo.toml*]:
```toml
[dependencies]
@@ -372,21 +358,18 @@ The *fixed* crate requires rustc version 1.50.0 or later.
The *fixed* crate has these optional feature:
- 1. `serde`, disabled by default. This provides serialization support
- for the fixed-point types. This feature requires the
- [*serde* crate].
- 2. `std`, disabled by default. This is for features that are not
- possible under `no_std`: currently the implementation of the
- [`Error`] trait for [`ParseFixedError`].
- 3. `serde-str`, disabled by default. Fixed-point numbers are
- serialized as strings showing the value when using human-readable
- formats. This feature requires the `serde` and the `std` optional
- features. **Warning:** numbers serialized when this feature is
- enabled cannot be deserialized when this feature is disabled, and
- vice versa.
+ 1. `serde`, disabled by default. This provides serialization support for the
+ fixed-point types. This feature requires the [*serde* crate].
+ 2. `std`, disabled by default. This is for features that are not possible under
+ `no_std`: currently the implementation of the [`Error`] trait for
+ [`ParseFixedError`].
+ 3. `serde-str`, disabled by default. Fixed-point numbers are serialized as
+ strings showing the value when using human-readable formats. This feature
+ requires the `serde` and the `std` optional features. **Warning:** numbers
+ serialized when this feature is enabled cannot be deserialized when this
+ feature is disabled, and vice versa.
-To enable features, you can add the dependency like this to
-[*Cargo.toml*]:
+To enable features, you can add the dependency like this to [*Cargo.toml*]:
```toml
[dependencies.fixed]
@@ -396,33 +379,29 @@ features = ["serde"]
## Experimental optional features
-It is not considered a breaking change if the following experimental
-features are removed. The removal of experimental features would
-however require a minor version bump. Similarly, on a minor version
-bump, optional dependencies can be updated to an incompatible newer
-version.
+It is not considered a breaking change if the following experimental features
+are removed. The removal of experimental features would however require a minor
+version bump. Similarly, on a minor version bump, optional dependencies can be
+updated to an incompatible newer version.
- 1. `num-traits`, disabled by default. This implements some traits
- from the [*num-traits* crate]. (The plan is to promote this to an
- optional feature once the [*num-traits* crate] reaches version
- 1.0.0.)
+ 1. `num-traits`, disabled by default. This implements some traits from the
+ [*num-traits* crate]. (The plan is to promote this to an optional feature
+ once the [*num-traits* crate] reaches version 1.0.0.)
## Deprecated optional features
-The following optional features are deprecated and may be removed in
-the next major version of the crate.
+The following optional features are deprecated and may be removed in the next
+major version of the crate.
- 1. `az`, has no effect. Previously required to enable the cast traits
- provided by the [*az* crate]. Now these cast traits are always
- provided.
- 2. `f16`, has no effect. Previously required to provide conversion
- to/from [`f16`] and [`bf16`]. Now these conversions are always
- provided.
+ 1. `az`, has no effect. Previously required to enable the cast traits provided
+ by the [*az* crate]. Now these cast traits are always provided.
+ 2. `f16`, has no effect. Previously required to provide conversion to/from
+ [`f16`] and [`bf16`]. Now these conversions are always provided.
## License
-This crate is free software: you can redistribute it and/or modify it
-under the terms of either
+This crate is free software: you can redistribute it and/or modify it under the
+terms of either
* the [Apache License, Version 2.0][LICENSE-APACHE] or
* the [MIT License][LICENSE-MIT]
@@ -431,10 +410,9 @@ at your option.
### Contribution
-Unless you explicitly state otherwise, any contribution intentionally
-submitted for inclusion in the work by you, as defined in the Apache
-License, Version 2.0, shall be dual licensed as above, without any
-additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache License, Version 2.0,
+shall be dual licensed as above, without any additional terms or conditions.
[*Cargo.toml*]: https://doc.rust-lang.org/cargo/guide/dependencies.html
[*az* crate]: https://crates.io/crates/az
@@ -452,6 +430,7 @@ additional terms or conditions.
[LICENSE-APACHE]: https://www.apache.org/licenses/LICENSE-2.0
[LICENSE-MIT]: https://opensource.org/licenses/MIT
[U0]: https://docs.rs/fixed/~1.7/fixed/types/extra/type.U0.html
+[U12]: https://docs.rs/fixed/~1.7/fixed/types/extra/type.U12.html
[U32]: https://docs.rs/fixed/~1.7/fixed/types/extra/type.U32.html
[`Binary`]: https://doc.rust-lang.org/nightly/core/fmt/trait.Binary.html
[`Display`]: https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html
@@ -481,7 +460,6 @@ additional terms or conditions.
[`Octal`]: https://doc.rust-lang.org/nightly/core/fmt/trait.Octal.html
[`ParseFixedError`]: https://docs.rs/fixed/~1.7/fixed/struct.ParseFixedError.html
[`ToFixed`]: https://docs.rs/fixed/~1.7/fixed/traits/trait.ToFixed.html
-[`U12`]: https://docs.rs/fixed/~1.7/fixed/types/extra/type.U12.html
[`U20F12`]: https://docs.rs/fixed/~1.7/fixed/types/type.U20F12.html
[`UpperHex`]: https://doc.rust-lang.org/nightly/core/fmt/trait.UpperHex.html
[`bf16`]: https://docs.rs/half/^1/half/struct.bf16.html
diff --git a/RELEASES.md b/RELEASES.md
index 04a4a14..b489c0f 100644
--- a/RELEASES.md
+++ b/RELEASES.md
@@ -8,30 +8,27 @@ as-is, without any warranty. -->
Version 1.8.0 (unreleased)
==========================
- * The following constants were added to all fixed-point numbers, to
- the [`Fixed`][tf-1-8] trait, and to the [`Wrapping`][w-1-8] and
+ * The following constants were added to all fixed-point numbers, to the
+ [`Fixed`][tf-1-8] trait, and to the [`Wrapping`][w-1-8] and
[`Unwrapped`][u-1-8] wrappers:
* [`ZERO`][f-z-1-8], [`DELTA`][f-d-1-8]
* [`mul_acc`][f-ma-1-8]
- * The [`ONE`][f-o-1-8] constant was added to all fixed-point numbers
- that can represent the value 1.
- * The following methods were added to all fixed-point numbers and to
- the [`Fixed`][tf-1-8] trait:
+ * The [`ONE`][f-o-1-8] constant was added to all fixed-point numbers that can
+ represent the value 1.
+ * The following methods were added to all fixed-point numbers and to the
+ [`Fixed`][tf-1-8] trait:
* [`checked_mul_acc`][f-cma-1-8], [`saturating_mul_acc`][f-sma-1-8],
[`wrapping_mul_acc`][f-wma-1-8], [`unwrapped_mul_acc`][f-uma-1-8],
[`overflowing_mul_acc`][f-oma-1-8]
* [`saturating_div_euclid_int`][f-sdei-1-8],
[`saturating_rem_euclid_int`][f-srei-1-8]
- * [`unwrapped_rem`][f-ur-1-8],
- [`unwrapped_rem_euclid`][f-ure-1-8]
+ * [`unwrapped_rem`][f-ur-1-8], [`unwrapped_rem_euclid`][f-ure-1-8]
* [`unwrapped_rem_int`][f-uri-1-8]
* The following methods are now `const` functions:
* [`checked_rem`][f-cr-1-8]
* [`rem_euclid`][f-re-1-8], [`checked_rem_euclid`][f-cre-1-8]
- * [`checked_div_int`][f-cdi-1-8],
- [`wrapping_div_int`][f-wdi-1-8],
- [`unwrapped_div_int`][f-udi-1-8],
- [`overflowing_div_int`][f-odi-1-8]
+ * [`checked_div_int`][f-cdi-1-8], [`wrapping_div_int`][f-wdi-1-8],
+ [`unwrapped_div_int`][f-udi-1-8], [`overflowing_div_int`][f-odi-1-8]
* The following methods were added to all fixed-point numbers:
* [`const_not`][f-cn-1-8]
* [`const_bitand`][f-cba-1-8], [`const_bitor`][f-cbo-1-8],
@@ -75,9 +72,9 @@ Version 1.7.0 (2021-03-25)
* [`next_power_of_two`][f-npot-1-7],
[`checked_next_power_of_two`][f-cnpot-1-7],
[`wrapping_next_power_of_two`][f-wnpot-1-7]
- * The following constant and methods were added to all fixed-point
- numbers, to the [`Fixed`][tf-1-7] trait, and to the
- [`Wrapping`][w-1-7] and [`Unwrapped`][u-1-7] wrappers:
+ * The following constant and methods were added to all fixed-point numbers, to
+ the [`Fixed`][tf-1-7] trait, and to the [`Wrapping`][w-1-7] and
+ [`Unwrapped`][u-1-7] wrappers:
* [`IS_SIGNED`][f-is-1-7]
* [`from_be`][f-fb-1-7], [`from_le`][f-fl-1-7]
* [`to_be`][f-tb-1-7], [`to_le`][f-tl-1-7]
@@ -90,36 +87,33 @@ Version 1.7.0 (2021-03-25)
[`from_ne_bytes`][f-fnb-1-7]
* [`to_be_bytes`][f-tbb-1-7], [`to_le_bytes`][f-tlb-1-7],
[`to_ne_bytes`][f-tnb-1-7]
- * The following methods were added to all unsigned fixed-point
- types, to the [`FixedUnsigned`][tfu-1-7] trait, and to the
- [`Wrapping`][w-1-7] and [`Unwrapped`][u-1-7] wrappers for unsigned
- numbers:
+ * The following methods were added to all unsigned fixed-point types, to the
+ [`FixedUnsigned`][tfu-1-7] trait, and to the [`Wrapping`][w-1-7] and
+ [`Unwrapped`][u-1-7] wrappers for unsigned numbers:
* [`significant_bits`][f-signi-1-7]
* [`highest_one`][f-ho-1-7]
- * The [`signed_bits`][f-signe-1-7] method was added to all signed
- fixed-point types, to the [`FixedSigned`][tfs-1-7] trait, and to
- the [`Wrapping`][w-1-7] and [`Unwrapped`][u-1-7] wrappers for
- signed numbers.
- * The following constants, which are available in other programming
- language standard libraries, were added to the [`consts`][c-1-7]
- module and as associated constants to fixed-point types:
+ * The [`signed_bits`][f-signe-1-7] method was added to all signed fixed-point
+ types, to the [`FixedSigned`][tfs-1-7] trait, and to the [`Wrapping`][w-1-7]
+ and [`Unwrapped`][u-1-7] wrappers for signed numbers.
+ * The following constants, which are available in other programming language
+ standard libraries, were added to the [`consts`][c-1-7] module and as
+ associated constants to fixed-point types:
* [`SQRT_PI`][c-rp-1-7] (Go), [`FRAC_1_SQRT_PI`][c-1rp-1-7] (C++)
* [`SQRT_3`][c-r3-1-7] (C++), [`FRAC_1_SQRT_3`][c-1r3-1-7] (C++)
* [`SQRT_E`][c-re-1-7] (Go)
* [`SQRT_PHI`][c-rf-1-7] (Go)
* [`GAMMA`][c-g-1-7] (C++)
* [`CATALAN`][c-c-1-7] (Julia)
- * [`Sum`] and [`Product`] are now supertraits of the
- [`Fixed`][tf-1-7] trait.
- * The [`F128Bits`][f128-1-7] type was added to support conversions
- and comparisons between fixed-point numbers and *binary128*
- floating-point numbers.
+ * [`Sum`] and [`Product`] are now supertraits of the [`Fixed`][tf-1-7] trait.
+ * The [`F128Bits`][f128-1-7] type was added to support conversions and
+ comparisons between fixed-point numbers and *binary128* floating-point
+ numbers.
* The features that previously required the [`az`][feat-dep-1-7] and
- [`f16`][feat-dep-1-7] optional features are now always provided.
- The [`az`][feat-dep-1-7] and [`f16`][feat-dep-1-7] optional
- features are now deprecated and have no effect.
- * For the experimental feature [`num-traits`][feat-exp-1-7], the
- following traits were implemented for all fixed-point numbers:
+ [`f16`][feat-dep-1-7] optional features are now always provided. The
+ [`az`][feat-dep-1-7] and [`f16`][feat-dep-1-7] optional features are now
+ deprecated and have no effect.
+ * For the experimental feature [`num-traits`][feat-exp-1-7], the following
+ traits were implemented for all fixed-point numbers:
* [`OverflowingAdd`][nt-0-2-oa], [`OverflowingSub`][nt-0-2-os],
[`OverflowingMul`][nt-0-2-om]
@@ -168,10 +162,9 @@ Version 1.6.0 (2021-02-05)
==========================
* The crate now requires rustc version 1.47.0 or later.
- * The optional [*az* crate] dependency was updated to
- [version 1.1][az-1-1].
- * The [`unsigned_abs`][f-ua-1-6] method was added to all signed
- fixed-point types and to the [`FixedSigned`][tfs-1-6] trait.
+ * The optional [*az* crate] dependency was updated to [version 1.1][az-1-1].
+ * The [`unsigned_abs`][f-ua-1-6] method was added to all signed fixed-point
+ types and to the [`FixedSigned`][tfs-1-6] trait.
* The following methods are now `const` functions:
* [`checked_neg`][f-cn-1-6], [`checked_add`][f-cad-1-6],
[`checked_sub`][f-cs-1-6], [`checked_mul_int`][f-cmi-1-6],
@@ -200,21 +193,19 @@ Version 1.6.0 (2021-02-05)
Version 1.5.0 (2020-11-05)
==========================
- * The [`wide_mul`][f-wm-1-5] method was added to all fixed-point
- numbers up to 64 bits wide ([issue 25]).
- * Unwrapped methods for arithmetic together with the
- [`Unwrapped`][unw-1-5] wrapper were added. Unwrapped methods panic
- on overflow, even when debug assertions are disabled, similar to
- how wrapping methods will wrap around even when debug assertions
- are enabled. (This was previously an experimental feature
- `unwrapped`.)
- * The [`serde-str`][feat-1-5] feature was added. (This was
- previously an experimental feature.)
- * For the experimental feature [`num-traits`][feat-exp-1-5], some
- missing supertraits were added to
- [`FixedOptionalFeatures`][tfof-1-5].
- * Bug fix: multiplication of [`FixedI128`][i128-1-5] was panicking
- when multiplying some large negative numbers ([issue 26]).
+ * The [`wide_mul`][f-wm-1-5] method was added to all fixed-point numbers up to
+ 64 bits wide ([issue 25]).
+ * Unwrapped methods for arithmetic together with the [`Unwrapped`][unw-1-5]
+ wrapper were added. Unwrapped methods panic on overflow, even when debug
+ assertions are disabled, similar to how wrapping methods will wrap around
+ even when debug assertions are enabled. (This was previously an experimental
+ feature `unwrapped`.)
+ * The [`serde-str`][feat-1-5] feature was added. (This was previously an
+ experimental feature.)
+ * For the experimental feature [`num-traits`][feat-exp-1-5], some missing
+ supertraits were added to [`FixedOptionalFeatures`][tfof-1-5].
+ * Bug fix: multiplication of [`FixedI128`][i128-1-5] was panicking when
+ multiplying some large negative numbers ([issue 26]).
[i128-1-5]: https://docs.rs/fixed/~1.5/fixed/struct.FixedI128.html
[f-wm-1-5]: https://docs.rs/fixed/~1.5/fixed/struct.FixedI32.html#method.wide_mul
@@ -231,21 +222,19 @@ Version 1.4.0 (2020-10-22)
* The following methods were added to all fixed-point types, to the
[`Fixed`][tf-1-4] trait, and to the [`Wrapping`][w-1-4] wrapper:
* [`recip`][f-rec-1-4], [`checked_recip`][f-crec-1-4],
- [`saturating_recip`][f-srec-1-4],
- [`wrapping_recip`][f-wrec-1-4],
+ [`saturating_recip`][f-srec-1-4], [`wrapping_recip`][f-wrec-1-4],
[`overflowing_recip`][f-orec-1-4]
- * For the experimental feature [`num-traits`][feat-exp-1-4], the
- following traits were implemented where applicable ([issue 23]):
+ * For the experimental feature [`num-traits`][feat-exp-1-4], the following
+ traits were implemented where applicable ([issue 23]):
* [`Num`][nt-0-2-num]
* [`Signed`][nt-0-2-signed], [`Unsigned`][nt-0-2-unsigned]
* [`Inv`][nt-0-2-inv]
* [`MulAdd`][nt-0-2-ma], [`MulAddAssign`][nt-0-2-maa]
* [`FloatConst`][nt-0-2-fc]
* [`ToPrimitive`][nt-0-2-tp], [`FromPrimitive`][nt-0-2-fp]
- * For the experimental feature [`serde-str`][feat-exp-1-4],
- serialization in human-readable formats was made more convenient
- to write manually ([issue 24]). This makes it incompatible with
- the version in 1.3.0.
+ * For the experimental feature [`serde-str`][feat-exp-1-4], serialization in
+ human-readable formats was made more convenient to write manually ([issue
+ 24]). This makes it incompatible with the version in 1.3.0.
[f-crec-1-4]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.checked_recip
[f-orec-1-4]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.overflowing_recip
@@ -270,21 +259,18 @@ Version 1.4.0 (2020-10-22)
Version 1.3.0 (2020-10-15)
==========================
- * The [`MulAssign`] implementation on fixed-point numbers now
- accepts an rhs fixed-point number with a different number of
- fractional bits from `self`.
+ * The [`MulAssign`] implementation on fixed-point numbers now accepts an rhs
+ fixed-point number with a different number of fractional bits from `self`.
* The following methods were added to all fixed-point types, to the
[`Fixed`][tf-1-3] trait, and to the [`Wrapping`][w-1-3] wrapper:
* [`mul_add`][f-ma-1-3], [`checked_mul_add`][f-cma-1-3],
- [`saturating_mul_add`][f-sma-1-3],
- [`wrapping_mul_add`][f-wma-1-3],
+ [`saturating_mul_add`][f-sma-1-3], [`wrapping_mul_add`][f-wma-1-3],
[`overflowing_mul_add`][f-oma-1-3]
- * The new experimental feature [`unwrapped`][feat-exp-1-3] was
- added, providing arithmetic methods that panic on overflow even
- when debug assertions are disabled.
- * The new experimental feature [`serde-str`][feat-exp-1-3] was
- added, which makes serialization use the number’s value in
- human-readable formats.
+ * The new experimental feature [`unwrapped`][feat-exp-1-3] was added,
+ providing arithmetic methods that panic on overflow even when debug
+ assertions are disabled.
+ * The new experimental feature [`serde-str`][feat-exp-1-3] was added, which
+ makes serialization use the number’s value in human-readable formats.
[f-cma-1-3]: https://docs.rs/fixed/~1.3/fixed/struct.FixedI32.html#method.checked_mul_add
[f-ma-1-3]: https://docs.rs/fixed/~1.3/fixed/struct.FixedI32.html#method.mul_add
@@ -298,9 +284,8 @@ Version 1.3.0 (2020-10-15)
Version 1.2.0 (2020-09-02)
==========================
- * The [`const_fixed_from_int!`][cffi-1-2] macro was added to make it
- easy to define constant fixed-point numbers using integer
- expressions ([issue 20]).
+ * The [`const_fixed_from_int!`][cffi-1-2] macro was added to make it easy to
+ define constant fixed-point numbers using integer expressions ([issue 20]).
[cffi-1-2]: https://docs.rs/fixed/~1.2/fixed/macro.const_fixed_from_int.html
[issue 20]: https://gitlab.com/tspiteri/fixed/-/issues/20
@@ -308,10 +293,9 @@ Version 1.2.0 (2020-09-02)
Version 1.1.0 (2020-07-21)
==========================
- * The new experimental feature [`num-traits`][feat-nt-1-1] was added
- to implement some traits, and to also add the relevant traits as
- supertraits to the [`FixedOptionalFeatures`][fof-1-1] trait
- ([issue 18]).
+ * The new experimental feature [`num-traits`][feat-nt-1-1] was added to
+ implement some traits, and to also add the relevant traits as supertraits to
+ the [`FixedOptionalFeatures`][fof-1-1] trait ([issue 18]).
[issue 18]: https://gitlab.com/tspiteri/fixed/-/issues/18
[feat-nt-1-1]: https://docs.rs/fixed/~1.1/fixed/#experimental-optional-features
@@ -339,20 +323,20 @@ Version 0.5.7 (2020-05-11)
==========================
* The `LosslessTryFrom` and `LosslessTryInto` traits were added.
- * The following methods were added to all fixed-point types, to the
- `Fixed` trait, and to the `Wrapping` wrapper:
+ * The following methods were added to all fixed-point types, to the `Fixed`
+ trait, and to the `Wrapping` wrapper:
* `leading_ones`, `trailing_ones`
- * The following method was added to unsigned fixed-point types and
- to the `FixedUnsigned` trait:
+ * The following method was added to unsigned fixed-point types and to the
+ `FixedUnsigned` trait:
* `wrapping_next_power_of_two`
- * The `PHI` and `FRAC_1_PHI` constants were added to the `consts`
- module and as associated constants to fixed-point types.
+ * The `PHI` and `FRAC_1_PHI` constants were added to the `consts` module and
+ as associated constants to fixed-point types.
Version 0.5.6 (2020-05-01)
==========================
- * The following methods were added to signed fixed-point types and to
- the `FixedSigned` trait:
+ * The following methods were added to signed fixed-point types and to the
+ `FixedSigned` trait:
* `checked_signum`, `saturating_signum`, `wrapping_signum`,
`overflowing_signum`
* The `LossyFrom` and `LossyInto` traits were added to the prelude.
@@ -362,23 +346,23 @@ Version 0.5.6 (2020-05-01)
Version 0.5.5 (2020-04-16)
==========================
- * Bug fix: an incorrect result could be given when comparing a
- signed fixed-point number of type `FixedI` to a number that would
- overflow by exactly one bit when converting to `FixedI`.
- * The following associated constants were added to all fixed-point
- types, to the `Fixed` trait, and to the `Wrapping` wrapper:
+ * Bug fix: an incorrect result could be given when comparing a signed
+ fixed-point number of type `FixedI` to a number that would overflow by
+ exactly one bit when converting to `FixedI`.
+ * The following associated constants were added to all fixed-point types, to
+ the `Fixed` trait, and to the `Wrapping` wrapper:
* `MIN`, `MAX`
- * The following associated constants were added to the `Fixed` trait
- and to the `Wrapping` wrapper:
+ * The following associated constants were added to the `Fixed` trait and to
+ the `Wrapping` wrapper:
* `INT_NBITS`, `FRAC_NBITS`
- * The following methods were added to all fixed-point types and to
- the `Fixed` trait:
+ * The following methods were added to all fixed-point types and to the `Fixed`
+ trait:
* `int_log2`, `int_log10`
* `checked_int_log2`, `checked_int_log10`
* The following methods were added to the `Wrapping` wrapper:
* `int_log2`, `int_log10`
- * The constants in the `consts` module were also added as associated
- constants to fixed-point types that can represent them.
+ * The constants in the `consts` module were also added as associated constants
+ to fixed-point types that can represent them.
* The following methods were deprecated:
* `min_value`, `max_value`
* `int_nbits`, `frac_nbits`
@@ -386,22 +370,22 @@ Version 0.5.5 (2020-04-16)
Version 0.5.4 (2020-02-21)
==========================
- * Bug fix: `rem_euclid_int` and its checked versions were handling
- overflow incorrectly.
+ * Bug fix: `rem_euclid_int` and its checked versions were handling overflow
+ incorrectly.
Version 0.5.3 (2020-02-13)
==========================
- * Bug fix: `round_to_zero` was returning incorrect results for
- negative whole number operands.
- * Bug fix: all remainder operations with a fixed-point LHS and an
- integer RHS were giving an incorrect answer
+ * Bug fix: `round_to_zero` was returning incorrect results for negative whole
+ number operands.
+ * Bug fix: all remainder operations with a fixed-point LHS and an integer RHS
+ were giving an incorrect answer
(https://gitlab.com/tspiteri/fixed/issues/13).
- * Bug fix: Euclidean division operations by integers were giving an
- incorrect answer.
+ * Bug fix: Euclidean division operations by integers were giving an incorrect
+ answer.
* `Rem` and `RemAssign` were implemented for fixed-point numbers.
- * The following methods were added to all fixed-point types and to
- the `Fixed` trait:
+ * The following methods were added to all fixed-point types and to the `Fixed`
+ trait:
* `checked_rem`
* `div_euclid`, `rem_euclid`
* `checked_div_euclid`, `checked_rem_euclid`
@@ -422,15 +406,14 @@ Version 0.5.2 (2020-02-02)
Version 0.5.1 (2019-12-22)
==========================
- * `ParseFixedError` implements `Error` when the new `std` feature is
- enabled.
+ * `ParseFixedError` implements `Error` when the new `std` feature is enabled.
Version 0.5.0 (2019-12-06)
==========================
* The crate now requires rustc version 1.39.0 or later.
- * The following methods were added to all fixed-point types and to
- the `Fixed` trait:
+ * The following methods were added to all fixed-point types and to the `Fixed`
+ trait:
* `from_be_bytes`, `from_le_bytes`, `from_ne_bytes`
* `to_be_bytes`, `to_le_bytes`, `to_ne_bytes`
* `div_euclid_int`, `rem_euclid_int`
@@ -448,99 +431,92 @@ Incompatible changes
Version 0.4.6 (2019-10-16)
==========================
- * Conversions to/from `bf16` are now provided when the `f16` option
- is enabled.
+ * Conversions to/from `bf16` are now provided when the `f16` option is
+ enabled.
* The following methods are now `const` functions: `saturating_neg`,
- `saturating_add`, `saturating_sub`, `saturating_mul_int`,
- `saturating_abs`
+ `saturating_add`, `saturating_sub`, `saturating_mul_int`, `saturating_abs`
* Support for casts using the *az* crate was added.
Version 0.4.5 (2019-08-30)
==========================
- * Bug fix: display of many decimal numbers was panicking in debug
- mode or including a leading zero in release mode.
- * Many methods were added to `Wrapping` for convenience, even if
- they do not involve wrapping.
+ * Bug fix: display of many decimal numbers was panicking in debug mode or
+ including a leading zero in release mode.
+ * Many methods were added to `Wrapping` for convenience, even if they do not
+ involve wrapping.
Version 0.4.4 (2019-08-24)
==========================
- * Bug fix: rounding could produce bad output for `Binary`, `Octal`,
- `LowerHex` and `UpperHex`.
- * The following methods are now `const` functions:
- `is_power_of_two`, `abs`, `wrapping_abs`, `overflowing_abs`
+ * Bug fix: rounding could produce bad output for `Binary`, `Octal`, `LowerHex`
+ and `UpperHex`.
+ * The following methods are now `const` functions: `is_power_of_two`, `abs`,
+ `wrapping_abs`, `overflowing_abs`
* The method `round_to_zero` was added.
- * The method `round_ties_to_even` and its checked versions were
- added.
+ * The method `round_ties_to_even` and its checked versions were added.
Version 0.4.3 (2019-08-20)
==========================
* The crate now requires rustc version 1.34.0 or later.
- * The precision argument is no longer ignored when formatting
- fixed-point numbers; precision should now be handled the same as
- for primitive floating-point numbers in the standard library.
- * Parsing strings now rounds to the nearest with ties rounded to
- even.
- * Checked versions of string parsing methods are now available as
- inherent methods to all fixed-point numbers, and as methods in the
- `Fixed` trait.
- * `Wrapping` now has methods for parsing with wrapping, including
- an implementation of `FromStr`.
+ * The precision argument is no longer ignored when formatting fixed-point
+ numbers; precision should now be handled the same as for primitive
+ floating-point numbers in the standard library.
+ * Parsing strings now rounds to the nearest with ties rounded to even.
+ * Checked versions of string parsing methods are now available as inherent
+ methods to all fixed-point numbers, and as methods in the `Fixed` trait.
+ * `Wrapping` now has methods for parsing with wrapping, including an
+ implementation of `FromStr`.
* The following methods are now `const` functions:
* `min_value`, `max_value`, `from_bits`, `to_bits`
* `count_ones`, `count_zeros`, `leading_zeros`, `trailing_zeros`
`rotate_left`, `rotate_right`
- * `wrapping_neg`, `wrapping_add`, `wrapping_sub`,
- `wrapping_mul_int`, `wrapping_shl`, `wrapping_shr`
+ * `wrapping_neg`, `wrapping_add`, `wrapping_sub`, `wrapping_mul_int`,
+ `wrapping_shl`, `wrapping_shr`
* `overflowing_neg`, `overflowing_add`, `overflowing_sub`,
`overflowing_mul_int`, `overflowing_shl`, `overflowing_shr`
* `is_positive`, `is_negative`
* The associated constants `INT_NBITS` and `FRAC_NBITS` were added.
- * The reexports in the `frac` module and the `LeEqU*` traits were
- moved into the new `types::extra` module.
+ * The reexports in the `frac` module and the `LeEqU*` traits were moved into
+ the new `types::extra` module.
Version 0.4.2 (2019-08-16)
==========================
- * The new methods `from_num` and `to_num` together with their
- checked versions were added to all fixed-point numbers.
- * The methods `from_fixed`, `to_fixed`, `from_int`, `to_int`,
- `from_float`, and `to_float`, and their checked versions, were
- deprecated.
+ * The new methods `from_num` and `to_num` together with their checked versions
+ were added to all fixed-point numbers.
+ * The methods `from_fixed`, `to_fixed`, `from_int`, `to_int`, `from_float`,
+ and `to_float`, and their checked versions, were deprecated.
* The new method `from_num` was added to the `Wrapping` wrapper.
- * Bug fix: parsing of decimal fractions was fixed to give correctly
- rounded results for long decimal fraction strings, for example
- with four fractional bits, 0.96874999… (just below 31⁄32) and
- 0.96875 (31⁄32) are now parsed correctly as 0.9375 (15⁄16) and 1.0.
+ * Bug fix: parsing of decimal fractions was fixed to give correctly rounded
+ results for long decimal fraction strings, for example with four fractional
+ bits, 0.96874999… (just below 31⁄32) and 0.96875 (31⁄32) are now parsed
+ correctly as 0.9375 (15⁄16) and 1.0.
Version 0.4.1 (2019-08-12)
==========================
* All fixed-point types now implement `FromStr`.
- * The methods `from_str_binary`, `from_str_octal` and `from_str_hex`
- were added.
+ * The methods `from_str_binary`, `from_str_octal` and `from_str_hex` were
+ added.
Version 0.4.0 (2019-08-08)
==========================
* The crate now requires rustc version 1.31.0 or later.
- * The `traits` module was added, with its traits `Fixed`,
- `FixedSigned`, `FixedUnsigned`, `FromFixed`, `ToFixed`,
- `LossyFrom` and `LossyInto`.
- * The `saturating_neg` method was added to all fixed-point numbers,
- and the `saturating_abs` method was added to signed fixed-point
- numbers.
+ * The `traits` module was added, with its traits `Fixed`, `FixedSigned`,
+ `FixedUnsigned`, `FromFixed`, `ToFixed`, `LossyFrom` and `LossyInto`.
+ * The `saturating_neg` method was added to all fixed-point numbers, and the
+ `saturating_abs` method was added to signed fixed-point numbers.
* The `consts` module was added.
* The `signum` method now wraps instead of panics in release mode.
Incompatible changes
--------------------
- * The sealed traits `Int` and `Float` now have no provided methods;
- the methods in the old implementation are now provided by
- `FromFixed` and `ToFixed`.
+ * The sealed traits `Int` and `Float` now have no provided methods; the
+ methods in the old implementation are now provided by `FromFixed` and
+ `ToFixed`.
* Deprecated methods were removed.
Contributors
@@ -562,65 +538,57 @@ Version 0.3.2 (2019-02-27)
Version 0.3.1 (2019-02-07)
==========================
- * Reimplement `From` for all fixed-point types which can
- represent the integer 1. This was inadvertently removed in 0.3.0.
+ * Reimplement `From` for all fixed-point types which can represent the
+ integer 1. This was inadvertently removed in 0.3.0.
Version 0.3.0 (2019-02-03)
==========================
* Incompatible change: the return type of `to_int` is now generic.
- * Incompatible change: the `Int` trait implementation for `bool` was
- removed.
+ * Incompatible change: the `Int` trait implementation for `bool` was removed.
* The new method `to_fixed` was added.
- * The new methods `checked_to_fixed`, `checked_to_int`,
- `saturating_to_fixed`, `saturating_to_int`, `wrapping_to_fixed`,
- `wrapping_to_int`, `overflowing_to_fixed` and `overflowing_to_int`
- were added.
+ * The new methods `checked_to_fixed`, `checked_to_int`, `saturating_to_fixed`,
+ `saturating_to_int`, `wrapping_to_fixed`, `wrapping_to_int`,
+ `overflowing_to_fixed` and `overflowing_to_int` were added.
* The methods `from_fixed`, `to_fixed`, `checked_from_fixed`,
- `checked_to_fixed`, `saturating_from_fixed`,
- `saturating_to_fixed`, `wrapping_from_fixed`, `wrapping_to_fixed`,
- `overflowing_from_fixed` and `overflowing_to_fixed` were added to
- the `Int` trait.
+ `checked_to_fixed`, `saturating_from_fixed`, `saturating_to_fixed`,
+ `wrapping_from_fixed`, `wrapping_to_fixed`, `overflowing_from_fixed` and
+ `overflowing_to_fixed` were added to the `Int` trait.
* The methods `from_fixed`, `to_fixed`, `checked_to_fixed`,
- `saturating_to_fixed`, `wrapping_to_fixed` and
- `overflowing_to_fixed` were added to the `Float` trait.
- * `PartialEq` and `PartialCmp` are now implemented for all
- combinations of fixed-point numbers and primitive integers.
- * The methods `int_bits` and `frac_bits` were deprecated and
- replaced by the methods `int_nbits` and `frac_nbits`.
+ `saturating_to_fixed`, `wrapping_to_fixed` and `overflowing_to_fixed` were
+ added to the `Float` trait.
+ * `PartialEq` and `PartialCmp` are now implemented for all combinations of
+ fixed-point numbers and primitive integers.
+ * The methods `int_bits` and `frac_bits` were deprecated and replaced by the
+ methods `int_nbits` and `frac_nbits`.
Version 0.2.1 (2019-01-29)
==========================
- * Bug fix: the `from_fixed` and `from_int` methods (and their
- checked counterparts) could return wrong values for negative
- values.
- * Bug fix: display was using one fractional digit less than
- required, thus yielding the same output for diffent fixed-point
- numbers.
+ * Bug fix: the `from_fixed` and `from_int` methods (and their checked
+ counterparts) could return wrong values for negative values.
+ * Bug fix: display was using one fractional digit less than required, thus
+ yielding the same output for diffent fixed-point numbers.
Version 0.2.0 (2019-01-29)
==========================
- * Incompatible change: The method `from_int` was change to accept a
- generic parameter.
- * The new methods `from_fixed`, `checked_from_fixed`,
- `saturating_from_fixed`, `wrapping_from_fixed` and
- `overflowing_from_fixed` were added.
+ * Incompatible change: The method `from_int` was change to accept a generic
+ parameter.
+ * The new methods `from_fixed`, `checked_from_fixed`, `saturating_from_fixed`,
+ `wrapping_from_fixed` and `overflowing_from_fixed` were added.
* The new methods `checked_from_int`, `saturating_from_int`,
`wrapping_from_int` and `overflowing_from_int` were added.
- * The new methods `from_float`, `checked_from_float`,
- `saturating_from_float`, `wrapping_from_float` and
- `overflowing_from_float` were added.
+ * The new methods `from_float`, `checked_from_float`, `saturating_from_float`,
+ `wrapping_from_float` and `overflowing_from_float` were added.
* The new method `to_float` was added.
- * The methods `from_f16`, `from_f32`, `from_f64`, `to_f16`, `to_f32`
- and `to_f64` were deprecated.
- * The `to_int` method was fixed to truncate fractional bits as
- documented for negative values.
- * The new methods `ceil`, `floor`, `round`, `checked_ceil`,
- `checked_floor`, `checked_round`, `saturating_ceil`,
- `saturating_floor`, `saturating_round`, `wrapping_ceil`,
- `wrapping_floor`, `wrapping_round`, `overflowing_ceil`,
+ * The methods `from_f16`, `from_f32`, `from_f64`, `to_f16`, `to_f32` and
+ `to_f64` were deprecated.
+ * The `to_int` method was fixed to truncate fractional bits as documented for
+ negative values.
+ * The new methods `ceil`, `floor`, `round`, `checked_ceil`, `checked_floor`,
+ `checked_round`, `saturating_ceil`, `saturating_floor`, `saturating_round`,
+ `wrapping_ceil`, `wrapping_floor`, `wrapping_round`, `overflowing_ceil`,
`overflowing_floor` and `overflowing_round` were added.
* The methods `to_int_ceil`, `to_int_floor` and `to_int_round` were
deprecated.
@@ -633,10 +601,10 @@ Version 0.1.6 (2019-01-27)
Version 0.1.5 (2019-01-26)
==========================
- * Lossless infallible conversions between fixed-point numbers and
- numeric primitives are now supported using `From` and `Into`.
- * A new module `types` is available with aliases for all supported
- fixed-point numbers.
+ * Lossless infallible conversions between fixed-point numbers and numeric
+ primitives are now supported using `From` and `Into`.
+ * A new module `types` is available with aliases for all supported fixed-point
+ numbers.
Version 0.1.4 (2018-11-29)
==========================
@@ -646,35 +614,35 @@ Version 0.1.4 (2018-11-29)
Version 0.1.3 (2018-08-23)
==========================
- * The `f16` feature was added, and new methods `from_f16` and
- `to_f16` were added.
+ * The `f16` feature was added, and new methods `from_f16` and `to_f16` were
+ added.
Version 0.1.2 (2018-08-15)
==========================
* The crate can now be used without the standard library `std`.
* New methods `from_f32` and `from_f64` were added.
- * New methods `is_positive` and `is_negative` were added to signed
- fixed-point numbers.
+ * New methods `is_positive` and `is_negative` were added to signed fixed-point
+ numbers.
Version 0.1.1 (2018-08-11)
==========================
- * Comparisons are now supported between all fixed-point numbers with
- the same underlying integer type.
+ * Comparisons are now supported between all fixed-point numbers with the same
+ underlying integer type.
* New static methods `int_bits` and `frac_bits` were added.
- * New methods `from_int`, `to_int`, `to_int_ceil`, `to_int_floor`
- and `to_int_round` were added.
+ * New methods `from_int`, `to_int`, `to_int_ceil`, `to_int_floor` and
+ `to_int_round` were added.
* New methods `int` and `frac` were added.
* Support for multiplication and division by integers was added.
Version 0.1.0 (2018-08-10)
==========================
- * `Unsigned` constants provided by the *typenum* crate are now used
- for the number of fractional bits.
- * Many methods and trait implementations available for primitive
- integers are now also supported by the fixed-point numbers.
+ * `Unsigned` constants provided by the *typenum* crate are now used for the
+ number of fractional bits.
+ * Many methods and trait implementations available for primitive integers are
+ now also supported by the fixed-point numbers.
[*az* crate]: https://crates.io/crates/az
[`MulAssign`]: https://doc.rust-lang.org/nightly/core/ops/trait.MulAssign.html
diff --git a/src/lib.rs b/src/lib.rs
index ef69c6f..8845431 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -39,10 +39,9 @@ range −0.5 ≤ x < 0.5 for signed numbers like
[FixedI32]\<[U32]>
, and in the range 0 ≤ x < 1 for unsigned
numbers like [FixedU32]\<[U32]>
.
-In version 1 the [*typenum* crate] is used for the fractional bit
-count `Frac`; the plan is to to have a major version 2 with [const
-generics] instead when the Rust compiler support for them is powerful
-enough.
+In version 1 the [*typenum* crate] is used for the fractional bit count `Frac`;
+the plan is to to have a major version 2 with [const generics] instead when the
+Rust compiler support for them is powerful enough.
The main features are
@@ -55,46 +54,42 @@ The main features are
This crate does *not* provide general analytic functions.
- * No algebraic functions are provided, for example no `sqrt` or
- `pow`.
- * No trigonometric functions are provided, for example no `sin` or
- `cos`.
- * No other transcendental functions are provided, for example no
- `log` or `exp`.
+ * No algebraic functions are provided, for example no `sqrt` or `pow`.
+ * No trigonometric functions are provided, for example no `sin` or `cos`.
+ * No other transcendental functions are provided, for example no `log` or
+ `exp`.
-These functions are not provided because different implementations can
-have different trade-offs, for example trading some correctness for
-speed. Implementations can be provided in other crates.
+These functions are not provided because different implementations can have
+different trade-offs, for example trading some correctness for speed.
+Implementations can be provided in other crates.
* The [*fixed-sqrt* crate] provides the square root operation.
- * The [*cordic* crate] provides various functions implemented using
- the [CORDIC] algorithm.
+ * The [*cordic* crate] provides various functions implemented using the
+ [CORDIC] algorithm.
The conversions supported cover the following cases.
- * Infallible lossless conversions between fixed-point numbers and
- numeric primitives are provided using [`From`] and [`Into`]. These
- never fail (infallible) and do not lose any bits (lossless).
- * Infallible lossy conversions between fixed-point numbers and
- numeric primitives are provided using the [`LossyFrom`] and
- [`LossyInto`] traits. The source can have more fractional bits
- than the destination.
- * Checked lossless conversions between fixed-point numbers and
- numeric primitives are provided using the [`LosslessTryFrom`] and
- [`LosslessTryInto`] traits. The source cannot have more fractional
- bits than the destination.
- * Checked conversions between fixed-point numbers and numeric
- primitives are provided using the [`FromFixed`] and [`ToFixed`]
- traits, or using the [`from_num`] and [`to_num`] methods and
- [their checked versions][`checked_from_num`].
- * Fixed-point numbers can be parsed from decimal strings using
- [`FromStr`], and from binary, octal and hexadecimal strings using
- the [`from_str_binary`], [`from_str_octal`] and [`from_str_hex`]
- methods. The result is rounded to the nearest, with ties rounded
- to even.
+ * Infallible lossless conversions between fixed-point numbers and numeric
+ primitives are provided using [`From`] and [`Into`]. These never fail
+ (infallible) and do not lose any bits (lossless).
+ * Infallible lossy conversions between fixed-point numbers and numeric
+ primitives are provided using the [`LossyFrom`] and [`LossyInto`] traits.
+ The source can have more fractional bits than the destination.
+ * Checked lossless conversions between fixed-point numbers and numeric
+ primitives are provided using the [`LosslessTryFrom`] and
+ [`LosslessTryInto`] traits. The source cannot have more fractional bits than
+ the destination.
+ * Checked conversions between fixed-point numbers and numeric primitives are
+ provided using the [`FromFixed`] and [`ToFixed`] traits, or using the
+ [`from_num`] and [`to_num`] methods and [their checked
+ versions][`checked_from_num`].
+ * Fixed-point numbers can be parsed from decimal strings using [`FromStr`],
+ and from binary, octal and hexadecimal strings using the
+ [`from_str_binary`], [`from_str_octal`] and [`from_str_hex`] methods. The
+ result is rounded to the nearest, with ties rounded to even.
* Fixed-point numbers can be converted to strings using [`Display`],
- [`Binary`], [`Octal`], [`LowerHex`] and [`UpperHex`]. The output
- is rounded to the nearest, with ties rounded to even.
+ [`Binary`], [`Octal`], [`LowerHex`] and [`UpperHex`]. The output is rounded
+ to the nearest, with ties rounded to even.
## Quick examples
@@ -111,12 +106,11 @@ assert_eq!(six_and_third.ceil().to_num::(), 7);
assert_eq!(six_and_third.ceil(), 7);
```
-The type [`I20F12`] is a 32-bit fixed-point signed number with 20
-integer bits and 12 fractional bits. It is an alias to
-[FixedI32][`FixedI32`]<[U12][`U12`]>
. The unsigned
-counterpart would be [`U20F12`]. Aliases are provided for all
-combinations of integer and fractional bits adding up to a total of
-eight, 16, 32, 64 or 128 bits.
+The type [`I20F12`] is a 32-bit fixed-point signed number with 20 integer bits
+and 12 fractional bits. It is an alias to [FixedI32]\<[U12]>
. The
+unsigned counterpart would be [`U20F12`]. Aliases are provided for all
+combinations of integer and fractional bits adding up to a total of eight, 16,
+32, 64 or 128 bits.
```rust
use fixed::types::{I4F4, I4F12};
@@ -138,23 +132,22 @@ assert_eq!(ans2, I4F4::from_bits((3 << 4) + 6));
assert_eq!(ans2.to_string(), "3.4");
```
-The second example shows some precision and conversion issues. The low
-precision of `a` means that `a / 5` is 3⁄16 instead of 1⁄5, leading to
-an inaccurate result `ans1` = 3 3⁄16 (~3.2). With a higher precision,
-we get `wider_a / 5` equal to 819⁄4096, leading to a more accurate
-intermediate result `wider_ans` = 3 1635⁄4096. When we convert back to
-four fractional bits, we get `ans2` = 3 6⁄16 (~3.4).
+The second example shows some precision and conversion issues. The low precision
+of `a` means that `a / 5` is 3⁄16 instead of 1⁄5, leading to an inaccurate
+result `ans1` = 3 3⁄16 (~3.2). With a higher precision, we get `wider_a / 5`
+equal to 819⁄4096, leading to a more accurate intermediate result `wider_ans` =
+3 1635⁄4096. When we convert back to four fractional bits, we get `ans2` = 3
+6⁄16 (~3.4).
-Note that we can convert from [`I4F4`] to [`I4F12`] using [`From`], as
-the target type has the same number of integer bits and a larger
-number of fractional bits. Converting from [`I4F12`] to [`I4F4`]
-cannot use [`From`] as we have less fractional bits, so we use
-[`from_num`] instead.
+Note that we can convert from [`I4F4`] to [`I4F12`] using [`From`], as the
+target type has the same number of integer bits and a larger number of
+fractional bits. Converting from [`I4F12`] to [`I4F4`] cannot use [`From`] as we
+have less fractional bits, so we use [`from_num`] instead.
## Writing fixed-point constants and values literally
-The [*fixed-macro* crate] provides a convenient macro to write down
-fixed-point constants literally in the code.
+The [*fixed-macro* crate] provides a convenient macro to write down fixed-point
+constants literally in the code.
```rust
# #[cfg(feature = "skip-this-test")] {
@@ -169,8 +162,8 @@ assert_eq!(num2, 25.875);
## Using the *fixed* crate
-The *fixed* crate is available on [crates.io][*fixed* crate]. To use
-it in your crate, add it as a dependency inside [*Cargo.toml*]:
+The *fixed* crate is available on [crates.io][*fixed* crate]. To use it in your
+crate, add it as a dependency inside [*Cargo.toml*]:
```toml
[dependencies]
@@ -183,21 +176,18 @@ The *fixed* crate requires rustc version 1.50.0 or later.
The *fixed* crate has these optional feature:
- 1. `serde`, disabled by default. This provides serialization support
- for the fixed-point types. This feature requires the
- [*serde* crate].
- 2. `std`, disabled by default. This is for features that are not
- possible under `no_std`: currently the implementation of the
- [`Error`] trait for [`ParseFixedError`].
- 3. `serde-str`, disabled by default. Fixed-point numbers are
- serialized as strings showing the value when using human-readable
- formats. This feature requires the `serde` and the `std` optional
- features. **Warning:** numbers serialized when this feature is
- enabled cannot be deserialized when this feature is disabled, and
- vice versa.
+ 1. `serde`, disabled by default. This provides serialization support for the
+ fixed-point types. This feature requires the [*serde* crate].
+ 2. `std`, disabled by default. This is for features that are not possible under
+ `no_std`: currently the implementation of the [`Error`] trait for
+ [`ParseFixedError`].
+ 3. `serde-str`, disabled by default. Fixed-point numbers are serialized as
+ strings showing the value when using human-readable formats. This feature
+ requires the `serde` and the `std` optional features. **Warning:** numbers
+ serialized when this feature is enabled cannot be deserialized when this
+ feature is disabled, and vice versa.
-To enable features, you can add the dependency like this to
-[*Cargo.toml*]:
+To enable features, you can add the dependency like this to [*Cargo.toml*]:
```toml
[dependencies.fixed]
@@ -207,33 +197,29 @@ features = ["serde"]
## Experimental optional features
-It is not considered a breaking change if the following experimental
-features are removed. The removal of experimental features would
-however require a minor version bump. Similarly, on a minor version
-bump, optional dependencies can be updated to an incompatible newer
-version.
+It is not considered a breaking change if the following experimental features
+are removed. The removal of experimental features would however require a minor
+version bump. Similarly, on a minor version bump, optional dependencies can be
+updated to an incompatible newer version.
- 1. `num-traits`, disabled by default. This implements some traits
- from the [*num-traits* crate]. (The plan is to promote this to an
- optional feature once the [*num-traits* crate] reaches version
- 1.0.0.)
+ 1. `num-traits`, disabled by default. This implements some traits from the
+ [*num-traits* crate]. (The plan is to promote this to an optional feature
+ once the [*num-traits* crate] reaches version 1.0.0.)
## Deprecated optional features
-The following optional features are deprecated and may be removed in
-the next major version of the crate.
+The following optional features are deprecated and may be removed in the next
+major version of the crate.
- 1. `az`, has no effect. Previously required to enable the cast traits
- provided by the [*az* crate]. Now these cast traits are always
- provided.
- 2. `f16`, has no effect. Previously required to provide conversion
- to/from [`f16`] and [`bf16`]. Now these conversions are always
- provided.
+ 1. `az`, has no effect. Previously required to enable the cast traits provided
+ by the [*az* crate]. Now these cast traits are always provided.
+ 2. `f16`, has no effect. Previously required to provide conversion to/from
+ [`f16`] and [`bf16`]. Now these conversions are always provided.
## License
-This crate is free software: you can redistribute it and/or modify it
-under the terms of either
+This crate is free software: you can redistribute it and/or modify it under the
+terms of either
* the [Apache License, Version 2.0][LICENSE-APACHE] or
* the [MIT License][LICENSE-MIT]
@@ -242,10 +228,9 @@ at your option.
### Contribution
-Unless you explicitly state otherwise, any contribution intentionally
-submitted for inclusion in the work by you, as defined in the Apache
-License, Version 2.0, shall be dual licensed as above, without any
-additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache License, Version 2.0,
+shall be dual licensed as above, without any additional terms or conditions.
[*Cargo.toml*]: https://doc.rust-lang.org/cargo/guide/dependencies.html
[*az* crate]: https://crates.io/crates/az
@@ -427,9 +412,9 @@ macro_rules! fixed {
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 ",
+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, "/2f"),
@@ -455,9 +440,9 @@ When f = 0, Δ = 1 and the fixed-point number behaves like ",
if_signed_unsigned!($Signedness, "−1/2 ≤ x < 1/2", "0 ≤ x < 1"),
".
-`Frac` is an [`Unsigned`] as provided by the [*typenum* crate]; the
-plan is to to have a major version 2 with [const generics] instead
-when the Rust compiler support for them is powerful enough.
+`Frac` is an [`Unsigned`] as provided by the [*typenum* crate]; the plan is to
+to have a major version 2 with [const generics] instead when the Rust compiler
+support for them is powerful enough.
# Examples
@@ -627,14 +612,14 @@ fixed! {
FixedI128, i128, "128", False
}
-/// The bit representation of a *binary128* floating-point number
-/// (`f128`).
+/// The bit representation of a *binary128* floating-point number (`f128`).
///
/// This type can be used to
-/// * convert between fixed-point numbers and the bit representation
-/// of 128-bit floating-point numbers.
-/// * compare fixed-point numbers and the bit representation of
+///
+/// * convert between fixed-point numbers and the bit representation of
/// 128-bit floating-point numbers.
+/// * compare fixed-point numbers and the bit representation of 128-bit
+/// floating-point numbers.
///
/// # Examples
///
@@ -667,19 +652,18 @@ impl F128Bits {
/// Defines constant fixed-point numbers from integer expressions.
///
-/// This macro is useful because [`from_num`] cannot be used in
-/// constant expressions.
+/// This macro is useful because [`from_num`] cannot be used in constant
+/// expressions.
///
/// # Alternative
///
-/// The [*fixed-macro* crate] provides a convenient macro to write
-/// down fixed-point constants literally in code which has two
-/// advantages over this macro:
+/// The [*fixed-macro* crate] provides a convenient macro to write down
+/// fixed-point constants literally in code which has two advantages over this
+/// macro:
///
-/// 1. It can handle fixed-point numbers with fractions, not just
-/// integers.
-/// 2. It can be used anywhere an expression or constant expression
-/// can be used, not just to define a constant.
+/// 1. It can handle fixed-point numbers with fractions, not just integers.
+/// 2. It can be used anywhere an expression or constant expression can be
+/// used, not just to define a constant.
///
/// # Examples
///
@@ -696,8 +680,7 @@ impl F128Bits {
/// ```
///
/// The following would fail to compile because
-/// [i32]::[MAX][i32::MAX]
is not representable by
-/// [`I16F16`].
+/// [i32]::[MAX][i32::MAX]
is not representable by [`I16F16`].
///
/// ```rust,compile_fail
/// use fixed::{const_fixed_from_int, types::I16F16};
@@ -707,10 +690,9 @@ impl F128Bits {
/// }
/// ```
///
-/// The following would fail to compile because [`I16F16`] is an alias
-/// for [FixedI32]<[U32]>
, and this macro
-/// can define [`FixedI32`] constants using [`i32`] expressions, not
-/// [`i16`] expressions.
+/// The following would fail to compile because [`I16F16`] is an alias for
+/// [FixedI32]\<[U32]>
, and this macro can define [`FixedI32`]
+/// constants using [`i32`] expressions, not [`i16`] expressions.
///
/// ```rust,compile_fail
/// use fixed::{const_fixed_from_int, types::I16F16};
@@ -738,8 +720,8 @@ macro_rules! const_fixed_from_int {
)* };
}
-/// These are doc tests that should not appear in the docs, but are
-/// useful as doc tests can check to ensure compilation failure.
+/// These are doc tests that should not appear in the docs, but are useful as
+/// doc tests can check to ensure compilation failure.
///
/// The first snippet succeeds, and acts as a control.
///