update README and doc main page
This commit is contained in:
parent
97e57bad0e
commit
82c7781f0e
106
README.md
106
README.md
|
@ -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`]<[U12][`U12`]></code>.
|
<code>[FixedI32][`FixedI32`]<[U12][`U12`]></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
106
src/lib.rs
|
@ -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`]<[U12][`U12`]></code>.
|
<code>[FixedI32][`FixedI32`]<[U12][`U12`]></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
|
||||||
|
|
Loading…
Reference in New Issue