reflow some docs
This commit is contained in:
Trevor Spiteri
parent
2ca975ee46
commit
353ece484e
246
README.md
246
README.md
|
|
@ -30,10 +30,9 @@ range −0.5 ≤ <i>x</i> < 0.5 for signed numbers like
|
|||
<code>[FixedI32]\<[U32]></code>, and in the range 0 ≤ <i>x</i> < 1 for unsigned
|
||||
numbers like <code>[FixedU32]\<[U32]></code>.
|
||||
|
||||
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::<i32>(), 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
|
||||
<code>[FixedI32][`FixedI32`]<[U12][`U12`]></code>. 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 <code>[FixedI32]\<[U12]></code>. 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
|
||||
|
|
|
|||
404
RELEASES.md
404
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<bool>` for all fixed-point types which can
|
||||
represent the integer 1. This was inadvertently removed in 0.3.0.
|
||||
* Reimplement `From<bool>` 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
|
||||
|
|
|
|||
228
src/lib.rs
228
src/lib.rs
|
|
@ -39,10 +39,9 @@ range −0.5 ≤ <i>x</i> < 0.5 for signed numbers like
|
|||
<code>[FixedI32]\<[U32]></code>, and in the range 0 ≤ <i>x</i> < 1 for unsigned
|
||||
numbers like <code>[FixedU32]\<[U32]></code>.
|
||||
|
||||
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::<i32>(), 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
|
||||
<code>[FixedI32][`FixedI32`]<[U12][`U12`]></code>. 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 <code>[FixedI32]\<[U12]></code>. 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 <i>f</i> = `Frac` are
|
||||
fractional bits and ", $s_nbits, " − <i>f</i> are integer bits. The
|
||||
value <i>x</i> can lie in the range ",
|
||||
The number has ", $s_nbits, " bits, of which <i>f</i> = `Frac` are fractional
|
||||
bits and ", $s_nbits, " − <i>f</i> are integer bits. The value <i>x</i> can lie
|
||||
in the range ",
|
||||
if_signed_unsigned!(
|
||||
$Signedness,
|
||||
concat!("−2<sup>", $s_nbits_m1, "</sup>/2<sup><i>f</i></sup>"),
|
||||
|
|
@ -455,9 +440,9 @@ When <i>f</i> = 0, <i>Δ</i> = 1 and the fixed-point number behaves like ",
|
|||
if_signed_unsigned!($Signedness, "−1/2 ≤ <i>x</i> < 1/2", "0 ≤ <i>x</i> < 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
|
||||
/// <code>[i32]::[MAX][i32::MAX]</code> is not representable by
|
||||
/// [`I16F16`].
|
||||
/// <code>[i32]::[MAX][i32::MAX]</code> 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 <code>[FixedI32]<[U32]></code>, 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
|
||||
/// <code>[FixedI32]\<[U32]></code>, 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.
|
||||
///
|
||||
|
|
|
|||
Loading…
Reference in New Issue