ibig 0.3.6

A big integer library with good performance
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

//! A ring of integers modulo a positive integer.

use crate::{
    arch::word::Word,
    assert::debug_assert_in_const_fn,
    cmp, div,
    fast_divide::FastDivideNormalized,
    math,
    ubig::{Repr, UBig},
};
use alloc::vec::Vec;
use core::cmp::Ordering;

/// A ring of integers modulo a positive integer.
///
/// # Examples
///
/// ```
/// # use ibig::{modular::ModuloRing, ubig};
/// let ring = ModuloRing::new(&ubig!(100));
/// assert_eq!(ring.modulus(), ubig!(100));
/// ```
pub struct ModuloRing(ModuloRingRepr);

pub(crate) enum ModuloRingRepr {
    Small(ModuloRingSmall),
    Large(ModuloRingLarge),
}

pub(crate) struct ModuloRingSmall {
    normalized_modulus: Word,
    shift: u32,
    fast_div: FastDivideNormalized,
}

pub(crate) struct ModuloRingLarge {
    normalized_modulus: Vec<Word>,
    shift: u32,
    fast_div_top: FastDivideNormalized,
}

impl ModuloRing {
    /// Create a new ring of integers modulo `n`.
    ///
    /// For two [Modulo](crate::modular::Modulo) numbers to be compatible,
    /// they must come from the same [ModuloRing].
    /// Two different [ModuloRing]s are not compatible even if
    /// they have the same modulus `n`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use ibig::{modular::ModuloRing, ubig};
    /// let ring = ModuloRing::new(&ubig!(100));
    /// assert_eq!(ring.modulus(), ubig!(100));
    /// ```
    ///
    /// # Panics
    ///
    /// Panics if `n` is zero.
    #[inline]
    pub fn new(n: &UBig) -> ModuloRing {
        match n.repr() {
            Repr::Small(0) => panic!("ModuloRing::new(0)"),
            Repr::Small(word) => ModuloRing(ModuloRingRepr::Small(ModuloRingSmall::new(*word))),
            Repr::Large(words) => ModuloRing(ModuloRingRepr::Large(ModuloRingLarge::new(words))),
        }
    }

    #[inline]
    pub(crate) fn repr(&self) -> &ModuloRingRepr {
        &self.0
    }
}

impl ModuloRingSmall {
    /// Create a new small ring of integers modulo `n`.
    #[inline]
    pub(crate) const fn new(n: Word) -> ModuloRingSmall {
        debug_assert_in_const_fn!(n != 0);
        let shift = n.leading_zeros();
        let normalized_modulus = n << shift;
        let fast_div = FastDivideNormalized::new(normalized_modulus);
        ModuloRingSmall {
            normalized_modulus,
            shift,
            fast_div,
        }
    }

    #[inline]
    pub(crate) const fn normalized_modulus(&self) -> Word {
        self.normalized_modulus
    }

    #[inline]
    pub(crate) const fn shift(&self) -> u32 {
        self.shift
    }

    #[inline]
    pub(crate) const fn fast_div(&self) -> FastDivideNormalized {
        self.fast_div
    }
}

impl ModuloRingLarge {
    /// Create a new large ring of integers modulo `n`.
    fn new(n: &[Word]) -> ModuloRingLarge {
        let mut normalized_modulus = n.to_vec();
        let (shift, fast_div_top) = div::normalize_large(&mut normalized_modulus);
        ModuloRingLarge {
            normalized_modulus,
            shift,
            fast_div_top,
        }
    }

    pub(crate) fn normalized_modulus(&self) -> &[Word] {
        &self.normalized_modulus
    }

    pub(crate) fn shift(&self) -> u32 {
        self.shift
    }

    pub(crate) fn fast_div_top(&self) -> FastDivideNormalized {
        self.fast_div_top
    }

    pub(crate) fn is_valid(&self, val: &[Word]) -> bool {
        val.len() == self.normalized_modulus.len()
            && cmp::cmp_same_len(val, &self.normalized_modulus) == Ordering::Less
            && val[0] & math::ones::<Word>(self.shift) == 0
    }
}