2018-08-09 11:02:34 -07:00
|
|
|
|
<!-- Copyright © 2018 Trevor Spiteri -->
|
|
|
|
|
|
|
|
|
|
<!-- 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
|
|
|
|
|
|
2018-08-10 11:30:03 -07:00
|
|
|
|
The [*fixed* crate] provides fixed-point numbers. Currently it uses
|
|
|
|
|
the [*typenum* crate] for the fractional bit count; it is planned to
|
|
|
|
|
move to [const generics] when they are implemented by the Rust
|
2018-08-10 08:45:08 -07:00
|
|
|
|
compiler.
|
2018-08-09 11:02:34 -07:00
|
|
|
|
|
2018-08-10 11:43:53 -07:00
|
|
|
|
The crate provides the following types:
|
|
|
|
|
|
|
|
|
|
* [`FixedI8`] is a signed eight-bit fixed-point number,
|
|
|
|
|
* [`FixedI16`] is a signed 16-bit fixed-point number,
|
|
|
|
|
* [`FixedI32`] is a signed 32-bit fixed-point number,
|
|
|
|
|
* [`FixedI64`] is a signed 64-bit fixed-point number,
|
|
|
|
|
* [`FixedI128`] is a signed 128-bit fixed-point number,
|
|
|
|
|
* [`FixedU8`] is an unsigned eight-bit fixed-point number,
|
|
|
|
|
* [`FixedU16`] is an unsigned 16-bit fixed-point number,
|
|
|
|
|
* [`FixedU32`] is an unsigned 32-bit fixed-point number,
|
|
|
|
|
* [`FixedU64`] is an unsigned 64-bit fixed-point number, and
|
|
|
|
|
* [`FixedU128`] is an unsigned 128-bit fixed-point number.
|
|
|
|
|
|
|
|
|
|
All fixed-point numbers can have `Frac` fractional bits, where `Frac`
|
|
|
|
|
can have any value from 0 up to and including the size of the number
|
|
|
|
|
in bits. When `Frac` is 0, the fixed-point number behaves like an
|
|
|
|
|
integer. When `Frac` is equal to the number of bits, the value of the
|
|
|
|
|
fixed-point number lies in the range −0.5 ≤ *x* < 0.5 for signed
|
|
|
|
|
fixed-point numbers, and in the range 0 ≤ *x* < 1 for unsigned
|
|
|
|
|
fixed-point numbers.
|
2018-08-10 02:13:42 -07:00
|
|
|
|
|
2018-08-10 11:57:59 -07:00
|
|
|
|
## What’s new
|
|
|
|
|
|
2018-11-03 09:23:18 -07:00
|
|
|
|
### Version 0.1.4 news (unreleased)
|
|
|
|
|
|
|
|
|
|
* Division is now implemented for [`FixedI128`] and [`FixedU128`].
|
|
|
|
|
|
2018-08-23 04:32:59 -07:00
|
|
|
|
### Version 0.1.3 news (2018-08-23)
|
2018-08-23 04:12:32 -07:00
|
|
|
|
|
2018-08-23 04:32:59 -07:00
|
|
|
|
* The `f16` feature was added, and new methods [`from_f16`] and
|
|
|
|
|
[`to_f16`] were added.
|
2018-08-23 04:12:32 -07:00
|
|
|
|
|
|
|
|
|
[`from_f16`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.from_f16
|
|
|
|
|
[`to_f16`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.to_f16
|
|
|
|
|
|
2018-08-15 11:14:36 -07:00
|
|
|
|
### Version 0.1.2 news (2018-08-15)
|
2018-08-12 03:11:28 -07:00
|
|
|
|
|
|
|
|
|
* The crate can now be used without the standard library `std`.
|
2018-08-13 15:21:29 -07:00
|
|
|
|
* New methods [`from_f32`] and [`from_f64`] were added.
|
2018-08-14 08:47:29 -07:00
|
|
|
|
* New methods [`is_positive`] and [`is_negative`] were added to
|
|
|
|
|
signed fixed-point numbers.
|
2018-08-13 15:21:29 -07:00
|
|
|
|
|
2018-08-23 04:32:59 -07:00
|
|
|
|
[`from_f32`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.from_f32
|
|
|
|
|
[`from_f64`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.from_f64
|
|
|
|
|
[`is_negative`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.is_negative
|
|
|
|
|
[`is_positive`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.is_positive
|
2018-08-12 03:11:28 -07:00
|
|
|
|
|
2018-08-11 12:10:03 -07:00
|
|
|
|
### Version 0.1.1 news (2018-08-11)
|
2018-08-10 12:28:24 -07:00
|
|
|
|
|
2018-08-11 11:21:29 -07:00
|
|
|
|
* Comparisons are now supported between all fixed-point numbers with
|
|
|
|
|
the same underlying integer type.
|
2018-08-10 12:28:24 -07:00
|
|
|
|
* New static methods [`int_bits`] and [`frac_bits`] were added.
|
2018-08-11 08:19:17 -07:00
|
|
|
|
* 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.
|
2018-08-10 15:28:31 -07:00
|
|
|
|
* Support for multiplication and division by integers was added.
|
2018-08-10 12:28:24 -07:00
|
|
|
|
|
2018-08-23 04:32:59 -07:00
|
|
|
|
[`frac_bits`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.frac_bits
|
|
|
|
|
[`frac`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.frac
|
|
|
|
|
[`from_int`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.from_int
|
|
|
|
|
[`int_bits`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.int_bits
|
|
|
|
|
[`to_int_ceil`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.to_int_ceil
|
|
|
|
|
[`to_int_floor`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.to_int_floor
|
|
|
|
|
[`to_int_round`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.to_int_round
|
|
|
|
|
[`to_int`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.to_int
|
|
|
|
|
[`int`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html#method.int
|
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
|
|
|
|
|
|
2018-08-11 08:33:31 -07:00
|
|
|
|
## Quick example
|
|
|
|
|
|
|
|
|
|
```rust
|
|
|
|
|
use fixed::frac;
|
|
|
|
|
use fixed::FixedI32;
|
|
|
|
|
|
|
|
|
|
// 20 integer bits, 12 fractional bits
|
|
|
|
|
type I20F12 = FixedI32<frac::U12>;
|
2018-08-11 08:49:36 -07:00
|
|
|
|
// 19/3 = 6 1/3
|
|
|
|
|
let six_and_third = I20F12::from_int(19).unwrap() / 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");
|
2018-08-11 08:33:31 -07:00
|
|
|
|
// convert to i32, taking the ceil
|
2018-08-11 08:49:36 -07:00
|
|
|
|
assert_eq!(six_and_third.to_int_ceil(), 7);
|
2018-08-11 08:33:31 -07:00
|
|
|
|
```
|
|
|
|
|
|
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]
|
2018-08-23 04:32:59 -07:00
|
|
|
|
fixed = "0.1.3"
|
2018-08-10 02:13:42 -07:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
You also need to declare it by adding this to your crate root (usually
|
|
|
|
|
*lib.rs* or *main.rs*):
|
|
|
|
|
|
|
|
|
|
```rust
|
|
|
|
|
extern crate fixed;
|
|
|
|
|
```
|
|
|
|
|
|
2018-08-13 03:10:53 -07:00
|
|
|
|
The *fixed* crate requires rustc version 1.28.0 or later.
|
|
|
|
|
|
2018-08-23 04:12:32 -07:00
|
|
|
|
## Optional features
|
|
|
|
|
|
|
|
|
|
The *fixed* crate has one optional feature:
|
|
|
|
|
|
|
|
|
|
1. `f16`, disabled by default. This provides conversion to/from
|
|
|
|
|
[`f16`]. This features requires the [*half* crate].
|
|
|
|
|
|
|
|
|
|
To enable the feature, you can add the dependency like this to
|
|
|
|
|
[*Cargo.toml*]:
|
|
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[dependencies.fixed]
|
2018-08-23 04:32:59 -07:00
|
|
|
|
version = "0.1.3"
|
2018-08-23 04:12:32 -07:00
|
|
|
|
features = ["f16"]
|
|
|
|
|
```
|
|
|
|
|
|
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
|
2018-08-10 11:30:03 -07:00
|
|
|
|
[*fixed* crate]: https://crates.io/crates/fixed
|
2018-08-23 04:12:32 -07:00
|
|
|
|
[*half* crate]: https://crates.io/crates/half
|
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
|
2018-08-23 04:32:59 -07:00
|
|
|
|
[`FixedI128`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI128.html
|
|
|
|
|
[`FixedI16`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI16.html
|
|
|
|
|
[`FixedI32`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI32.html
|
|
|
|
|
[`FixedI64`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI64.html
|
|
|
|
|
[`FixedI8`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedI8.html
|
|
|
|
|
[`FixedU128`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedU128.html
|
|
|
|
|
[`FixedU16`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedU16.html
|
|
|
|
|
[`FixedU32`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedU32.html
|
|
|
|
|
[`FixedU64`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedU64.html
|
|
|
|
|
[`FixedU8`]: https://docs.rs/fixed/0.1.3/fixed/struct.FixedU8.html
|
2018-08-23 04:12:32 -07:00
|
|
|
|
[`f16`]: https://docs.rs/half/^1/half/struct.f16.html
|
2018-08-10 02:13:42 -07:00
|
|
|
|
[channels]: https://doc.rust-lang.org/book/second-edition/appendix-07-nightly-rust.html
|
2018-08-09 11:02:34 -07:00
|
|
|
|
[const generics]: https://github.com/rust-lang/rust/issues/44580
|