blockworks-foundation
/
fixed
mirror of https://github.com/blockworks-foundation/fixed.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update README and doc main page

This commit is contained in:
Trevor Spiteri 2019-08-24 13:10:49 +02:00
parent 97e57bad0e
commit 82c7781f0e
2 changed files with 96 additions and 116 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
README.md
View File

@ -7,68 +7,58 @@ as-is, without any warranty. -->
# Fixed-point numbers # Fixed-point numbers
The [*fixed* crate] provides fixed-point numbers. Currently it uses The [*fixed* crate] provides fixed-point numbers.
the [*typenum* crate] for the fractional bit count; it is planned to
move to [const generics] when they are implemented by the Rust
compiler.
The crate provides the following types: * [`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.
* [`FixedI8`] is a signed eight-bit fixed-point number, These types can have `Frac` fractional bits, where 0 ≤ `Frac` ≤ *n*
* [`FixedI16`] is a signed 16-bit fixed-point number, and *n* is the total number of bits. When `Frac` = 0, the fixed-point
* [`FixedI32`] is a signed 32-bit fixed-point number, number behaves like an *n*-bit integer. When `Frac` = *n*, the value
* [`FixedI64`] is a signed 64-bit fixed-point number, *x* lies in the range −0.5 ≤ *x* < 0.5 for signed numbers, and in the
* [`FixedI128`] is a signed 128-bit fixed-point number, range 0 ≤ *x* < 1 for unsigned numbers.
* [`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` Currently the [*typenum* crate] is used for the fractional bit count
can have any value from 0 up to and including the size of the number `Frac`; it is planned to move to [const generics] when they are
in bits. When `Frac` is 0, the fixed-point number behaves like an supported by the Rust compiler.
integer. When `Frac` is equal to the number of bits, the value lies in
the range −0.5 ≤ *x* < 0.5 for signed numbers, and in the range
0 ≤ *x* < 1 for unsigned numbers.
The main features of this crate are: The main features are
* Representation of all fixed-point numbers up to 128 bits wide. * Representation of fixed-point numbers up to 128 bits wide.
* Comprehensive conversion support between fixed-point numbers and * Conversions between fixed-point numbers and numeric primitives.
numeric primitives. * Comparisons between fixed-point numbers and numeric primitives.
* Comprehensive comparison support between fixed-point numbers and * Parsing from strings in decimal, binary, octal and hexadecimal.
numeric primitives. * Display as decimal, binary, octal and hexadecimal.
* Parsing of fixed-point numbers from strings in decimal, binary, * Arithmetic and logic operations.
octal and hexadecimal.
* Display of fixed-point numbers as decimal, binary, octal and
hexadecimal.
* Arithmetic and logic operations on all fixed-point numbers.
This crate does *not* provide the following: This crate does *not* provide general analytic functions.
* Algebraic functions like the square root and power functions. * No algebraic functions are provided, for example no `sqrt` or
* Trigonometric functions like the sine and cosine functions. `pow`.
* Other transcendental functions like logs and the exponential * No trigonometric functions are provided, for example no `sin` or
function. `cos`.
* No other transcendental functions are provided: for example no
`log` or `exp`.
The conversions supported cover the following cases. The conversions supported cover the following cases.
* For all lossless infallible conversions between fixed-point * Infallible lossless conversions between fixed-point numbers and
numbers and numeric primitives, you can use [`From`] or [`Into`]. numeric primitives are provided using [`From`] and [`Into`]. These
These conversions always work (infallible) without losing any bits never fail (infallible) and do not lose any bits (lossless).
(lossless). * Infallible lossy conversions between fixed-point numbers and
* For lossy infallible conversions between fixed-point numbers and numeric primitives are provided using the [`LossyFrom`] and
numeric primitives, you can use the [`LossyFrom`] and [`LossyInto`] traits. The source can have more fractional bits
[`LossyInto`] traits. The source type may have more fractional than the destination.
bits than the destination. * Checked conversions between fixed-point numbers and numeric
* Checked conversions are provided between fixed-point numbers and primitives are provided using the [`FromFixed`] and [`ToFixed`]
all numeric primitives using the [`FromFixed`] and [`ToFixed`] traits, or using the [`from_num`] and [`to_num`] methods and
traits, or using the [`from_num`] and [`to_num`] methods and their [their checked versions][`checked_from_num`].
checked versions.
* Fixed-point numbers can be parsed from decimal strings using * Fixed-point numbers can be parsed from decimal strings using
[`FromStr`], or from binary, octal or hexadecimal strings using [`FromStr`], and from binary, octal and hexadecimal strings using
the [`from_str_binary`], [`from_str_octal`] or [`from_str_hex`] the [`from_str_binary`], [`from_str_octal`] and [`from_str_hex`]
methods. The result is rounded to the nearest, with ties rounded methods. The result is rounded to the nearest, with ties rounded
to even. to even.
* Fixed-point numbers can be converted to strings using [`Display`], * Fixed-point numbers can be converted to strings using [`Display`],
@ -219,7 +209,6 @@ Details on other releases can be found in [*RELEASES.md*].
## Quick examples ## Quick examples
```rust ```rust
// 20 integer bits, 12 fractional bits
use fixed::types::I20F12; use fixed::types::I20F12;
// 19/3 = 6 1/3 // 19/3 = 6 1/3
@ -234,14 +223,15 @@ assert_eq!(six_and_third.ceil(), 7);
The type [`I20F12`] is a 32-bit fixed-point signed number with 20 The type [`I20F12`] is a 32-bit fixed-point signed number with 20
integer bits and 12 fractional bits. It is an alias to integer bits and 12 fractional bits. It is an alias to
<code>[FixedI32][`FixedI32`]&lt;[U12][`U12`]&gt;</code>. <code>[FixedI32][`FixedI32`]&lt;[U12][`U12`]&gt;</code>. The unsigned
The unsigned counterpart would be [`U20F12`]. Aliases are provided for counterpart would be [`U20F12`]. Aliases are provided for all
all combinations of integer and fractional bits adding up to a total combinations of integer and fractional bits adding up to a total of
of eight, 16, 32, 64 or 128 bits. eight, 16, 32, 64 or 128 bits.
```rust ```rust
use fixed::types::{I4F4, I4F12};
// −8 ≤ I4F4 < 8 with steps of 1/16 (~0.06) // −8 ≤ I4F4 < 8 with steps of 1/16 (~0.06)
use fixed::types::I4F4;
let a = I4F4::from_num(1); let a = I4F4::from_num(1);
// multiplication and division by integers are possible // multiplication and division by integers are possible
let ans1 = a / 5 * 17; let ans1 = a / 5 * 17;
@ -250,7 +240,6 @@ assert_eq!(ans1, I4F4::from_bits((3 << 4) + 3));
assert_eq!(ans1.to_string(), "3.2"); assert_eq!(ans1.to_string(), "3.2");
// −8 ≤ I4F12 < 8 with steps of 1/4096 (~0.0002) // −8 ≤ I4F12 < 8 with steps of 1/4096 (~0.0002)
use fixed::types::I4F12;
let wider_a = I4F12::from(a); let wider_a = I4F12::from(a);
let wider_ans = wider_a / 5 * 17; let wider_ans = wider_a / 5 * 17;
let ans2 = I4F4::from_num(wider_ans); let ans2 = I4F4::from_num(wider_ans);
@ -354,6 +343,7 @@ additional terms or conditions.
[`U12`]: https://docs.rs/fixed/0.4.3/fixed/types/extra/type.U12.html [`U12`]: https://docs.rs/fixed/0.4.3/fixed/types/extra/type.U12.html
[`U20F12`]: https://docs.rs/fixed/0.4.3/fixed/types/type.U20F12.html [`U20F12`]: https://docs.rs/fixed/0.4.3/fixed/types/type.U20F12.html
[`UpperHex`]: https://doc.rust-lang.org/nightly/std/fmt/trait.UpperHex.html [`UpperHex`]: https://doc.rust-lang.org/nightly/std/fmt/trait.UpperHex.html
[`checked_from_num`]: https://docs.rs/fixed/0.4.3/fixed/struct.FixedI32.html#method.checked_from_num
[`f16`]: https://docs.rs/half/^1/half/struct.f16.html [`f16`]: https://docs.rs/half/^1/half/struct.f16.html
[`from_num`]: https://docs.rs/fixed/0.4.3/fixed/struct.FixedI32.html#method.from_num [`from_num`]: https://docs.rs/fixed/0.4.3/fixed/struct.FixedI32.html#method.from_num
[`from_str_binary`]: https://docs.rs/fixed/0.4.3/fixed/struct.FixedI32.html#method.from_str_binary [`from_str_binary`]: https://docs.rs/fixed/0.4.3/fixed/struct.FixedI32.html#method.from_str_binary

106
src/lib.rs
View File

@ -16,68 +16,58 @@
/*! /*!
# Fixed-point numbers # Fixed-point numbers
The [*fixed* crate] provides fixed-point numbers. Currently it uses The [*fixed* crate] provides fixed-point numbers.
the [*typenum* crate] for the fractional bit count; it is planned to
move to [const generics] when they are implemented by the Rust
compiler.
The crate provides the following types: * [`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.
* [`FixedI8`] is a signed eight-bit fixed-point number, These types can have `Frac` fractional bits, where 0 ≤ `Frac` ≤ *n*
* [`FixedI16`] is a signed 16-bit fixed-point number, and *n* is the total number of bits. When `Frac` = 0, the fixed-point
* [`FixedI32`] is a signed 32-bit fixed-point number, number behaves like an *n*-bit integer. When `Frac` = *n*, the value
* [`FixedI64`] is a signed 64-bit fixed-point number, *x* lies in the range −0.5 ≤ *x* < 0.5 for signed numbers, and in the
* [`FixedI128`] is a signed 128-bit fixed-point number, range 0 ≤ *x* < 1 for unsigned numbers.
* [`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` Currently the [*typenum* crate] is used for the fractional bit count
can have any value from 0 up to and including the size of the number `Frac`; it is planned to move to [const generics] when they are
in bits. When `Frac` is 0, the fixed-point number behaves like an supported by the Rust compiler.
integer. When `Frac` is equal to the number of bits, the value lies in
the range −0.5 ≤ **x** < 0.5 for signed numbers, and in the range
0 ≤ **x** < 1 for unsigned numbers.
The main features of this crate are: The main features are
* Representation of all fixed-point numbers up to 128 bits wide. * Representation of fixed-point numbers up to 128 bits wide.
* Comprehensive conversion support between fixed-point numbers and * Conversions between fixed-point numbers and numeric primitives.
numeric primitives. * Comparisons between fixed-point numbers and numeric primitives.
* Comprehensive comparison support between fixed-point numbers and * Parsing from strings in decimal, binary, octal and hexadecimal.
numeric primitives. * Display as decimal, binary, octal and hexadecimal.
* Parsing of fixed-point numbers from strings in decimal, binary, * Arithmetic and logic operations.
octal and hexadecimal.
* Display of fixed-point numbers as decimal, binary, octal and
hexadecimal.
* Arithmetic and logic operations on all fixed-point numbers.
This crate does **not** provide the following: This crate does *not* provide general analytic functions.
* Algebraic functions like the square root and power functions. * No algebraic functions are provided, for example no `sqrt` or
* Trigonometric functions like the sine and cosine functions. `pow`.
* Other transcendental functions like logs and the exponential * No trigonometric functions are provided, for example no `sin` or
function. `cos`.
* No other transcendental functions are provided: for example no
`log` or `exp`.
The conversions supported cover the following cases. The conversions supported cover the following cases.
* For all lossless infallible conversions between fixed-point * Infallible lossless conversions between fixed-point numbers and
numbers and numeric primitives, you can use [`From`] or [`Into`]. numeric primitives are provided using [`From`] and [`Into`]. These
These conversions always work (infallible) without losing any bits never fail (infallible) and do not lose any bits (lossless).
(lossless). * Infallible lossy conversions between fixed-point numbers and
* For lossy infallible conversions between fixed-point numbers and numeric primitives are provided using the [`LossyFrom`] and
numeric primitives, you can use the [`LossyFrom`] and [`LossyInto`] traits. The source can have more fractional bits
[`LossyInto`] traits. The source type may have more fractional than the destination.
bits than the destination. * Checked conversions between fixed-point numbers and numeric
* Checked conversions are provided between fixed-point numbers and primitives are provided using the [`FromFixed`] and [`ToFixed`]
all numeric primitives using the [`FromFixed`] and [`ToFixed`] traits, or using the [`from_num`] and [`to_num`] methods and
traits, or using the [`from_num`] and [`to_num`] methods and their [their checked versions][`checked_from_num`].
checked versions.
* Fixed-point numbers can be parsed from decimal strings using * Fixed-point numbers can be parsed from decimal strings using
[`FromStr`], or from binary, octal or hexadecimal strings using [`FromStr`], and from binary, octal and hexadecimal strings using
the [`from_str_binary`], [`from_str_octal`] or [`from_str_hex`] the [`from_str_binary`], [`from_str_octal`] and [`from_str_hex`]
methods. The result is rounded to the nearest, with ties rounded methods. The result is rounded to the nearest, with ties rounded
to even. to even.
* Fixed-point numbers can be converted to strings using [`Display`], * Fixed-point numbers can be converted to strings using [`Display`],
@ -87,7 +77,6 @@ The conversions supported cover the following cases.
## Quick examples ## Quick examples
```rust ```rust
// 20 integer bits, 12 fractional bits
use fixed::types::I20F12; use fixed::types::I20F12;
// 19/3 = 6 1/3 // 19/3 = 6 1/3
@ -102,14 +91,15 @@ assert_eq!(six_and_third.ceil(), 7);
The type [`I20F12`] is a 32-bit fixed-point signed number with 20 The type [`I20F12`] is a 32-bit fixed-point signed number with 20
integer bits and 12 fractional bits. It is an alias to integer bits and 12 fractional bits. It is an alias to
<code>[FixedI32][`FixedI32`]&lt;[U12][`U12`]&gt;</code>. <code>[FixedI32][`FixedI32`]&lt;[U12][`U12`]&gt;</code>. The unsigned
The unsigned counterpart would be [`U20F12`]. Aliases are provided for counterpart would be [`U20F12`]. Aliases are provided for all
all combinations of integer and fractional bits adding up to a total combinations of integer and fractional bits adding up to a total of
of eight, 16, 32, 64 or 128 bits. eight, 16, 32, 64 or 128 bits.
```rust ```rust
use fixed::types::{I4F4, I4F12};
// −8 ≤ I4F4 < 8 with steps of 1/16 (~0.06) // −8 ≤ I4F4 < 8 with steps of 1/16 (~0.06)
use fixed::types::I4F4;
let a = I4F4::from_num(1); let a = I4F4::from_num(1);
// multiplication and division by integers are possible // multiplication and division by integers are possible
let ans1 = a / 5 * 17; let ans1 = a / 5 * 17;
@ -118,7 +108,6 @@ assert_eq!(ans1, I4F4::from_bits((3 << 4) + 3));
assert_eq!(ans1.to_string(), "3.2"); assert_eq!(ans1.to_string(), "3.2");
// −8 ≤ I4F12 < 8 with steps of 1/4096 (~0.0002) // −8 ≤ I4F12 < 8 with steps of 1/4096 (~0.0002)
use fixed::types::I4F12;
let wider_a = I4F12::from(a); let wider_a = I4F12::from(a);
let wider_ans = wider_a / 5 * 17; let wider_ans = wider_a / 5 * 17;
let ans2 = I4F4::from_num(wider_ans); let ans2 = I4F4::from_num(wider_ans);
@ -222,6 +211,7 @@ additional terms or conditions.
[`U12`]: types/extra/type.U12.html [`U12`]: types/extra/type.U12.html
[`U20F12`]: types/type.U20F12.html [`U20F12`]: types/type.U20F12.html
[`UpperHex`]: https://doc.rust-lang.org/nightly/std/fmt/trait.UpperHex.html [`UpperHex`]: https://doc.rust-lang.org/nightly/std/fmt/trait.UpperHex.html
[`checked_from_num`]: struct.FixedI32.html#method.checked_from_num
[`f16`]: https://docs.rs/half/^1/half/struct.f16.html [`f16`]: https://docs.rs/half/^1/half/struct.f16.html
[`from_num`]: struct.FixedI32.html#method.from_num [`from_num`]: struct.FixedI32.html#method.from_num
[`from_str_binary`]: struct.FixedI32.html#method.from_str_binary [`from_str_binary`]: struct.FixedI32.html#method.from_str_binary