From 82c7781f0e07ee265469f6648e588d06766ee853 Mon Sep 17 00:00:00 2001 From: Trevor Spiteri Date: Sat, 24 Aug 2019 13:10:49 +0200 Subject: [PATCH] update README and doc main page --- README.md | 106 ++++++++++++++++++++++++----------------------------- src/lib.rs | 106 ++++++++++++++++++++++++----------------------------- 2 files changed, 96 insertions(+), 116 deletions(-) diff --git a/README.md b/README.md index 80167e4..7c331d6 100644 --- a/README.md +++ b/README.md @@ -7,68 +7,58 @@ as-is, without any warranty. --> # Fixed-point numbers -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 -compiler. +The [*fixed* crate] provides fixed-point numbers. -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, - * [`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. +These types can have `Frac` fractional bits, where 0 ≤ `Frac` ≤ *n* +and *n* is the total number of bits. When `Frac` = 0, the fixed-point +number behaves like an *n*-bit integer. When `Frac` = *n*, the value +*x* lies in the range −0.5 ≤ *x* < 0.5 for signed numbers, and in the +range 0 ≤ *x* < 1 for unsigned numbers. -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 lies in -the range −0.5 ≤ *x* < 0.5 for signed numbers, and in the range -0 ≤ *x* < 1 for unsigned numbers. +Currently the [*typenum* crate] is used for the fractional bit count +`Frac`; it is planned to move to [const generics] when they are +supported by the Rust compiler. -The main features of this crate are: +The main features are - * Representation of all fixed-point numbers up to 128 bits wide. - * Comprehensive conversion support between fixed-point numbers and - numeric primitives. - * Comprehensive comparison support between fixed-point numbers and - numeric primitives. - * Parsing of fixed-point numbers from strings in decimal, binary, - octal and hexadecimal. - * Display of fixed-point numbers as decimal, binary, octal and - hexadecimal. - * Arithmetic and logic operations on all fixed-point numbers. + * 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 the following: +This crate does *not* provide general analytic functions. - * Algebraic functions like the square root and power functions. - * Trigonometric functions like the sine and cosine functions. - * Other transcendental functions like logs and the exponential - function. + * 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`. The conversions supported cover the following cases. - * For all lossless infallible conversions between fixed-point - numbers and numeric primitives, you can use [`From`] or [`Into`]. - These conversions always work (infallible) without losing any bits - (lossless). - * For lossy infallible conversions between fixed-point numbers and - numeric primitives, you can use the [`LossyFrom`] and - [`LossyInto`] traits. The source type may have more fractional - bits than the destination. - * Checked conversions are provided between fixed-point numbers and - all numeric primitives using the [`FromFixed`] and [`ToFixed`] - traits, or using the [`from_num`] and [`to_num`] methods and their - checked versions. + * 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 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`], or from binary, octal or hexadecimal strings using - the [`from_str_binary`], [`from_str_octal`] or [`from_str_hex`] + [`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`], @@ -219,7 +209,6 @@ Details on other releases can be found in [*RELEASES.md*]. ## Quick examples ```rust -// 20 integer bits, 12 fractional bits use fixed::types::I20F12; // 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 integer bits and 12 fractional bits. It is an alias to -[FixedI32][`FixedI32`]<[U12][`U12`]>. -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. +[FixedI32][`FixedI32`]<[U12][`U12`]>. 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}; + // −8 ≤ I4F4 < 8 with steps of 1/16 (~0.06) -use fixed::types::I4F4; let a = I4F4::from_num(1); // multiplication and division by integers are possible 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"); // −8 ≤ I4F12 < 8 with steps of 1/4096 (~0.0002) -use fixed::types::I4F12; let wider_a = I4F12::from(a); let wider_ans = wider_a / 5 * 17; 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 [`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 +[`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 [`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 diff --git a/src/lib.rs b/src/lib.rs index 1097f3f..12cc2e0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -16,68 +16,58 @@ /*! # Fixed-point numbers -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 -compiler. +The [*fixed* crate] provides fixed-point numbers. -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, - * [`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. +These types can have `Frac` fractional bits, where 0 ≤ `Frac` ≤ *n* +and *n* is the total number of bits. When `Frac` = 0, the fixed-point +number behaves like an *n*-bit integer. When `Frac` = *n*, the value +*x* lies in the range −0.5 ≤ *x* < 0.5 for signed numbers, and in the +range 0 ≤ *x* < 1 for unsigned numbers. -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 lies in -the range −0.5 ≤ **x** < 0.5 for signed numbers, and in the range -0 ≤ **x** < 1 for unsigned numbers. +Currently the [*typenum* crate] is used for the fractional bit count +`Frac`; it is planned to move to [const generics] when they are +supported by the Rust compiler. -The main features of this crate are: +The main features are - * Representation of all fixed-point numbers up to 128 bits wide. - * Comprehensive conversion support between fixed-point numbers and - numeric primitives. - * Comprehensive comparison support between fixed-point numbers and - numeric primitives. - * Parsing of fixed-point numbers from strings in decimal, binary, - octal and hexadecimal. - * Display of fixed-point numbers as decimal, binary, octal and - hexadecimal. - * Arithmetic and logic operations on all fixed-point numbers. + * 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 the following: +This crate does *not* provide general analytic functions. - * Algebraic functions like the square root and power functions. - * Trigonometric functions like the sine and cosine functions. - * Other transcendental functions like logs and the exponential - function. + * 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`. The conversions supported cover the following cases. - * For all lossless infallible conversions between fixed-point - numbers and numeric primitives, you can use [`From`] or [`Into`]. - These conversions always work (infallible) without losing any bits - (lossless). - * For lossy infallible conversions between fixed-point numbers and - numeric primitives, you can use the [`LossyFrom`] and - [`LossyInto`] traits. The source type may have more fractional - bits than the destination. - * Checked conversions are provided between fixed-point numbers and - all numeric primitives using the [`FromFixed`] and [`ToFixed`] - traits, or using the [`from_num`] and [`to_num`] methods and their - checked versions. + * 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 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`], or from binary, octal or hexadecimal strings using - the [`from_str_binary`], [`from_str_octal`] or [`from_str_hex`] + [`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`], @@ -87,7 +77,6 @@ The conversions supported cover the following cases. ## Quick examples ```rust -// 20 integer bits, 12 fractional bits use fixed::types::I20F12; // 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 integer bits and 12 fractional bits. It is an alias to -[FixedI32][`FixedI32`]<[U12][`U12`]>. -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. +[FixedI32][`FixedI32`]<[U12][`U12`]>. 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}; + // −8 ≤ I4F4 < 8 with steps of 1/16 (~0.06) -use fixed::types::I4F4; let a = I4F4::from_num(1); // multiplication and division by integers are possible 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"); // −8 ≤ I4F12 < 8 with steps of 1/4096 (~0.0002) -use fixed::types::I4F12; let wider_a = I4F12::from(a); let wider_ans = wider_a / 5 * 17; let ans2 = I4F4::from_num(wider_ans); @@ -222,6 +211,7 @@ additional terms or conditions. [`U12`]: types/extra/type.U12.html [`U20F12`]: types/type.U20F12.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 [`from_num`]: struct.FixedI32.html#method.from_num [`from_str_binary`]: struct.FixedI32.html#method.from_str_binary