Merge pull request #35 from isaacholt100/v0.9.1

v0.9.1

.github/workflows/cargo-msrv.yml

@@ -0,0 +1,26 @@
+name: Verify MSRV
+
+on:
+  push:
+    branches: "**"
+  pull_request:
+    branches: "**"
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  cargo-msrv:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust
+        run: rustup update nightly
+      - name: Set nightly as default
+        run: rustup default nightly
+      - name: Install cargo-binstall
+        uses: taiki-e/install-action@cargo-binstall
+      - name: Install cargo-msrv
+        run: cargo binstall cargo-msrv --no-confirm
+      - name: verify MSRV
+        run: cargo msrv verify

Cargo.toml

@@ -1,16 +1,17 @@
 [package]
 name = "bnum"
-version = "0.9.0"
+version = "0.9.1"
 authors = ["isaac-holt <[email protected]>"]
 edition = "2021"
 license = "MIT OR Apache-2.0"
-description = "Arbitrary, fixed size numeric types that extend the functionality of primitive numeric types in Rust."
+description = "Arbitrary, fixed size numeric types that extend the functionality of primitive numeric types."
 homepage = "https://github.com/isaacholt100/bnum"
 documentation = "https://docs.rs/bnum/latest/bnum"
 repository = "https://github.com/isaacholt100/bnum"
 readme = "README.md"
 keywords = ["uint", "int", "bignum", "maths", "arbitrary"]
 categories = ["algorithms", "mathematics", "cryptography", "no-std"]
+rust-version = "1.65"
 
 exclude = ["src/float/*", "src/tests", "TODO.txt", "lit-parser/*"] # TODO: make sure to include these when they are ready
 

README.md

@@ -16,29 +16,29 @@ The aim of this crate is to provide integer types of arbitrary fixed size which
 
 This crate uses Rust's const generics to allow creation of integers of arbitrary size that can be determined at compile time. Unsigned integers are stored as an array of digits (primitive unsigned integers) of length `N`. This means all `bnum` integers can be stored on the stack, as they are fixed size. Signed integers are simply stored as an unsigned integer in two's complement.
 
-`bnum` defines 4 unsigned integer types: each uses a different primitive integer as its digit type. `BUint` uses `u64` as its digit, `BUintD32` uses `u32`, `BUintD16` uses `u16` and `BUintD8` uses `u8`. The signed integer types, `BInt`, `BIntD32`, `BIntD16` and `BIntD8` are represented by these unsigned integers respectively.
+`bnum` defines 4 unsigned integer types: each uses a different primitive integer as its digit type. `BUint` uses `u64` as its digit, `BUintD32` uses `u32`, `BUintD16` uses `u16` and `BUintD8` uses `u8`. The signed integer types `BInt`, `BIntD32`, `BIntD16` and `BIntD8` are represented by these unsigned integers respectively.
 
