Skip to content

Commit

Permalink
Merge #277
Browse files Browse the repository at this point in the history 
277: Improve doc linking and minor formatting. r=cuviper a=waywardmonkeys



Co-authored-by: Bruce Mitchener <bruce.mitchener@gmail.com>
  • Loading branch information
@bors @waywardmonkeys
bors[bot] and waywardmonkeys committed Aug 22, 2023
2 parents 9dbf8d6 + 078972d commit 9134523
Show file tree
Hide file tree
Showing 6 changed files with 77 additions and 80 deletions.
72 changes: 36 additions & 36 deletions src/bigint.rs
View file
Expand Up @@ -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,
Expand All @@ -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 {
Expand Down Expand Up @@ -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`: <https://github.com/rust-lang/rust/issues/74913>
fn uabs(self) -> Self::Unsigned;

fn checked_uabs(self) -> CheckedUnsignedAbs<Self::Unsigned>;
Expand Down Expand Up @@ -558,24 +558,24 @@ 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<BigInt>;
}

impl BigInt {
/// Creates and initializes a BigInt.
/// Creates and initializes a [`BigInt`].
///
/// The base 2<sup>32</sup> digits are ordered least significant digit first.
#[inline]
pub fn new(sign: Sign, digits: Vec<u32>) -> BigInt {
BigInt::from_biguint(sign, BigUint::new(digits))
}

/// Creates and initializes a `BigInt`.
/// Creates and initializes a [`BigInt`].
///
/// The base 2<sup>32</sup> digits are ordered least significant digit first.
#[inline]
Expand All @@ -589,15 +589,15 @@ impl BigInt {
BigInt { sign, data }
}

/// Creates and initializes a `BigInt`.
/// Creates and initializes a [`BigInt`].
///
/// The base 2<sup>32</sup> digits are ordered least significant digit first.
#[inline]
pub fn from_slice(sign: Sign, slice: &[u32]) -> BigInt {
BigInt::from_biguint(sign, BigUint::from_slice(slice))
}

/// Reinitializes a `BigInt`.
/// Reinitializes a [`BigInt`].
///
/// The base 2<sup>32</sup> digits are ordered least significant digit first.
#[inline]
Expand All @@ -610,7 +610,7 @@ impl BigInt {
}
}

/// Creates and initializes a `BigInt`.
/// Creates and initializes a [`BigInt`].
///
/// The bytes are in big-endian byte order.
///
Expand All @@ -633,15 +633,15 @@ 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]
pub fn from_bytes_le(sign: Sign, bytes: &[u8]) -> 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 2<sup>8</sup>.
Expand All @@ -650,15 +650,15 @@ 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 2<sup>8</sup>.
#[inline]
pub fn from_signed_bytes_le(digits: &[u8]) -> BigInt {
convert::from_signed_bytes_le(digits)
}

/// Creates and initializes a `BigInt`.
/// Creates and initializes a [`BigInt`].
///
/// # Examples
///
Expand All @@ -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`.
///
Expand All @@ -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`.
///
Expand All @@ -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
///
Expand All @@ -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
///
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
///
Expand All @@ -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
///
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
///
Expand All @@ -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
///
Expand All @@ -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
///
Expand All @@ -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<BigUint> {
match self.sign {
Expand Down Expand Up @@ -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)
}
Expand Down
2 changes: 1 addition & 1 deletion src/bigint/convert.rs
View file
Expand Up @@ -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<BigInt, ParseBigIntError> {
let sign = if s.starts_with('-') {
Expand Down
16 changes: 8 additions & 8 deletions src/bigrand.rs
View file
Expand Up @@ -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;
Expand Down Expand Up @@ -141,7 +141,7 @@ impl<R: Rng + ?Sized> 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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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)]
Expand Down

0 comments on commit 9134523

Please sign in to comment.