Is there a modulus (not remainder) function / operation?

Question

In Rust (like most programming languages), the % operator performs the remainder operation, not the modulus operation. These operations have different results for negative numbers:

-21 modulus 4 => 3
-21 remainder 4 => -1

println!("{}", -21 % 4); // -1

However, I want the modulus.

I found a workaround ((a % b) + b) % b, but I don't want to reinvent the wheel if there's already a function for that!

Any reason to use the term `modulus` instead of `modulo` (which is more common AFAICS). — ideasman42, Jan 02 '17 at 08:33
They might have studied somewhere where the term modulus is used, not knowing that different institutions tend to differ in vocabulary. — OliverUv, Dec 24 '17 at 19:32
For powers of two, you can do something like -21 & (4 - 1), granted it's an integer. — AldaronLau, Aug 14 '20 at 22:45

score 108 · Answer 1 · answered Aug 03 '19 at 20:53

108

RFC 2196 adds a couple of integer methods related to euclidian division. Specifically, the rem_euclid method (example link for i32) is what you are searching for:

println!("{}", -1i32 % 4);                // -1
println!("{}", (-21i32).rem_euclid(4));   // 3

This method is available in rustc 1.38.0 (released on 2019-09-27) and above.

answered Aug 03 '19 at 20:53

Lukas Kalbertodt

79,749
26
255
305

3

They are also implemented for unsigned variants, although it is not possible to figure out what they do from that documentation. I would also mention `div_euclid()` for completeness. But this should be the selected answer anyway. – nert May 10 '20 at 11:50
@nert when you see `int_impl!` you can go to this file and see the actual implementation: https://github.com/rust-lang/rust/blob/81799cd8fd841e23b52876ae5e22faeb3ad04eb5/library/core/src/num/int_macros.rs#L672-L696 – Anemoia Apr 28 '22 at 05:21
such a misnomer. remainder should be modulos and modulos remainder. – Nearoo Dec 13 '22 at 14:20

score 43 · Answer 2 · edited Aug 16 '20 at 19:19

43

Is there a modulus (not remainder!) function / operation in Rust?

As far as I can tell, there is no modular arithmetic function.

This also happens in C, where it is common to use the workaround you mentioned: ((a % b) + b) % b.

In C, C++, D, C#, F# and Java, % is in fact the remainder. In Perl, Python or Ruby, % is the modulus.

Language developers don't always go the "correct mathematical way", so computer languages might seem weird from the strict mathematician view. The thing is that both modulus and remainder, are correct for different uses.

Modulus is more mathematical if you like, while the remainder (in the C-family) is consistent with common integer division satisfying: (a / b) * b + a % b = a; this is adopted from old Fortran. So % is better called the remainder, and I suppose Rust is being consistent with C.

You are not the first to note this:

edited Aug 16 '20 at 19:19

AldaronLau

1,044
11
15

answered Jul 03 '15 at 16:01

JosEduSol

5,268
3
23
31

4

I, as a C/C++ programmer, am embarrassed that I didn't know that `%` works in C that way, too... – Kapichu Jul 03 '15 at 16:08
4

Isn't this a gap in Rust? – Kapichu Jul 03 '15 at 16:09
1

Well, as you expect, this is not something mathematicians enjoy. And i would not say it is a gap, for all this family of languages `%` is just the remainder. – JosEduSol Jul 03 '15 at 16:20
2

I'll go with `%` being the remainder, but not having support for modulus sucks... – Kapichu Jul 03 '15 at 16:24
6

@JosEduSol As I write this, the answer above shows `(a % b) + b` as a way to calculate the modulus, but I'm pretty sure what you meant to write is this: `((a % b) + b) % b`. – David J. Nov 21 '18 at 01:58
4

`(a / b) * b + a mod b = a` is satisfied if `/` rounds toward -∞. – Vaelus Oct 04 '19 at 14:46
It has been added now, see next comment. – Hypno Jan 30 '21 at 12:11

score 10 · Answer 3 · edited Nov 21 '18 at 20:01

10

No, Rust doesn't have a built in modulus, see this discussion for some reasons why.

Here's an example that might be handy:

///
/// Modulo that handles negative numbers, works the same as Python's `%`.
///
/// eg: `(a + b).modulo(c)`
///
pub trait ModuloSignedExt {
    fn modulo(&self, n: Self) -> Self;
}
macro_rules! modulo_signed_ext_impl {
    ($($t:ty)*) => ($(
        impl ModuloSignedExt for $t {
            #[inline]
            fn modulo(&self, n: Self) -> Self {
                (self % n + n) % n
            }
        }
    )*)
}
modulo_signed_ext_impl! { i8 i16 i32 i64 }

edited Nov 21 '18 at 20:01

Shepmaster

388,571
95
1,107
1,366

answered Jan 02 '17 at 06:01

ideasman42

42,413
44
197
320

Would `modulo_signed_ext_impl! { i8 i16 i32 i64 isize u8 u16 u32 u64 usize }` be better? – Alexx Roche Aug 25 '20 at 23:30

score -2 · Answer 4 · answered Aug 25 '20 at 23:27

-2

From the other answers I constructed:

fn n_mod_m <T: std::ops::Rem<Output = T> + std::ops::Add<Output = T> + Copy>
  (n: T, m: T) -> T {
    ((n % m) + m) % m
}

assert_eq!(n_mod_m(-21, 4), 3);

answered Aug 25 '20 at 23:27

Alexx Roche

3,151
1
33
39

2

If you're going to use that on integers, how is it better than the built-in [`rem_euclid` mentioned in Lukas Kalbertodt's answer](https://stackoverflow.com/a/57342011/2733851)? – mcarton Aug 26 '20 at 00:37
I find this explicit function easier to mentally parse than the opaque .rem_euclid() – Alexx Roche Aug 27 '20 at 14:05

Is there a modulus (not remainder) function / operation?

4 Answers4

Linked

Related