-`BUint` and `BInt` are the fastest as they store (and so operate on) the least number of digits for a given bit size. However, the drawback is that the bit size must be a multiple of `64` (`bitsize = N * 64`). This is why other integer types are provided as well, as they allow the bit size to be a multiple of `32`, `16`, or `8` instead. When choosing which of these types to use, determine which of `64, 32, 16, 8` is the largest multiple of the desired bit size, and use the corresponding type. For example, if you wanted a 96-bit unsigned integer, 32 is the largest multiple of 96 out of these, so use `BUintD32<3>`. A 40-bit signed integer would be `BIntD8<5>`.
+`BUint` and `BInt` are the fastest as they store (and so operate on) the least number of digits for a given bit size. However, the drawback is that the bit size must be a multiple of `64` (`bitsize = N * 64`). This is why other integer types are provided as well, as they allow the bit size to be a multiple of `32`, `16` or `8` instead. When choosing which of these types to use, determine which of `64, 32, 16, 8` is the largest divisor of the desired bit size, and use the corresponding type. For example, if you wanted a 96-bit unsigned integer, 32 is the largest divisor of 96 out of these, so use `BUintD32<3>`. A 40-bit signed integer would be `BIntD8<5>`.
 
 ## Why bnum?
 
 - **Zero dependencies by default**: `bnum` does not depend on any other crates by default. Support for crates such as [`rand`](https://docs.rs/rand/latest/rand/) and [`serde`](https://docs.rs/serde/latest/serde/) can be enabled with crate [features](#features).
 - **`no-std` compatible**: `bnum` can be used in `no_std` environments, provided that the [`arbitrary`](#fuzzing) and [`quickcheck`](#quickcheck) features are not enabled.
-- **Compile-time integer parsing**: the `from_str_radix` and `parse_str_radix` methods on `bnum` integers are `const`, which allows parsing of integers from string slices at compile time. Note that this is more powerful than compile-time parsing of integer literals. This is because it allows parsing of strings in all radices from `2` to `36` inclusive instead of just `2`, `8`, `10` and `16`. Additionally, the string to be parsed does not have to be a literal: it could, for example, be obtained via `include_str!("...")`, or `env!("...")`.
+- **Compile-time integer parsing**: the `from_str_radix` and `parse_str_radix` methods on `bnum` integers are `const`, which allows parsing of integers from string slices at compile time. Note that this is more powerful than compile-time parsing of integer literals. This is because it allows parsing of strings in all radices from `2` to `36` inclusive instead of just `2`, `8`, `10` and `16`. Additionally, the string to be parsed does not have to be a literal: it could, for example, be obtained via [`include_str!`](https://doc.rust-lang.org/core/macro.include_str.html), or [`env!`](https://doc.rust-lang.org/core/macro.env.html)`.
 - **`const` evaluation**: nearly all methods defined on `bnum` integers are `const`, which allows complex compile-time calculations.
 
 ## Installation
 
 To install and use `bnum`, simply add the following line to your `Cargo.toml` file in the `[dependencies]` section:
 
 ```toml
-bnum = "0.9.0"
+bnum = "0.9.1"
 ```
 
 Or, to enable various `bnum` features as well, add for example this line instead:
 
 ```toml
-bnum = { version = "0.9.0", features = ["rand"] } # enables the "rand" feature
+bnum = { version = "0.9.1", features = ["rand"] } # enables the "rand" feature
 ```
 
 ## Example Usage
@@ -90,12 +90,12 @@ assert_eq!(f_n, U512::from_str_radix("354224848179261915075", 10).unwrap());
 
 ```rust
 // Construct an 80-bit signed integer
-// Out of [64, 32, 16, 8], 16 is the largest multiple of 80, so use `BIntD16`
+// Out of [64, 32, 16, 8], 16 is the largest divisor of 80, so use `BIntD16`
 use bnum::BIntD16;
 
 type I80 = BIntD16<5>; // 80 / 16 = 5
 
-let neg_one = I80::NEG_ONE;
+let neg_one = I80::NEG_ONE; // -1
 assert_eq!(neg_one.count_ones(), 80); // signed integers are stored in two's complement so `-1` is represented as `111111...`
 ```
 
@@ -119,7 +119,7 @@ The `numtraits` feature includes implementations of traits from the [`num_traits
 
 ### Quickcheck
 
-The `quickcheck` feature enables the [`Arbitrary`](https://docs.rs/quickcheck/latest/quickcheck/trait.Arbitrary.html) trait from the [`quickcheck`](https://docs.rs/quickcheck/latest/quickcheck/) crate. **Note: currently, this feature cannot be used with `no_std` (see <https://github.com/rust-fuzz/arbitrary/issues/38>).**
+The `quickcheck` feature enables the [`Arbitrary`](https://docs.rs/quickcheck/latest/quickcheck/trait.Arbitrary.html) trait from the [`quickcheck`](https://docs.rs/quickcheck/latest/quickcheck/) crate. **Note: currently, this feature cannot be used with `no_std`.**
 
 ### Zeroize
 
@@ -137,6 +137,10 @@ Activating the `nightly` feature will enable the `from_be_bytes`, `from_le_bytes
 
 This crate is tested with the [`quickcheck`](https://docs.rs/quickcheck/latest/quickcheck/) crate as well as with specific edge cases. The outputs of methods are compared to the outputs of the equivalent methods of primitive integers to ensure that the behaviour is identical.
 
+## Minimum Supported Rust Version
+
+The current Minimum Supported Rust Version (MSRV) is `1.65.0`. <!-- TODO: check that this is inline with msrv specified in Cargo.toml-->
+
 ## Documentation
 
 If a method is not documented explicitly, it will have a link to the equivalent method defined on primitive Rust integers (since the methods have the same functionality).
@@ -145,9 +149,9 @@ If a method is not documented explicitly, it will have a link to the equivalent
 
 ## Known Issues
 
-At the moment, the [`From`](https://doc.rust-lang.org/core/convert/trait.From.html) trait is implemented for `bnum`'s integers, from all the Rust primitive integers. However, this behaviour is not quite correct. For example, if a 24-bit wide unsigned integer were created (`BUintD8<3>`), this should not implement `From<u32>`, etc. and should implement `TryFrom<u32>` instead. To ensure correct behaviour, the [`FromPrimitive`](https://docs.rs/num-traits/latest/num_traits/cast/trait.FromPrimitive.html) trait from the [`num_traits`](https://docs.rs/num-traits/latest/num_traits/index.html) crate can be used instead, as this will always return an `Option` rather than the integer itself.
+At the moment, the [`From`](https://doc.rust-lang.org/core/convert/trait.From.html) trait is implemented for `bnum` integers, from all the Rust primitive integers. However, this behaviour is not quite correct. For example, if a 24-bit wide unsigned integer (`BUintD8<3>`) were created, this should not implement `From<u32>`, etc. and should implement `TryFrom<u32>` instead. To ensure correct behaviour, the [`FromPrimitive`](https://docs.rs/num-traits/latest/num_traits/cast/trait.FromPrimitive.html) trait from the [`num_traits`](https://docs.rs/num-traits/latest/num_traits/index.html) crate can be used instead, as this will always return an [`Option`](https://doc.rust-lang.org/core/option/enum.Option.html) rather than the integer itself.
 
-The [`num_traits::NumCast`](https://docs.rs/num-traits/latest/num_traits/cast/trait.NumCast.html) trait is implemented for `bnum`'s integers but will panic if its method [`from`](https://docs.rs/num-traits/latest/num_traits/cast/trait.NumCast.html#tymethod.from) is called, as it is not possible to guarantee a correct conversion, due to trait bounds enforced by [`NumCast`](https://docs.rs/num-traits/latest/num_traits/cast/trait.NumCast.html). This trait should therefore never be used on `bnum`'s integers. The implementation exists only to allow implementation of the [`num_traits::PrimInt`](https://docs.rs/num-traits/latest/num_traits/int/trait.PrimInt.html) trait for `bnum`'s integers.
+The [`num_traits::NumCast`](https://docs.rs/num-traits/latest/num_traits/cast/trait.NumCast.html) trait is implemented for `bnum` integers but will intentionally panic if its method [`from`](https://docs.rs/num-traits/latest/num_traits/cast/trait.NumCast.html#tymethod.from) is called, as it is not possible to guarantee a correct conversion, due to trait bounds enforced by [`NumCast`](https://docs.rs/num-traits/latest/num_traits/cast/trait.NumCast.html). This trait should therefore never be used on `bnum` integers. The implementation exists only to allow implementation of the [`num_traits::PrimInt`](https://docs.rs/num-traits/latest/num_traits/int/trait.PrimInt.html) trait.
 
 ## Prior bugs
 
@@ -159,7 +163,7 @@ This library aims to provide arbitrary, fixed precision equivalents of Rust's 3
 
 Currently, arbitrary precision fixed size floats are being worked on but are incomplete. Most of the basic methods, such as arithmetic and classification, have been implemented, but at the moment there is no implementation of the transcendental floating point methods such as `sin`, `exp`, `log`, etc.
 
-Additionally, a proc macro for parsing numeric values will be developed at some point, which will allow easier creation of large constant values for `bnum`'s numeric types.
+Additionally, a proc macro for parsing numeric values will be developed at some point.
 
 ## Licensing
 

codecov.yml

@@ -0,0 +1,8 @@
+coverage:
+  status:
+    project:
+      default:
+        threshold: 1% # needed because due to property based testing, coverage isn't exactly the same each time
+    patch:
+      default:
+        threshold: 1% # needed because due to property based testing, coverage isn't exactly the same each time