malachite_base/unsigned_vector/arithmetic/
mod_neg.rs

1// Copyright © 2026 Mikhail Hogrefe
2//
3// This file is part of Malachite.
4//
5// Malachite is free software: you can redistribute it and/or modify it under the terms of the GNU
6// Lesser General Public License (LGPL) as published by the Free Software Foundation; either version
7// 3 of the License, or (at your option) any later version. See <https://www.gnu.org/licenses/>.
8
9use crate::num::arithmetic::traits::{ModIsReduced, ModNeg, ModNegAssign};
10use crate::num::basic::unsigneds::PrimitiveUnsigned;
11use crate::unsigned_vector::UnsignedVector;
12
13fn assert_reduced<T: PrimitiveUnsigned>(v: &UnsignedVector<T>, m: T) {
14    assert!(
15        v.mod_is_reduced(&m),
16        "self must be reduced mod m, but {v} has an element >= {m}"
17    );
18}
19
20// Negates every element modulo m.
21fn negate<T: PrimitiveUnsigned>(elements: &mut [T], m: T) {
22    for x in elements {
23        if *x != T::ZERO {
24            *x = m - *x;
25        }
26    }
27}
28
29impl<T: PrimitiveUnsigned> ModNeg<T> for UnsignedVector<T> {
30    type Output = Self;
31
32    /// Negates an [`UnsignedVector`] modulo $m$, taking the vector by value. The elements must
33    /// already be reduced modulo $m$.
34    ///
35    /// Each element $x$ becomes $-x \bmod m$: $m - x$ if $x$ is nonzero, and 0 if it is zero. The
36    /// dimension is unchanged.
37    ///
38    /// $$
39    /// f(v, m) = -v \bmod m.
40    /// $$
41    ///
42    /// # Worst-case complexity
43    /// $T(n) = O(n)$
44    ///
45    /// $M(n) = O(1)$
46    ///
47    /// where $T$ is time, $M$ is additional memory, and $n$ is `self.dimension()`.
48    ///
49    /// # Panics
50    /// Panics if `m` is zero, or if any element of `self` is greater than or equal to `m`.
51    ///
52    /// # Examples
53    /// ```
54    /// use core::str::FromStr;
55    /// use malachite_base::num::arithmetic::traits::ModNeg;
56    /// use malachite_base::unsigned_vector::UnsignedVector;
57    ///
58    /// let v = UnsignedVector::<u8>::from_str("(5, 1, 0)").unwrap();
59    /// assert_eq!(v.mod_neg(7).to_string(), "(2, 6, 0)");
60    /// ```
61    ///
62    /// This is equivalent to `_nmod_vec_neg` from `nmod_vec/neg.c`, FLINT 3.6.0.
63    #[inline]
64    fn mod_neg(mut self, m: T) -> Self {
65        self.mod_neg_assign(m);
66        self
67    }
68}
69
70impl<T: PrimitiveUnsigned> ModNeg<T> for &UnsignedVector<T> {
71    type Output = UnsignedVector<T>;
72
73    /// Negates an [`UnsignedVector`] modulo $m$, taking the vector by reference. The elements must
74    /// already be reduced modulo $m$.
75    ///
76    /// Each element $x$ becomes $-x \bmod m$: $m - x$ if $x$ is nonzero, and 0 if it is zero. The
77    /// dimension is unchanged.
78    ///
79    /// $$
80    /// f(v, m) = -v \bmod m.
81    /// $$
82    ///
83    /// # Worst-case complexity
84    /// $T(n) = O(n)$
85    ///
86    /// $M(n) = O(n)$
87    ///
88    /// where $T$ is time, $M$ is additional memory, and $n$ is `self.dimension()`.
89    ///
90    /// # Panics
91    /// Panics if `m` is zero, or if any element of `self` is greater than or equal to `m`.
92    ///
93    /// # Examples
94    /// ```
95    /// use core::str::FromStr;
96    /// use malachite_base::num::arithmetic::traits::ModNeg;
97    /// use malachite_base::unsigned_vector::UnsignedVector;
98    ///
99    /// let v = UnsignedVector::<u8>::from_str("(5, 1, 0)").unwrap();
100    /// assert_eq!((&v).mod_neg(7).to_string(), "(2, 6, 0)");
101    /// ```
102    ///
103    /// This is equivalent to `_nmod_vec_neg` from `nmod_vec/neg.c`, FLINT 3.6.0.
104    #[inline]
105    fn mod_neg(self, m: T) -> UnsignedVector<T> {
106        assert_reduced(self, m);
107        let mut elements = self.elements.clone();
108        negate(&mut elements, m);
109        UnsignedVector { elements }
110    }
111}
112
113impl<T: PrimitiveUnsigned> ModNegAssign<T> for UnsignedVector<T> {
114    /// Negates an [`UnsignedVector`] modulo $m$, in place. The elements must already be reduced
115    /// modulo $m$.
116    ///
117    /// See [`mod_neg`](ModNeg::mod_neg).
118    ///
119    /// # Worst-case complexity
120    /// $T(n) = O(n)$
121    ///
122    /// $M(n) = O(1)$
123    ///
124    /// where $T$ is time, $M$ is additional memory, and $n$ is `self.dimension()`.
125    ///
126    /// # Panics
127    /// Panics if `m` is zero, or if any element of `self` is greater than or equal to `m`.
128    ///
129    /// # Examples
130    /// ```
131    /// use core::str::FromStr;
132    /// use malachite_base::num::arithmetic::traits::ModNegAssign;
133    /// use malachite_base::unsigned_vector::UnsignedVector;
134    ///
135    /// let mut v = UnsignedVector::<u8>::from_str("(5, 1, 0)").unwrap();
136    /// v.mod_neg_assign(7);
137    /// assert_eq!(v.to_string(), "(2, 6, 0)");
138    /// ```
139    #[inline]
140    fn mod_neg_assign(&mut self, m: T) {
141        assert_reduced(self, m);
142        negate(&mut self.elements, m);
143    }
144}
malachite_base/unsigned_vector/arithmetic/mod_neg.rs

malachite_base/unsigned_vector/arithmetic/
mod_neg.rs
