NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io
crates.io, #2260 most downloaded on crates.io
Fixed-size integer types with generic signedness, bit width and overflow behaviour.
Latest stable
0.14.4
Last release 8 months ago
24 Mar 2026
Release timing varies
gaps range from 8 days to 12 months
Nearly every release is documented
notes for 20 of 21 stable releases
Nothing withdrawn
no release was ever pulled
4 years old
21 releases · first in 2022
Drag across the ruler to compare, or tap a release to open it.
Fixes #72, also fixes a bug in the quickcheck::Arbitrary and rand::Distribution and rand::Fill traits where the padding bits of integers with non-mult
Fixes #72, also fixes a bug in the quickcheck::Arbitrary and rand::Distribution and rand::Fill traits where the padding bits of integers with non-multiple-of-8 bit widths were not set properly.
Patch release: update the Cargo.toml description and fix display of code examples in the README.
Patch release: update the Cargo.toml description and fix display of code examples in the README.
This implements the fix #68 which caused the crate tests to not compile when the "alloc" feature was disabled.
This implements the fix #68 which caused the crate tests to not compile when the "alloc" feature was disabled.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
fix: borsh feature compile error by @larry0x in https://github.com/isaacholt100/bnum/pull/66
This version fixes #65.
Auto-generated release notes:
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.14.0...v0.14.1
This release is by far the most significant upgrade of the crate so far, with a greatly simplified API, performance improvements, increased customisab
This release is by far the most significant upgrade of the crate so far, with a greatly simplified API, performance improvements, increased customisability, and new functionality.
The biggest change is that instead of there being 4 unsigned integer types (BUint, BUintD32, BUintD16, BUintD8) and 4 signed integer types ( BInt, BIntD32, BIntD16, BIntD8), there is now a single type Integer, which has a const-generic parameter S of type bool, which controls whether the type behaves as an unsigned or signed integer.
In previous versions of the crate, there was a separate integer type for each of the 4 allowed underlying digit types: u8, u16, u32, and u64. The reason for this was that narrower digit types allowed for more fine-grained bit widths, while wider digit types meant faster performance. Thus, there was a trade-off between bit width customisability, and speed.
Integer avoids this trade-off entirely by being stored as an array of u8 digits, but iterating over wider digits (by "chunking" together u8 digits) during computations. The performance of a given method on Integer has been benchmarked with each possible choice of chunked digit (u8, u16, u32, u64, u128), and the digit giving the fastest implementation was chosen.
The types Uint and Int are aliases Integer, with the const-generic parameter S specified to be false and true respectively.
Integer has another const-generic parameter B of type usize to specify the bit width of the integer as any integer between 2 and 2^32 - 1; in previous versions, the bit width of the integer was inferred from the byte width, so had to be a multiple of 8.
The final const-generic parameter Integer controls its behaviour when arithmetic overflow occurs. There are 3 possible behaviours: wrap around, panic, or saturate. By default, the behaviour is wrapping if the overflow-checks flag is disabled, and is panicking if overflow-checks is enabled.
The full set of generic parameters of Integer<S, N, B, OM> are the signedness S, the byte width N, the bit width B, and the overflow mode OM. For example:
type A = Integer<true, 3, 23, 0>; // signed 23-bit integer with wrapping overflow behaviour
type B = Integer<false, 20, 155, 2>; // unsigned 155-bit integer with saturating overflow behaviour
In previous versions, in order to construct integers from a specified list of digits, the from_str_radix had to be used, e.g.
let a = U256::from_str_radix("abcdef", 16).unwrap()
There was no way of constructing integers from Rust integer literals at compile time. In this release, the n! macro is introduced, which takes an integer literal, and returns an integer whose value corresponds to the literal, e.g.
let a = n!(0xabcdef_U256);
Similarly to how integer literals are handled for the primitive integer types, if literal is specified without a suffix, then type inference is performed, e.g.
let b: I512 = n!(1234);
is valid. As in the case of primitive integers, if an invalid literal is encountered, then a compile error is triggered, e.g.
let a = n!(1a23_U24)
would cause a compile error. The one difference is that let c = 0 assigns a type of i32 to c by default, whereas let c = n!(0) would result in a compile error (unless c was subsequently used in a way that type inference for c could be performed by the compiler).
bnum now also supports construction of specific integer types via the t! macro. The t! macro takes a "type descriptor" which is an identifier encoding the specific values of the const-generic parameters of Integer. For example, if you wanted a 155-bit signed integer which has wrapping behaviour on overflow, you would write t!(I155w), which outputs Integer<true, 20, 155, 0>.
let a: t!(I155w) = n!(1234);
fn add_one(int: t!(I155w)) -> t!(I155w) {
int + n!(1)
}
let b = add_one(a);
The n! and t! macros are both declarative, not procedural, so add minimal compile-time overhead and do not introduce any dependencies to bnum (which is still zero-dependency by default).
Add<Digit>, Div<Digit> and Rem<Digit> impls for unsigned integers (use the Add<Self>, Div<Self> and Rem<Self> impls instead).parse_str_radix method (use from_str_radix(...).unwrap(), or the n! macro if appropriate).rand dependency is now version 0.10 of that crate.Slice struct and try_fill_slice function from the crate's random module (these are superseded by the implementation of the Fill trait from rand 0.10).parse_bytes method (use from_ascii_radix instead).as_bits, as_bits_mut from signed integers (either use as_bytes or as_bytes_mut instead, methods like set_bit are now defined for signed integers as well as unsigned).ZERO, TWO, NEG_ONE) from integers, as these values can now be easily constructed with the n! macro.{to,from}_{be,le} methods from integers, as not portable (and it didn't make sense to have them anyway as bnum integers are always stored in little-endian byte order).from_digit method from unsigned integers (use the As trait instead).{from,to}_radix_{be,le} from signed integers (only makes sense to have this for unsigned integers).CastFrom trait from the prelude.bits method from signed integers and rename the bits method on unsigned integers to bit_width, which now takes self instead of &self.BTryFrom trait (use the TryFrom<&Integer> for Integer, TryFrom<Int> for Uint or TryFrom<Uint> for Int impls instead).From<primitive_int> impls to TryFrom<primitive_int> (use the As trait instead for infallible conversions).From conversions between Uint and [u8; N].FromBytes, ToBytes, ConstZero, ConstOne and OverflowingMul traits from the num_traits crate.unchecked_... methods are now const.alloc crate behind an alloc feature, which allows for usage in no-alloc environments.1.87.0.from_ascii and from_ascii_radix methods.unchecked_neg method to signed integers.checked_signed_diff, overflowing_sub_signed, wrapping_sub_signed, checked_sub_signed, saturating_sub_signed methods to unsigned integers.Debug impl for integers when the alloc feature is disabled, which formats the integer as a padded hex string.[2, 2^32).TryFrom<&Integer> for Integer, TryFrom<Int> for Uint or TryFrom<Uint> for Int impls.core::error::Error trait for TryFromIntError, TryFromCharError, and ParseIntError.is_multiple_of method (previously, it incorrectly panicked if rhs was zero).mod_floor and div_floor methods of the num_integer::Integer impl for signed integers.wrapping_sh{l, r} and overflowing_sh{l,r} methods when shift exceeds the bit width of the integer.This release adds support for some more traits from the num_traits crate, implements a few new methods, fixes three methods which were incorrectly did
This release adds support for some more traits from the num_traits crate, implements a few new methods, fixes three methods which were incorrectly did not panic, and allows testing on stable.
nightly crate feature (and nightly Rust is still required to test these specific methods).OverflowingAdd and OverflowingSub traits from the num_traits crate.unbounded_shl and unbounded_shr methods to signed and unsigned integers.as_bits and as_bits_mut to signed integers.to_str_radix, to_radix_be and to_radix_le stated that these methods panicked on invalid radices, where in fact this was not the case. As of this version, they now panic correctly on invalid radices (as per the documentation).set_bit method on unsigned ints is now branchless.Auto-generated release notes:
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.12.1...v0.13.0
This release fixes a few incorrect implementations of some methods.
This release fixes a few incorrect implementations of some methods.
midpoint round to zero for signed integers.Debug implementation of ParseIntError to match that of core::num::ParseIntError.lcm method on num-integer::Integer for signed integers (now always returns non-negative values)PosOverflow error is returned instead of an InvalidDigit error when parsing integers (however there some edge cases where PosOverflow should be returned and now isn't, this will be fixed at some point).Auto-generated release notes:
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.12.0...v0.12.1
This release introduces a number of new methods, as well as support for the borsh crate.
This release introduces a number of new methods, as well as support for the borsh crate.
1.83.0) does not support user-defined const traits, and so the nightly crate feature no longer makes the CastFrom and As traits const. This means the implementations of these traits on bnum integers are no longer const either.borsh crate (this enables serialisation and deserialisation using this crate).digits_mut and set_bit methods to unsigned integers, allowing for manipulation without copying the value.cast_signed method for unsigned integers and cast_unsigned method for signed integers.midpoint method for all integers.carrying_add and borrowing_sub methods for signed integers.strict_... arithmetic methods for all integers.(bnum) prefix to panic messages that mistakenly did not include it.Auto-generated release notes:
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.11.0...v0.12.0
This release fixes #39, and makes all ilog* methods panic with the same message as Rust's primitive integers (with the (bnum) prefix, as for other bnu
This release fixes #39, and makes all ilog* methods panic with the same message as Rust's primitive integers (with the (bnum) prefix, as for other bnum panic messages).
ilog* methods now panic for invalid inputs in release mode as well as debug mode.ilog* panic messages now match that of Rust's primitives.Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.10.0...v0.11.0
This release fixes #36, which was related to a premature stabilisation of the language feature const_intrinsic_copy (see https://github.com/rust-lang/
This release fixes #36, which was related to a premature stabilisation of the language feature const_intrinsic_copy (see https://github.com/rust-lang/rust/pull/117905). Previously, several functions had relied on this feature, which meant their implementations contained Undefined Behaviour. (For a list of those affected and for further details, see changes/prior-bugs.md). Completely safe implementations have now been written for these functions.
This is marked as a major change as previous versions v0.7.0 - v0.9.1 may at some point cease to be compatible with the latest version of the Rust compiler, if stabilisation of const_intrinsic_copy is reverted.
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.9.1...v0.10.0
The only change in this version is the addition of the rust-version (MSRV) field to Cargo.toml. The MSRV is currently 1.65.0.
The only change in this version is the addition of the rust-version (MSRV) field to Cargo.toml. The MSRV is currently 1.65.0.
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.9.0...v0.9.1
bnum integers are now #[repr(transparent)], which solves #30.
bnum integers are now #[repr(transparent)], which solves #30.Slice struct is now #[repr(transparent)].wrapping_rem method now has the same panic message as wrapping_rem on primitive integers.unchecked_shl and unchecked_shr now take a u32 as the shifting argument instead of Self.unchecked_shl and unchecked_shr for bnum integers with 64-bit digits were previously incorrect; they have now been fixed.Add<$Digit> on all bnum unsigned integers was previously incorrect; it has now been fixed.lcm method on bnum integers no longer panics if self is zero; instead, it returns zero.zeroize support.quickcheck support.valuable support.PartialEq and Eq to #[derive(PartialEq, Eq)]: this fixes #32.BTryFrom for fallible conversions between bnum integers - this is a temporary solution to #31.std_rng and small_rng features of the rand crate except when testing.shr methods (checked_shr, wrapping_shr, etc.).Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.8.0...v0.9.0
This release fixes #36. For more info, see the release notes for v0.10.0.
This release fixes #36. For more info, see the release notes for v0.10.0.
There are no breaking changes in this release.
There are no breaking changes in this release.
const on stable: checked_div, checked_div_euclid, checked_rem, checked_rem_euclid, checked_next_multiple_of, checked_ilog10, checked_ilog, div, rem, overflowing_div, overflowing_div_euclid, overflowing_rem, overflowing_rem_euclid, saturating_div, wrapping_div, wrapping_div_euclid, wrapping_rem, wrapping_rem_euclid, div_euclid, rem_euclid, ilog10, ilog, next_multiple_of, div_floor, div_ceil.BUint<5> to BIntD16<7>.Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.7.0...v0.8.0
Unfortunately version 1.71.0 of the nightly Rust compiler dropped support of the const implementation of common standard library traits. Previous to t
1.71.0 of the nightly Rust compiler dropped support of the const implementation of common standard library traits. Previous to this version, bnum had const implementations of many standard library traits such as Add, BitOr, PartialEq, etc. which were available using nightly. However, now this is no longer possible with the current version of the nightly Rust compiler (as of 28th May 2023), hence the const implementations of these traits have been dropped for now to allow compatibility with the latest version on nightly. To account for this, many of the methods defined on these traits now have const implementations on the integer types themselves - so for example, there are now BUint::shr and BInt::shr methods which are const.arbitrary feature has been introduced, which derives the Arbitrary trait from the arbitrary crate. Note that normally bnum works with no_std, but it cannot with this feature enabled.const on stable: abs_diff, <uint>::{overflowing_neg, wrapping_neg}, wrapping_{shr, shl}, overflowing_{shr, shl}, checked_{shr, shl}, rotate_left, rotate_right, from_be_slice, from_le_slice.(@lrubasze contributed the addition of the arbitrary support in this release - due to a complication with the CI with his pull request, I'm mentioning him here so he is included in this list of contributors).
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.6.0...v0.7.0
There were no breaking changes in this release. The biggest update is the introduction of the const parse_str_radix method on signed and unsigned inte…
There were no breaking changes in this release. The biggest update is the introduction of the const parse_str_radix method on signed and unsigned integers, which allows compile-time parsing of string literals in a given radix. from_str_radix is now also const, which allows compile-time parsing of string literals which are not guaranteed to parse successfully.
The following methods are now const on stable:
{BUint, BInt}::parse_bytesBInt::overflowing_mulBInt::overflowing_negBInt::overflowing_absBInt::overflowing_powBInt::wrapping_negBInt::wrapping_absBInt::checked_mulBInt::checked_negBInt::checked_absBInt::checked_powBInt::saturating_mulBInt::saturating_negBInt::saturating_absBInt::saturating_powBInt::unsigned_absBInt::powBInt::absBInt::abs_diffAdditionally, the following methods are now const when the nightly feature is enabled:
{BUint, BInt}::from_radix_be{BUint, BInt}::from_radix_leFull Changelog: https://github.com/isaacholt100/bnum/compare/v0.5.0...v0.6.0
Another minor release, the only breaking change in this release is that the implementations of traits from the num_traits and num_integer traits are n…
Another minor release, the only breaking change in this release is that the implementations of traits from the num_traits and num_integer traits are no longer const, since those traits are not marked as const_trait in those crates.
Previously, traits defined in the crate were not marked as const_trait which meant that they couldn't be used in the latest version of Rust nightly (currently 1.68.0). Now this issue has been fixed and the latest version of nightly can be used.
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.4.0...v0.5.0
No changes to functionality were made in this release, the only changes were editing the metadata of the project's optional dependencies so that they
No changes to functionality were made in this release, the only changes were editing the metadata of the project's optional dependencies so that they had default-features = false in Cargo.toml, which allows for bnum to be used in no_std environments while still enabling these optional dependencies.
NB: docs.rs failed to build the documentation for this release, due to a compile error (since this version didn't work with the current latest version of nightly, 1.68.0 at the time of writing).
NB: this release and earlier releases don't work with the current latest version of nightly, 1.68.0 (and, most likely, future versions) because it contains const implementations of crates which are not marked as const_trait. Upgrade to the latest version (currently v0.5.0) to be able to use the latest version of nightly.
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.3.0...v0.4.0
This release does not include many changes. The only breaking change is the renaming of the log... and checked_log... methods to ilog... and checked_i…
This release does not include many changes. The only breaking change is the renaming of the log... and checked_log... methods to ilog... and checked_ilog... to match the Rust integer API. A warning was added to the README about the incorrectness of the from_be and to_be methods in v0.1.0.
Full Changelog: https://github.com/isaacholt100/bnum/compare/v0.2.0...v0.3.0
v0.2.0 introduces some differences to the API of v0.1.0. In v0.1.0, the only integer types were BUint and BInt, which by default were stored as an arr
v0.2.0 introduces some differences to the API of v0.1.0. In v0.1.0, the only integer types were BUint and BInt, which by default were stored as an array of u64 digits. The u8_digit feature allowed them to be stored as an array of u8 digits instead. However, as mentioned in #7, this feature was non-additive, which could have been an issue for multiple dependencies using this library further down the line. It also meant that all integers had to either store u64 or u8 digits - there couldn't be different integer types using different digit sizes.
v0.2.0 solves this issue by defining integer types that are stored as an array of either u64, u32, u16, or u8 digits. BUint and BInt are still stored as an array of u64 digits, but there is no u8_digit feature anymore. Additionally, BUintD32 is stored as an array of u32 digits, BUintD16 as an array of u16 digits, and BUintD8 as an array of u8 digits. The signed integer types BIntD32, BIntD16 and BIntD8 are defined similarly. This allows finer control of integer bit sizes while ensuring speed is not sacrificed. For information on how to choose one of these four integer types, see https://crates.io/crates/bnum/0.2.0.
Full Changelog: https://github.com/isaacholt100/bnum/commits/v0.2.0
Nothing published for this version
One column per quarter.