2020-04-13 11:11:39 -07:00
|
|
|
|
<!-- Copyright © 2018–2020 Trevor Spiteri -->
|
2018-08-09 11:02:34 -07:00
|
|
|
|
|
|
|
|
|
<!-- Copying and distribution of this file, with or without
|
|
|
|
|
modification, are permitted in any medium without royalty provided the
|
|
|
|
|
copyright notice and this notice are preserved. This file is offered
|
|
|
|
|
as-is, without any warranty. -->
|
|
|
|
|
|
|
|
|
|
# Fixed-point numbers
|
|
|
|
|
|
2019-08-24 04:10:49 -07:00
|
|
|
|
The [*fixed* crate] provides fixed-point numbers.
|
|
|
|
|
|
|
|
|
|
* [`FixedI8`] and [`FixedU8`] are eight-bit fixed-point numbers.
|
|
|
|
|
* [`FixedI16`] and [`FixedU16`] are 16-bit fixed-point numbers.
|
|
|
|
|
* [`FixedI32`] and [`FixedU32`] are 32-bit fixed-point numbers.
|
|
|
|
|
* [`FixedI64`] and [`FixedU64`] are 64-bit fixed-point numbers.
|
|
|
|
|
* [`FixedI128`] and [`FixedU128`] are 128-bit fixed-point numbers.
|
|
|
|
|
|
2019-08-26 02:10:07 -07:00
|
|
|
|
These types can have `Frac` fractional bits, where
|
|
|
|
|
0 ≤ `Frac` ≤ <i>n</i> and <i>n</i> is the total number of bits. When
|
|
|
|
|
`Frac` = 0, the fixed-point number behaves like an <i>n</i>-bit
|
|
|
|
|
integer. When `Frac` = <i>n</i>, the value <i>x</i> lies in the range
|
|
|
|
|
−0.5 ≤ <i>x</i> < 0.5 for signed numbers, and in the range
|
|
|
|
|
0 ≤ <i>x</i> < 1 for unsigned numbers.
|
2019-08-24 04:10:49 -07:00
|
|
|
|
|
2020-05-02 12:22:46 -07:00
|
|
|
|
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] when they are supported by the Rust compiler.
|
2019-08-24 04:10:49 -07:00
|
|
|
|
|
|
|
|
|
The main features are
|
|
|
|
|
|
|
|
|
|
* Representation of fixed-point numbers up to 128 bits wide.
|
|
|
|
|
* Conversions between fixed-point numbers and numeric primitives.
|
|
|
|
|
* Comparisons between fixed-point numbers and numeric primitives.
|
|
|
|
|
* Parsing from strings in decimal, binary, octal and hexadecimal.
|
|
|
|
|
* Display as decimal, binary, octal and hexadecimal.
|
|
|
|
|
* Arithmetic and logic operations.
|
|
|
|
|
|
|
|
|
|
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`.
|
2019-08-24 05:52:32 -07:00
|
|
|
|
* No other transcendental functions are provided, for example no
|
2019-08-24 04:10:49 -07:00
|
|
|
|
`log` or `exp`.
|
2019-08-23 01:02:50 -07:00
|
|
|
|
|
2020-02-12 14:56:26 -08:00
|
|
|
|
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.
|
|
|
|
|
|
2020-02-13 03:18:22 -08:00
|
|
|
|
* The [*fixed-sqrt* crate] provides the square root operation.
|
2020-02-12 14:56:26 -08:00
|
|
|
|
|
2019-08-23 01:02:50 -07:00
|
|
|
|
The conversions supported cover the following cases.
|
|
|
|
|
|
2019-08-24 04:10:49 -07:00
|
|
|
|
* 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.
|
2020-05-08 03:41:35 -07:00
|
|
|
|
* 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.
|
2019-08-24 04:10:49 -07:00
|
|
|
|
* 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`].
|
2019-08-20 07:42:37 -07:00
|
|
|
|
* Fixed-point numbers can be parsed from decimal strings using
|
2019-08-24 04:10:49 -07:00
|
|
|
|
[`FromStr`], and from binary, octal and hexadecimal strings using
|
|
|
|
|
the [`from_str_binary`], [`from_str_octal`] and [`from_str_hex`]
|
2019-08-20 10:40:53 -07:00
|
|
|
|
methods. The result is rounded to the nearest, with ties rounded
|
|
|
|
|
to even.
|
2019-08-20 07:42:37 -07:00
|
|
|
|
* Fixed-point numbers can be converted to strings using [`Display`],
|
|
|
|
|
[`Binary`], [`Octal`], [`LowerHex`] and [`UpperHex`]. The output
|
2019-08-20 10:40:53 -07:00
|
|
|
|
is rounded to the nearest, with ties rounded to even.
|
2019-01-26 12:16:20 -08:00
|
|
|
|
|
2018-08-10 11:57:59 -07:00
|
|
|
|
## What’s new
|
|
|
|
|
|
2020-10-30 16:29:58 -07:00
|
|
|
|
### Version 1.5.0 news (unreleased)
|
|
|
|
|
|
2020-10-31 07:12:58 -07:00
|
|
|
|
* The [`wide_mul`][f-wm-1-5] method was added to all fixed-point
|
2020-10-30 16:29:58 -07:00
|
|
|
|
numbers up to 64 bits wide.
|
|
|
|
|
|
2020-10-31 07:12:58 -07:00
|
|
|
|
[f-wm-1-5]: https://tspiteri.gitlab.io/fixed/dev/fixed/struct.FixedI32.html#method.wide_mul
|
2020-10-30 16:29:58 -07:00
|
|
|
|
|
2020-10-23 04:00:36 -07:00
|
|
|
|
### Version 1.4.1 news (unreleased)
|
|
|
|
|
|
|
|
|
|
* For the experimental feature [`num-traits`][feat-exp-1-4], some
|
|
|
|
|
missing supertraits were added to
|
|
|
|
|
[`FixedOptionalFeatures`][tfof-1-4].
|
|
|
|
|
|
2020-10-22 02:45:51 -07:00
|
|
|
|
### Version 1.4.0 news (2020-10-22)
|
2020-10-20 03:10:49 -07:00
|
|
|
|
|
2020-10-22 02:21:54 -07:00
|
|
|
|
* 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],
|
|
|
|
|
[`overflowing_recip`][f-orec-1-4]
|
2020-10-20 07:02:43 -07:00
|
|
|
|
* 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]
|
2020-10-20 03:10:49 -07:00
|
|
|
|
* For the experimental feature [`serde-str`][feat-exp-1-4],
|
|
|
|
|
serialization in human-readable formats was made more convenient
|
2020-10-20 07:02:43 -07:00
|
|
|
|
to write manually ([issue 24]). This makes it incompatible with
|
|
|
|
|
the version in 1.3.0.
|
2020-10-20 03:10:49 -07:00
|
|
|
|
|
2020-10-22 02:45:51 -07:00
|
|
|
|
[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
|
|
|
|
|
[f-rec-1-4]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.recip
|
|
|
|
|
[f-srec-1-4]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.saturating_recip
|
|
|
|
|
[f-wrec-1-4]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.wrapping_recip
|
|
|
|
|
[feat-exp-1-4]: https://docs.rs/fixed/~1.4/fixed/#experimental-optional-features
|
2020-10-20 07:02:43 -07:00
|
|
|
|
[issue 23]: https://gitlab.com/tspiteri/fixed/-/issues/23
|
|
|
|
|
[issue 24]: https://gitlab.com/tspiteri/fixed/-/issues/24
|
|
|
|
|
[nt-0-2-fc]: https://docs.rs/num-traits/^0.2/num_traits/float/trait.FloatConst.html
|
|
|
|
|
[nt-0-2-fp]: https://docs.rs/num-traits/^0.2/num_traits/cast/trait.FromPrimitive.html
|
|
|
|
|
[nt-0-2-inv]: https://docs.rs/num-traits/^0.2/num_traits/ops/inv/trait.Inv.html
|
|
|
|
|
[nt-0-2-ma]: https://docs.rs/num-traits/^0.2/num_traits/ops/mul_add/trait.MulAdd.html
|
|
|
|
|
[nt-0-2-maa]: https://docs.rs/num-traits/^0.2/num_traits/ops/mul_add/trait.MulAddAssign.html
|
|
|
|
|
[nt-0-2-num]: https://docs.rs/num-traits/^0.2/num_traits/trait.Num.html
|
|
|
|
|
[nt-0-2-signed]: https://docs.rs/num-traits/^0.2/num_traits/sign/trait.Signed.html
|
|
|
|
|
[nt-0-2-tp]: https://docs.rs/num-traits/^0.2/num_traits/cast/trait.ToPrimitive.html
|
|
|
|
|
[nt-0-2-unsigned]: https://docs.rs/num-traits/^0.2/num_traits/sign/trait.Unsigned.html
|
2020-10-22 02:45:51 -07:00
|
|
|
|
[tf-1-4]: https://docs.rs/fixed/~1.4/fixed/traits/trait.Fixed.html
|
2020-10-23 04:00:36 -07:00
|
|
|
|
[tfof-1-4]: https://docs.rs/fixed/~1.4/fixed/traits/trait.FixedOptionalFeatures.html
|
2020-10-22 02:45:51 -07:00
|
|
|
|
[w-1-4]: https://docs.rs/fixed/~1.4/fixed/struct.Wrapping.html
|
2020-10-20 03:10:49 -07:00
|
|
|
|
|
2020-10-15 09:48:04 -07:00
|
|
|
|
### Version 1.3.0 news (2020-10-15)
|
2020-09-17 07:58:26 -07:00
|
|
|
|
|
2020-09-22 10:09:41 -07:00
|
|
|
|
* The [`MulAssign`] implementation on fixed-point numbers now
|
|
|
|
|
accepts an rhs fixed-point number with a different number of
|
|
|
|
|
fractional bits from `self`.
|
2020-09-22 08:20:13 -07:00
|
|
|
|
* The following methods were added to all fixed-point types, to the
|
2020-09-22 10:09:41 -07:00
|
|
|
|
[`Fixed`][tf-ma-1-3] trait, and to the [`Wrapping`][w-ma-1-3] wrapper:
|
2020-09-22 06:47:13 -07:00
|
|
|
|
* [`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],
|
|
|
|
|
[`overflowing_mul_add`][f-oma-1-3]
|
2020-10-09 05:41:10 -07:00
|
|
|
|
* 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.
|
2020-09-17 07:58:26 -07:00
|
|
|
|
|
2020-09-22 10:09:41 -07:00
|
|
|
|
[`MulAssign`]: https://doc.rust-lang.org/nightly/core/ops/trait.MulAssign.html
|
2020-10-15 09:48:04 -07:00
|
|
|
|
[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
|
|
|
|
|
[f-oma-1-3]: https://docs.rs/fixed/~1.3/fixed/struct.FixedI32.html#method.overflowing_mul_add
|
|
|
|
|
[f-sma-1-3]: https://docs.rs/fixed/~1.3/fixed/struct.FixedI32.html#method.saturating_mul_add
|
|
|
|
|
[f-wma-1-3]: https://docs.rs/fixed/~1.3/fixed/struct.FixedI32.html#method.wrapping_mul_add
|
|
|
|
|
[feat-exp-1-3]: https://docs.rs/fixed/~1.3/fixed/#experimental-optional-features
|
|
|
|
|
[tf-ma-1-3]: https://docs.rs/fixed/~1.3/fixed/traits/trait.Fixed.html#tymethod.mul_add
|
|
|
|
|
[w-ma-1-3]: https://docs.rs/fixed/~1.3/fixed/struct.Wrapping.html#method.mul_add
|
2020-09-17 07:58:26 -07:00
|
|
|
|
|
2018-08-10 11:57:59 -07:00
|
|
|
|
### Other releases
|
|
|
|
|
|
|
|
|
|
Details on other releases can be found in [*RELEASES.md*].
|
|
|
|
|
|
|
|
|
|
[*RELEASES.md*]: https://gitlab.com/tspiteri/fixed/blob/master/RELEASES.md
|
|
|
|
|
|
2019-01-29 12:55:58 -08:00
|
|
|
|
## Quick examples
|
2018-08-11 08:33:31 -07:00
|
|
|
|
|
|
|
|
|
```rust
|
2019-01-26 13:22:18 -08:00
|
|
|
|
use fixed::types::I20F12;
|
|
|
|
|
|
2018-08-11 08:49:36 -07:00
|
|
|
|
// 19/3 = 6 1/3
|
2019-08-16 14:42:29 -07:00
|
|
|
|
let six_and_third = I20F12::from_num(19) / 3;
|
2018-08-11 08:33:31 -07:00
|
|
|
|
// four decimal digits for 12 binary digits
|
2018-08-11 08:49:36 -07:00
|
|
|
|
assert_eq!(six_and_third.to_string(), "6.3333");
|
2019-01-31 16:13:53 -08:00
|
|
|
|
// find the ceil and convert to i32
|
2019-08-16 14:42:29 -07:00
|
|
|
|
assert_eq!(six_and_third.ceil().to_num::<i32>(), 7);
|
2019-02-03 12:37:17 -08:00
|
|
|
|
// we can also compare directly to integers
|
|
|
|
|
assert_eq!(six_and_third.ceil(), 7);
|
2018-08-11 08:33:31 -07:00
|
|
|
|
```
|
|
|
|
|
|
2019-01-26 13:22:18 -08:00
|
|
|
|
The type [`I20F12`] is a 32-bit fixed-point signed number with 20
|
|
|
|
|
integer bits and 12 fractional bits. It is an alias to
|
2019-08-24 04:10:49 -07:00
|
|
|
|
<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.
|
2019-01-26 13:22:18 -08:00
|
|
|
|
|
2019-01-29 12:55:58 -08:00
|
|
|
|
```rust
|
2019-08-24 04:10:49 -07:00
|
|
|
|
use fixed::types::{I4F4, I4F12};
|
|
|
|
|
|
2019-08-20 07:42:37 -07:00
|
|
|
|
// −8 ≤ I4F4 < 8 with steps of 1/16 (~0.06)
|
2019-08-16 14:42:29 -07:00
|
|
|
|
let a = I4F4::from_num(1);
|
|
|
|
|
// multiplication and division by integers are possible
|
2019-01-29 12:55:58 -08:00
|
|
|
|
let ans1 = a / 5 * 17;
|
2019-08-20 07:42:37 -07:00
|
|
|
|
// 1 / 5 × 17 = 3 2/5 (3.4), but we get 3 3/16 (~3.2)
|
2019-01-29 12:55:58 -08:00
|
|
|
|
assert_eq!(ans1, I4F4::from_bits((3 << 4) + 3));
|
2019-08-19 14:15:03 -07:00
|
|
|
|
assert_eq!(ans1.to_string(), "3.2");
|
2019-01-29 12:55:58 -08:00
|
|
|
|
|
2019-08-20 07:42:37 -07:00
|
|
|
|
// −8 ≤ I4F12 < 8 with steps of 1/4096 (~0.0002)
|
2019-01-29 12:55:58 -08:00
|
|
|
|
let wider_a = I4F12::from(a);
|
|
|
|
|
let wider_ans = wider_a / 5 * 17;
|
2019-08-16 14:42:29 -07:00
|
|
|
|
let ans2 = I4F4::from_num(wider_ans);
|
2019-08-20 07:42:37 -07:00
|
|
|
|
// now the answer is the much closer 3 6/16 (~3.4)
|
2019-01-29 12:55:58 -08:00
|
|
|
|
assert_eq!(ans2, I4F4::from_bits((3 << 4) + 6));
|
2019-08-19 14:15:03 -07:00
|
|
|
|
assert_eq!(ans2.to_string(), "3.4");
|
2019-01-29 12:55:58 -08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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
|
2019-08-20 07:42:37 -07:00
|
|
|
|
an inaccurate result `ans1` = 3 3⁄16 (~3.2). With a higher precision,
|
2019-01-29 12:55:58 -08:00
|
|
|
|
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
|
2019-08-20 07:42:37 -07:00
|
|
|
|
four fractional bits, we get `ans2` = 3 6⁄16 (~3.4).
|
2019-01-29 12:55:58 -08:00
|
|
|
|
|
|
|
|
|
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
|
2019-08-16 14:42:29 -07:00
|
|
|
|
[`from_num`] instead.
|
2019-01-29 12:55:58 -08:00
|
|
|
|
|
2020-10-19 01:37:29 -07:00
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
```rust
|
|
|
|
|
use fixed::types::I16F16;
|
|
|
|
|
use fixed_macro::fixed;
|
|
|
|
|
|
|
|
|
|
const NUM1: I16F16 = fixed!(12.75: I16F16);
|
|
|
|
|
let num2 = NUM1 + fixed!(13.125: I16F16);
|
|
|
|
|
assert_eq!(num2, 25.875);
|
|
|
|
|
```
|
|
|
|
|
|
2018-08-10 11:30:03 -07:00
|
|
|
|
## 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*]:
|
2018-08-10 02:13:42 -07:00
|
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[dependencies]
|
2020-10-22 02:45:51 -07:00
|
|
|
|
fixed = "1.4"
|
2018-08-10 02:13:42 -07:00
|
|
|
|
```
|
|
|
|
|
|
2020-09-02 04:03:23 -07:00
|
|
|
|
The *fixed* crate requires rustc version 1.44.0 or later.
|
2018-08-13 03:10:53 -07:00
|
|
|
|
|
2018-08-23 04:12:32 -07:00
|
|
|
|
## Optional features
|
|
|
|
|
|
2019-12-23 08:39:41 -08:00
|
|
|
|
The *fixed* crate has four optional feature:
|
2018-08-23 04:12:32 -07:00
|
|
|
|
|
2019-10-10 08:13:36 -07:00
|
|
|
|
1. `az`, disabled by default. This implements the cast traits
|
|
|
|
|
provided by the [*az* crate].
|
|
|
|
|
2. `f16`, disabled by default. This provides conversion to/from
|
2019-10-16 02:32:53 -07:00
|
|
|
|
[`f16`] and [`bf16`]. This features requires the [*half* crate].
|
2019-10-10 08:13:36 -07:00
|
|
|
|
3. `serde`, disabled by default. This provides serialization support
|
2019-01-26 15:39:24 -08:00
|
|
|
|
for the fixed-point types. This feature requires the
|
2019-01-29 12:55:58 -08:00
|
|
|
|
[*serde* crate].
|
2019-12-23 08:39:41 -08:00
|
|
|
|
4. `std`, disabled by default. This is for features that are not
|
|
|
|
|
possible under `no_std`: currently the implementation of the
|
|
|
|
|
[`Error`] trait for [`ParseFixedError`].
|
2018-08-23 04:12:32 -07:00
|
|
|
|
|
2019-01-26 15:39:24 -08:00
|
|
|
|
To enable features, you can add the dependency like this to
|
2018-08-23 04:12:32 -07:00
|
|
|
|
[*Cargo.toml*]:
|
|
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[dependencies.fixed]
|
2020-10-22 02:45:51 -07:00
|
|
|
|
version = "1.4"
|
2019-01-26 15:39:24 -08:00
|
|
|
|
features = ["f16", "serde"]
|
2018-08-23 04:12:32 -07:00
|
|
|
|
```
|
|
|
|
|
|
2020-07-13 01:11:04 -07:00
|
|
|
|
## Experimental optional features
|
|
|
|
|
|
|
|
|
|
It is not considered a breaking change if 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.
|
|
|
|
|
|
2020-10-09 05:41:10 -07:00
|
|
|
|
There are three experimental feature:
|
2020-07-13 01:11:04 -07:00
|
|
|
|
|
|
|
|
|
1. `num-traits`, disabled by default. This implements some traits
|
2020-10-15 09:48:04 -07:00
|
|
|
|
from the [*num-traits* crate]. (The plan is to upgrade this to an
|
|
|
|
|
optional feature once *num-traits* reaches version 1.0.0.)
|
2020-09-17 07:58:26 -07:00
|
|
|
|
2. `unwrapped`, disabled by default. This adds methods for arithmetic
|
|
|
|
|
that panic on overflow even when debug assertions are disabled,
|
|
|
|
|
similar to how wrapping methods will wrap even when debug
|
2020-10-15 09:48:04 -07:00
|
|
|
|
assertions are enabled. (The plan is to always enable this
|
|
|
|
|
functionality but remove the experimental feature in version
|
2020-10-20 03:10:49 -07:00
|
|
|
|
1.5.0.)
|
2020-10-09 09:11:40 -07:00
|
|
|
|
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
|
2020-10-15 09:48:04 -07:00
|
|
|
|
features. (The plan is to upgrade this to an optional feature in
|
2020-10-20 03:10:49 -07:00
|
|
|
|
version 1.5.0.) **Warning:** numbers serialized when this feature
|
2020-10-22 02:45:51 -07:00
|
|
|
|
is enabled cannot be deserialized when this feature is disabled,
|
|
|
|
|
and vice versa.
|
2020-07-13 01:11:04 -07:00
|
|
|
|
|
2018-08-10 02:13:42 -07:00
|
|
|
|
## License
|
|
|
|
|
|
2018-08-10 02:34:17 -07:00
|
|
|
|
This crate is free software: you can redistribute it and/or modify it
|
|
|
|
|
under the terms of either
|
2018-08-10 02:13:42 -07:00
|
|
|
|
|
2018-08-10 11:30:03 -07:00
|
|
|
|
* the [Apache License, Version 2.0][LICENSE-APACHE] or
|
|
|
|
|
* the [MIT License][LICENSE-MIT]
|
2018-08-10 02:13:42 -07:00
|
|
|
|
|
|
|
|
|
at your option.
|
|
|
|
|
|
|
|
|
|
### Contribution
|
|
|
|
|
|
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally
|
2018-08-10 11:30:03 -07:00
|
|
|
|
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
|
2018-08-10 02:13:42 -07:00
|
|
|
|
additional terms or conditions.
|
|
|
|
|
|
|
|
|
|
[*Cargo.toml*]: https://doc.rust-lang.org/cargo/guide/dependencies.html
|
2019-10-10 08:13:36 -07:00
|
|
|
|
[*az* crate]: https://crates.io/crates/az
|
2018-08-10 11:30:03 -07:00
|
|
|
|
[*fixed* crate]: https://crates.io/crates/fixed
|
2020-10-19 01:37:29 -07:00
|
|
|
|
[*fixed-macro* crate]: https://crates.io/crates/fixed-macro
|
2020-02-13 03:18:22 -08:00
|
|
|
|
[*fixed-sqrt* crate]: https://crates.io/crates/fixed-sqrt
|
2018-08-23 04:12:32 -07:00
|
|
|
|
[*half* crate]: https://crates.io/crates/half
|
2020-07-13 01:11:04 -07:00
|
|
|
|
[*num-traits* crate]: https://crates.io/crates/num-traits
|
2019-01-26 15:39:24 -08:00
|
|
|
|
[*serde* crate]: https://crates.io/crates/serde
|
2018-08-10 11:30:03 -07:00
|
|
|
|
[*typenum* crate]: https://crates.io/crates/typenum
|
2018-08-10 02:13:42 -07:00
|
|
|
|
[LICENSE-APACHE]: https://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
[LICENSE-MIT]: https://opensource.org/licenses/MIT
|
2019-12-23 08:21:46 -08:00
|
|
|
|
[`Binary`]: https://doc.rust-lang.org/nightly/core/fmt/trait.Binary.html
|
|
|
|
|
[`Display`]: https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html
|
2019-12-23 08:39:41 -08:00
|
|
|
|
[`Error`]: https://doc.rust-lang.org/nightly/std/error/trait.Error.html
|
2020-10-22 02:45:51 -07:00
|
|
|
|
[`FixedI128`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI128.html
|
|
|
|
|
[`FixedI16`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI16.html
|
|
|
|
|
[`FixedI32`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html
|
|
|
|
|
[`FixedI64`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI64.html
|
|
|
|
|
[`FixedI8`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI8.html
|
|
|
|
|
[`FixedU128`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedU128.html
|
|
|
|
|
[`FixedU16`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedU16.html
|
|
|
|
|
[`FixedU32`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedU32.html
|
|
|
|
|
[`FixedU64`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedU64.html
|
|
|
|
|
[`FixedU8`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedU8.html
|
|
|
|
|
[`FromFixed`]: https://docs.rs/fixed/~1.4/fixed/traits/trait.FromFixed.html
|
2019-12-23 08:21:46 -08:00
|
|
|
|
[`FromStr`]: https://doc.rust-lang.org/nightly/core/str/trait.FromStr.html
|
|
|
|
|
[`From`]: https://doc.rust-lang.org/nightly/core/convert/trait.From.html
|
2020-10-22 02:45:51 -07:00
|
|
|
|
[`I20F12`]: https://docs.rs/fixed/~1.4/fixed/types/type.I20F12.html
|
|
|
|
|
[`I4F12`]: https://docs.rs/fixed/~1.4/fixed/types/type.I4F12.html
|
|
|
|
|
[`I4F4`]: https://docs.rs/fixed/~1.4/fixed/types/type.I4F4.html
|
2019-12-23 08:21:46 -08:00
|
|
|
|
[`Into`]: https://doc.rust-lang.org/nightly/core/convert/trait.Into.html
|
2020-10-22 02:45:51 -07:00
|
|
|
|
[`LosslessTryFrom`]: https://docs.rs/fixed/~1.4/fixed/traits/trait.LosslessTryFrom.html
|
|
|
|
|
[`LosslessTryInto`]: https://docs.rs/fixed/~1.4/fixed/traits/trait.LosslessTryInto.html
|
|
|
|
|
[`LossyFrom`]: https://docs.rs/fixed/~1.4/fixed/traits/trait.LossyFrom.html
|
|
|
|
|
[`LossyInto`]: https://docs.rs/fixed/~1.4/fixed/traits/trait.LossyInto.html
|
2019-12-23 08:21:46 -08:00
|
|
|
|
[`LowerHex`]: https://doc.rust-lang.org/nightly/core/fmt/trait.LowerHex.html
|
|
|
|
|
[`Octal`]: https://doc.rust-lang.org/nightly/core/fmt/trait.Octal.html
|
2020-10-22 02:45:51 -07:00
|
|
|
|
[`ParseFixedError`]: https://docs.rs/fixed/~1.4/fixed/struct.ParseFixedError.html
|
|
|
|
|
[`ToFixed`]: https://docs.rs/fixed/~1.4/fixed/traits/trait.ToFixed.html
|
|
|
|
|
[`U12`]: https://docs.rs/fixed/~1.4/fixed/types/extra/type.U12.html
|
|
|
|
|
[`U20F12`]: https://docs.rs/fixed/~1.4/fixed/types/type.U20F12.html
|
2019-12-23 08:21:46 -08:00
|
|
|
|
[`UpperHex`]: https://doc.rust-lang.org/nightly/core/fmt/trait.UpperHex.html
|
2019-10-16 02:32:53 -07:00
|
|
|
|
[`bf16`]: https://docs.rs/half/^1/half/struct.bf16.html
|
2020-10-22 02:45:51 -07:00
|
|
|
|
[`checked_from_num`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.checked_from_num
|
2018-08-23 04:12:32 -07:00
|
|
|
|
[`f16`]: https://docs.rs/half/^1/half/struct.f16.html
|
2020-10-22 02:45:51 -07:00
|
|
|
|
[`from_num`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.from_num
|
|
|
|
|
[`from_str_binary`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.from_str_binary
|
|
|
|
|
[`from_str_hex`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.from_str_hex
|
|
|
|
|
[`from_str_octal`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.from_str_octal
|
|
|
|
|
[`to_num`]: https://docs.rs/fixed/~1.4/fixed/struct.FixedI32.html#method.to_num
|
2018-08-09 11:02:34 -07:00
|
|
|
|
[const generics]: https://github.com/rust-lang/rust/issues/44580
|