diff --git a/src/bigint.rs b/src/bigint.rs index dd378349..97faa834 100644 --- a/src/bigint.rs +++ b/src/bigint.rs @@ -36,7 +36,7 @@ mod arbitrary; #[cfg(feature = "serde")] mod serde; -/// A Sign is a `BigInt`'s composing element. +/// A `Sign` is a [`BigInt`]'s composing element. #[derive(PartialEq, PartialOrd, Eq, Ord, Copy, Clone, Debug, Hash)] pub enum Sign { Minus, @@ -47,7 +47,7 @@ pub enum Sign { impl Neg for Sign { type Output = Sign; - /// Negate Sign value. + /// Negate `Sign` value. #[inline] fn neg(self) -> Sign { match self { @@ -292,7 +292,7 @@ trait UnsignedAbs { type Unsigned; /// A convenience method for getting the absolute value of a signed primitive as unsigned - /// See also `unsigned_abs`: https://github.com/rust-lang/rust/issues/74913 + /// See also `unsigned_abs`: fn uabs(self) -> Self::Unsigned; fn checked_uabs(self) -> CheckedUnsignedAbs; @@ -558,16 +558,16 @@ impl IntDigits for BigInt { } } -/// A generic trait for converting a value to a `BigInt`. This may return +/// A generic trait for converting a value to a [`BigInt`]. This may return /// `None` when converting from `f32` or `f64`, and will always succeed -/// when converting from any integer or unsigned primitive, or `BigUint`. +/// when converting from any integer or unsigned primitive, or [`BigUint`]. pub trait ToBigInt { - /// Converts the value of `self` to a `BigInt`. + /// Converts the value of `self` to a [`BigInt`]. fn to_bigint(&self) -> Option; } impl BigInt { - /// Creates and initializes a BigInt. + /// Creates and initializes a [`BigInt`]. /// /// The base 232 digits are ordered least significant digit first. #[inline] @@ -575,7 +575,7 @@ impl BigInt { BigInt::from_biguint(sign, BigUint::new(digits)) } - /// Creates and initializes a `BigInt`. + /// Creates and initializes a [`BigInt`]. /// /// The base 232 digits are ordered least significant digit first. #[inline] @@ -589,7 +589,7 @@ impl BigInt { BigInt { sign, data } } - /// Creates and initializes a `BigInt`. + /// Creates and initializes a [`BigInt`]. /// /// The base 232 digits are ordered least significant digit first. #[inline] @@ -597,7 +597,7 @@ impl BigInt { BigInt::from_biguint(sign, BigUint::from_slice(slice)) } - /// Reinitializes a `BigInt`. + /// Reinitializes a [`BigInt`]. /// /// The base 232 digits are ordered least significant digit first. #[inline] @@ -610,7 +610,7 @@ impl BigInt { } } - /// Creates and initializes a `BigInt`. + /// Creates and initializes a [`BigInt`]. /// /// The bytes are in big-endian byte order. /// @@ -633,7 +633,7 @@ impl BigInt { BigInt::from_biguint(sign, BigUint::from_bytes_be(bytes)) } - /// Creates and initializes a `BigInt`. + /// Creates and initializes a [`BigInt`]. /// /// The bytes are in little-endian byte order. #[inline] @@ -641,7 +641,7 @@ impl BigInt { BigInt::from_biguint(sign, BigUint::from_bytes_le(bytes)) } - /// Creates and initializes a `BigInt` from an array of bytes in + /// Creates and initializes a [`BigInt`] from an array of bytes in /// two's complement binary representation. /// /// The digits are in big-endian base 28. @@ -650,7 +650,7 @@ impl BigInt { convert::from_signed_bytes_be(digits) } - /// Creates and initializes a `BigInt` from an array of bytes in two's complement. + /// Creates and initializes a [`BigInt`] from an array of bytes in two's complement. /// /// The digits are in little-endian base 28. #[inline] @@ -658,7 +658,7 @@ impl BigInt { convert::from_signed_bytes_le(digits) } - /// Creates and initializes a `BigInt`. + /// Creates and initializes a [`BigInt`]. /// /// # Examples /// @@ -675,7 +675,7 @@ impl BigInt { BigInt::from_str_radix(s, radix).ok() } - /// Creates and initializes a `BigInt`. Each u8 of the input slice is + /// Creates and initializes a [`BigInt`]. Each `u8` of the input slice is /// interpreted as one digit of the number /// and must therefore be less than `radix`. /// @@ -696,7 +696,7 @@ impl BigInt { Some(BigInt::from_biguint(sign, u)) } - /// Creates and initializes a `BigInt`. Each u8 of the input slice is + /// Creates and initializes a [`BigInt`]. Each `u8` of the input slice is /// interpreted as one digit of the number /// and must therefore be less than `radix`. /// @@ -717,7 +717,7 @@ impl BigInt { Some(BigInt::from_biguint(sign, u)) } - /// Returns the sign and the byte representation of the `BigInt` in big-endian byte order. + /// Returns the sign and the byte representation of the [`BigInt`] in big-endian byte order. /// /// # Examples /// @@ -732,7 +732,7 @@ impl BigInt { (self.sign, self.data.to_bytes_be()) } - /// Returns the sign and the byte representation of the `BigInt` in little-endian byte order. + /// Returns the sign and the byte representation of the [`BigInt`] in little-endian byte order. /// /// # Examples /// @@ -747,7 +747,7 @@ impl BigInt { (self.sign, self.data.to_bytes_le()) } - /// Returns the sign and the `u32` digits representation of the `BigInt` ordered least + /// Returns the sign and the `u32` digits representation of the [`BigInt`] ordered least /// significant digit first. /// /// # Examples @@ -766,7 +766,7 @@ impl BigInt { (self.sign, self.data.to_u32_digits()) } - /// Returns the sign and the `u64` digits representation of the `BigInt` ordered least + /// Returns the sign and the `u64` digits representation of the [`BigInt`] ordered least /// significant digit first. /// /// # Examples @@ -786,7 +786,7 @@ impl BigInt { (self.sign, self.data.to_u64_digits()) } - /// Returns an iterator of `u32` digits representation of the `BigInt` ordered least + /// Returns an iterator of `u32` digits representation of the [`BigInt`] ordered least /// significant digit first. /// /// # Examples @@ -805,7 +805,7 @@ impl BigInt { self.data.iter_u32_digits() } - /// Returns an iterator of `u64` digits representation of the `BigInt` ordered least + /// Returns an iterator of `u64` digits representation of the [`BigInt`] ordered least /// significant digit first. /// /// # Examples @@ -825,7 +825,7 @@ impl BigInt { self.data.iter_u64_digits() } - /// Returns the two's-complement byte representation of the `BigInt` in big-endian byte order. + /// Returns the two's-complement byte representation of the [`BigInt`] in big-endian byte order. /// /// # Examples /// @@ -840,7 +840,7 @@ impl BigInt { convert::to_signed_bytes_be(self) } - /// Returns the two's-complement byte representation of the `BigInt` in little-endian byte order. + /// Returns the two's-complement byte representation of the [`BigInt`] in little-endian byte order. /// /// # Examples /// @@ -880,7 +880,7 @@ impl BigInt { /// Returns the integer in the requested base in big-endian digit order. /// The output is not given in a human readable alphabet but as a zero - /// based u8 number. + /// based `u8` number. /// `radix` must be in the range `2...256`. /// /// # Examples @@ -899,7 +899,7 @@ impl BigInt { /// Returns the integer in the requested base in little-endian digit order. /// The output is not given in a human readable alphabet but as a zero - /// based u8 number. + /// based `u8` number. /// `radix` must be in the range `2...256`. /// /// # Examples @@ -916,7 +916,7 @@ impl BigInt { (self.sign, self.data.to_radix_le(radix)) } - /// Returns the sign of the `BigInt` as a `Sign`. + /// Returns the sign of the [`BigInt`] as a [`Sign`]. /// /// # Examples /// @@ -933,7 +933,7 @@ impl BigInt { self.sign } - /// Returns the magnitude of the `BigInt` as a `BigUint`. + /// Returns the magnitude of the [`BigInt`] as a [`BigUint`]. /// /// # Examples /// @@ -950,8 +950,8 @@ impl BigInt { &self.data } - /// Convert this `BigInt` into its `Sign` and `BigUint` magnitude, - /// the reverse of `BigInt::from_biguint`. + /// Convert this [`BigInt`] into its [`Sign`] and [`BigUint`] magnitude, + /// the reverse of [`BigInt::from_biguint()`]. /// /// # Examples /// @@ -968,14 +968,14 @@ impl BigInt { (self.sign, self.data) } - /// Determines the fewest bits necessary to express the `BigInt`, + /// Determines the fewest bits necessary to express the [`BigInt`], /// not including the sign. #[inline] pub fn bits(&self) -> u64 { self.data.bits() } - /// Converts this `BigInt` into a `BigUint`, if it's not negative. + /// Converts this [`BigInt`] into a [`BigUint`], if it's not negative. #[inline] pub fn to_biguint(&self) -> Option { match self.sign { @@ -1026,19 +1026,19 @@ impl BigInt { } /// Returns the truncated principal square root of `self` -- - /// see [Roots::sqrt](https://docs.rs/num-integer/0.1/num_integer/trait.Roots.html#method.sqrt). + /// see [`num_integer::Roots::sqrt()`]. pub fn sqrt(&self) -> Self { Roots::sqrt(self) } /// Returns the truncated principal cube root of `self` -- - /// see [Roots::cbrt](https://docs.rs/num-integer/0.1/num_integer/trait.Roots.html#method.cbrt). + /// see [`num_integer::Roots::cbrt()`]. pub fn cbrt(&self) -> Self { Roots::cbrt(self) } /// Returns the truncated principal `n`th root of `self` -- - /// See [Roots::nth_root](https://docs.rs/num-integer/0.1/num_integer/trait.Roots.html#tymethod.nth_root). + /// See [`num_integer::Roots::nth_root()`]. pub fn nth_root(&self, n: u32) -> Self { Roots::nth_root(self, n) } diff --git a/src/bigint/convert.rs b/src/bigint/convert.rs index f3622035..f6c8163f 100644 --- a/src/bigint/convert.rs +++ b/src/bigint/convert.rs @@ -24,7 +24,7 @@ impl FromStr for BigInt { impl Num for BigInt { type FromStrRadixErr = ParseBigIntError; - /// Creates and initializes a BigInt. + /// Creates and initializes a [`BigInt`]. #[inline] fn from_str_radix(mut s: &str, radix: u32) -> Result { let sign = if s.starts_with('-') { diff --git a/src/bigrand.rs b/src/bigrand.rs index 8f0ce5b3..ec032241 100644 --- a/src/bigrand.rs +++ b/src/bigrand.rs @@ -16,22 +16,22 @@ use num_traits::{ToPrimitive, Zero}; /// /// The `rand` feature must be enabled to use this. See crate-level documentation for details. pub trait RandBigInt { - /// Generate a random `BigUint` of the given bit size. + /// Generate a random [`BigUint`] of the given bit size. fn gen_biguint(&mut self, bit_size: u64) -> BigUint; - /// Generate a random BigInt of the given bit size. + /// Generate a random [ BigInt`] of the given bit size. fn gen_bigint(&mut self, bit_size: u64) -> BigInt; - /// Generate a random `BigUint` less than the given bound. Fails + /// Generate a random [`BigUint`] less than the given bound. Fails /// when the bound is zero. fn gen_biguint_below(&mut self, bound: &BigUint) -> BigUint; - /// Generate a random `BigUint` within the given range. The lower + /// Generate a random [`BigUint`] within the given range. The lower /// bound is inclusive; the upper bound is exclusive. Fails when /// the upper bound is not greater than the lower bound. fn gen_biguint_range(&mut self, lbound: &BigUint, ubound: &BigUint) -> BigUint; - /// Generate a random `BigInt` within the given range. The lower + /// Generate a random [`BigInt`] within the given range. The lower /// bound is inclusive; the upper bound is exclusive. Fails when /// the upper bound is not greater than the lower bound. fn gen_bigint_range(&mut self, lbound: &BigInt, ubound: &BigInt) -> BigInt; @@ -141,7 +141,7 @@ impl RandBigInt for R { } } -/// The back-end implementing rand's `UniformSampler` for `BigUint`. +/// The back-end implementing rand's [`UniformSampler`] for [`BigUint`]. #[derive(Clone, Debug)] pub struct UniformBigUint { base: BigUint, @@ -197,7 +197,7 @@ impl SampleUniform for BigUint { type Sampler = UniformBigUint; } -/// The back-end implementing rand's `UniformSampler` for `BigInt`. +/// The back-end implementing rand's [`UniformSampler`] for [`BigInt`]. #[derive(Clone, Debug)] pub struct UniformBigInt { base: BigInt, @@ -253,7 +253,7 @@ impl SampleUniform for BigInt { type Sampler = UniformBigInt; } -/// A random distribution for `BigUint` and `BigInt` values of a particular bit size. +/// A random distribution for [`BigUint`] and [`BigInt`] values of a particular bit size. /// /// The `rand` feature must be enabled to use this. See crate-level documentation for details. #[derive(Clone, Copy, Debug)] diff --git a/src/biguint.rs b/src/biguint.rs index d1f60ce9..613e944b 100644 --- a/src/biguint.rs +++ b/src/biguint.rs @@ -504,13 +504,13 @@ impl Roots for BigUint { } } -/// A generic trait for converting a value to a `BigUint`. +/// A generic trait for converting a value to a [`BigUint`]. pub trait ToBigUint { - /// Converts the value of `self` to a `BigUint`. + /// Converts the value of `self` to a [`BigUint`]. fn to_biguint(&self) -> Option; } -/// Creates and initializes a `BigUint`. +/// Creates and initializes a [`BigUint`]. /// /// The digits are in little-endian base matching `BigDigit`. #[inline] @@ -519,7 +519,7 @@ pub(crate) fn biguint_from_vec(digits: Vec) -> BigUint { } impl BigUint { - /// Creates and initializes a `BigUint`. + /// Creates and initializes a [`BigUint`]. /// /// The base 232 digits are ordered least significant digit first. #[inline] @@ -538,7 +538,7 @@ impl BigUint { big } - /// Creates and initializes a `BigUint`. + /// Creates and initializes a [`BigUint`]. /// /// The base 232 digits are ordered least significant digit first. #[inline] @@ -548,7 +548,7 @@ impl BigUint { big } - /// Assign a value to a `BigUint`. + /// Assign a value to a [`BigUint`]. /// /// The base 232 digits are ordered least significant digit first. #[inline] @@ -564,7 +564,7 @@ impl BigUint { self.normalize(); } - /// Creates and initializes a `BigUint`. + /// Creates and initializes a [`BigUint`]. /// /// The bytes are in big-endian byte order. /// @@ -593,7 +593,7 @@ impl BigUint { } } - /// Creates and initializes a `BigUint`. + /// Creates and initializes a [`BigUint`]. /// /// The bytes are in little-endian byte order. #[inline] @@ -605,7 +605,7 @@ impl BigUint { } } - /// Creates and initializes a `BigUint`. The input slice must contain + /// Creates and initializes a [`BigUint`]. The input slice must contain /// ascii/utf8 characters in [0-9a-zA-Z]. /// `radix` must be in the range `2...36`. /// @@ -627,7 +627,7 @@ impl BigUint { BigUint::from_str_radix(s, radix).ok() } - /// Creates and initializes a `BigUint`. Each u8 of the input slice is + /// Creates and initializes a [`BigUint`]. Each `u8` of the input slice is /// interpreted as one digit of the number /// and must therefore be less than `radix`. /// @@ -647,7 +647,7 @@ impl BigUint { convert::from_radix_be(buf, radix) } - /// Creates and initializes a `BigUint`. Each u8 of the input slice is + /// Creates and initializes a [`BigUint`]. Each `u8` of the input slice is /// interpreted as one digit of the number /// and must therefore be less than `radix`. /// @@ -667,7 +667,7 @@ impl BigUint { convert::from_radix_le(buf, radix) } - /// Returns the byte representation of the `BigUint` in big-endian byte order. + /// Returns the byte representation of the [`BigUint`] in big-endian byte order. /// /// # Examples /// @@ -684,7 +684,7 @@ impl BigUint { v } - /// Returns the byte representation of the `BigUint` in little-endian byte order. + /// Returns the byte representation of the [`BigUint`] in little-endian byte order. /// /// # Examples /// @@ -703,7 +703,7 @@ impl BigUint { } } - /// Returns the `u32` digits representation of the `BigUint` ordered least significant digit + /// Returns the `u32` digits representation of the [`BigUint`] ordered least significant digit /// first. /// /// # Examples @@ -721,7 +721,7 @@ impl BigUint { self.iter_u32_digits().collect() } - /// Returns the `u64` digits representation of the `BigUint` ordered least significant digit + /// Returns the `u64` digits representation of the [`BigUint`] ordered least significant digit /// first. /// /// # Examples @@ -740,7 +740,7 @@ impl BigUint { self.iter_u64_digits().collect() } - /// Returns an iterator of `u32` digits representation of the `BigUint` ordered least + /// Returns an iterator of `u32` digits representation of the [`BigUint`] ordered least /// significant digit first. /// /// # Examples @@ -758,7 +758,7 @@ impl BigUint { U32Digits::new(self.data.as_slice()) } - /// Returns an iterator of `u64` digits representation of the `BigUint` ordered least + /// Returns an iterator of `u64` digits representation of the [`BigUint`] ordered least /// significant digit first. /// /// # Examples @@ -797,7 +797,7 @@ impl BigUint { /// Returns the integer in the requested base in big-endian digit order. /// The output is not given in a human readable alphabet but as a zero - /// based u8 number. + /// based `u8` number. /// `radix` must be in the range `2...256`. /// /// # Examples @@ -835,7 +835,7 @@ impl BigUint { convert::to_radix_le(self, radix) } - /// Determines the fewest bits necessary to express the `BigUint`. + /// Determines the fewest bits necessary to express the [`BigUint`]. #[inline] pub fn bits(&self) -> u64 { if self.is_zero() { @@ -858,7 +858,7 @@ impl BigUint { } } - /// Returns a normalized `BigUint`. + /// Returns a normalized [`BigUint`]. #[inline] fn normalized(mut self) -> BigUint { self.normalize(); @@ -1014,7 +1014,7 @@ impl IntDigits for BigUint { } } -/// Convert a u32 chunk (len is either 1 or 2) to a single u64 digit +/// Convert a `u32` chunk (len is either 1 or 2) to a single `u64` digit #[inline] fn u32_chunk_to_u64(chunk: &[u32]) -> u64 { // raw could have odd length diff --git a/src/biguint/monty.rs b/src/biguint/monty.rs index a5c79aa9..edb38cc8 100644 --- a/src/biguint/monty.rs +++ b/src/biguint/monty.rs @@ -37,7 +37,7 @@ impl MontyReducer { /// Computes z mod m = x * y * 2 ** (-n*_W) mod m /// assuming k = -1/m mod 2**_W /// See Gueron, "Efficient Software Implementations of Modular Exponentiation". -/// https://eprint.iacr.org/2011/239.pdf +/// /// In the terminology of that paper, this is an "Almost Montgomery Multiplication": /// x and y are required to satisfy 0 <= z < 2**(n*_W) and then the result /// z is guaranteed to satisfy 0 <= z < 2**(n*_W), but it may not be < m. diff --git a/src/lib.rs b/src/lib.rs index c741f68f..739b92ae 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -8,10 +8,10 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! A Big integer (signed version: `BigInt`, unsigned version: `BigUint`). +//! Big Integer Types for Rust //! -//! A `BigUint` is represented as a vector of `BigDigit`s. -//! A `BigInt` is a combination of `BigUint` and `Sign`. +//! * A [`BigUint`] is unsigned and represented as a vector of digits. +//! * A [`BigInt`] is signed and is a combination of [`BigUint`] and [`Sign`]. //! //! Common numerical operations are overloaded, so we can treat them //! the same way we treat other numbers. @@ -201,9 +201,6 @@ impl TryFromBigIntError { /// Extract the original value, if available. The value will be available /// if the type before conversion was either [`BigInt`] or [`BigUint`]. - /// - /// [`BigInt`]: struct.BigInt.html - /// [`BigUint`]: struct.BigUint.html pub fn into_original(self) -> T { self.original } @@ -239,26 +236,26 @@ pub use crate::bigint::ToBigInt; pub use crate::bigrand::{RandBigInt, RandomBits, UniformBigInt, UniformBigUint}; mod big_digit { - /// A `BigDigit` is a `BigUint`'s composing element. + /// A [`BigDigit`] is a [`BigUint`]'s composing element. #[cfg(not(u64_digit))] pub(crate) type BigDigit = u32; #[cfg(u64_digit)] pub(crate) type BigDigit = u64; - /// A `DoubleBigDigit` is the internal type used to do the computations. Its - /// size is the double of the size of `BigDigit`. + /// A [`DoubleBigDigit`] is the internal type used to do the computations. Its + /// size is the double of the size of [`BigDigit`]. #[cfg(not(u64_digit))] pub(crate) type DoubleBigDigit = u64; #[cfg(u64_digit)] pub(crate) type DoubleBigDigit = u128; - /// A `SignedDoubleBigDigit` is the signed version of `DoubleBigDigit`. + /// A [`SignedDoubleBigDigit`] is the signed version of [`DoubleBigDigit`]. #[cfg(not(u64_digit))] pub(crate) type SignedDoubleBigDigit = i64; #[cfg(u64_digit)] pub(crate) type SignedDoubleBigDigit = i128; - // `DoubleBigDigit` size dependent + // [`DoubleBigDigit`] size dependent #[cfg(not(u64_digit))] pub(crate) const BITS: u8 = 32; #[cfg(u64_digit)] @@ -279,13 +276,13 @@ mod big_digit { (n & LO_MASK) as BigDigit } - /// Split one `DoubleBigDigit` into two `BigDigit`s. + /// Split one [`DoubleBigDigit`] into two [`BigDigit`]s. #[inline] pub(crate) fn from_doublebigdigit(n: DoubleBigDigit) -> (BigDigit, BigDigit) { (get_hi(n), get_lo(n)) } - /// Join two `BigDigit`s into one `DoubleBigDigit` + /// Join two [`BigDigit`]s into one [`DoubleBigDigit`]. #[inline] pub(crate) fn to_doublebigdigit(hi: BigDigit, lo: BigDigit) -> DoubleBigDigit { DoubleBigDigit::from(lo) | (DoubleBigDigit::from(hi) << BITS)