Module in Rust: Don't Confuse It with the Remainder

Introduction: Why is the question about modulus so popular?

If you've ever written code in Rust and encountered negative numbers, you've probably wondered: "Where is the modulus function?" This question has thousands of views on Stack Overflow, and for good reason. The fact is that the % operator in Rust is not modulus, but the remainder. The difference is subtle but critical, especially in algorithms, cryptography, or working with cyclic structures.

In this article, we'll figure out how mathematical modulus differs from remainder, how Rust handles negative numbers, and how to write your own function for calculating the true modulus. The article is aimed at beginners but will also be useful for experienced developers who want to refresh their knowledge.

Table of Contents

\n
• What are modulus and remainder: the mathematical difference
\n
• Why % in Rust is not modulus
\n
• How to write a modulus function in Rust
\n
• Real-life examples: cyclic indices and hashes
\n
• Conclusions and practical tips
\n

Mathematics: Modulus vs Remainder

Let's start with the basics. In mathematics, modulus is an operation that returns a non-negative number less than the divisor. For example:

\n
• 7 mod 3 = 1 (7 divided by 3 gives a remainder of 1)
\n
• -7 mod 3 = 2 (because -7 = 3 * (-3) + 2)
\n

Remainder is what is left after integer division. In most programming languages (C, C++, Java, Rust), the % operator returns exactly the remainder, which can be negative if the dividend is negative. Example:

\n
• 7 % 3 = 1 (matches)
\n
• -7 % 3 = -1 (in Rust, because -7 / 3 = -2, remainder -1)
\n

Why is this important? Imagine you are writing a program for a clock: time 0–23. If it's 22:00 now and you add 5 hours, you get 3:00 AM. This works with modulus: (22 + 5) mod 24 = 3. But if you use remainder, everything breaks with negative values. For example, (-3) % 24 in Rust gives -3, not 21.

Why the % Operator in Rust is a Remainder

In Rust, the % operator is defined as the remainder. This is fixed in the documentation and the behavior of the standard library. The reason is historical: it's done this way in C and many other languages. Rust follows the principle of "explicit is better than implicit," but here beginners often fall into a trap.

fn main() {\n    println!("7 % 3 = {}", 7 % 3);   // 1\n    println!("-7 % 3 = {}", -7 % 3); // -1\n    println!("7 % -3 = {}", 7 % -3); // 1 (yes, the sign of the divisor does not affect it)\n    println!("-7 % -3 = {}", -7 % -3); // -1\n}

Note: the sign of the result always matches the sign of the dividend. This is not modulus. For true modulus, the result must always be non-negative.

How to Write a True Modulus Function in Rust?

The Rust standard library does not provide a built-in function for modulus (unlike Python, where % works as modulus). But it's very simple to write one. Here is the most common way — using remainder with correction.

Modulus function for integers

fn modulus(a: i32, b: i32) -> i32 {\n    let r = a % b;\n    if r < 0 { r + b.abs() } else { r }\n}\n\nfn main() {\n    println!("modulus(7, 3) = {}", modulus(7, 3));   // 1\n    println!("modulus(-7, 3) = {}", modulus(-7, 3)); // 2\n    println!("modulus(7, -3) = {}", modulus(7, -3)); // 1 (modulus is always non-negative)\n    println!("modulus(-7, -3) = {}", modulus(-7, -3)); // 2\n}

How it works: we take the remainder a % b. If it is negative, we add the absolute value of