modulus : Java Glossary

modulus
In Java you take the remainder with the % operator. % is informally called the modulus operator, (sometimes called mod or modulo) though mathematicians and serious computer scientists would beg to differ, it is a remainder operator not a modulus. The JLS (Java Language Specification) correctly refers to it as a remainder operator.

Happily, Java division has the Euclidean property namely when you multiply the quotient by the divisor and add the remainder you get back to the dividend. When you ask for % 3 in Java, you may be astounded to sometimes get an answer outside the range 0..2. See remainder/modulus sign rules. Be especially careful when corralling random numbers into a smaller range with the % operator.

Negative Operands

Java’s modulus behaves, well, strangely. In Java, the sign of the remainder follows the dividend, not the divisor as you would expect. % can produce a negative result even with a positive divisor. Be especially careful when corralling random numbers into a smaller range with the modulus operator, e.g. wheel.nextInt() % 3 will give you numbers -2 .. +2 not 0 .. 2 as most would expect.

For example, when you do a day of week calculation by taking day_number % 7 in Java, you will be astounded to sometimes get a negative answer outside the range 0 .. 6, namely when the dividend is negative. See sign rules. Java division is truncated division.

Mixed Base Calculations

The modulus operator is useful in time calculation, e. g. how many days, hours, minutes, seconds, milliseconds is 112,233,445,566,778,899 milliseconds? Going the other way from days, hours, minutes and seconds to milliseconds is easier. You just multiply each component
```static final long MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000L;
static final long MILLISECONDS_PER_HOUR = 60 * 60 * 1000L;
static final long MILLISECONDS_PER_MINUTE = 60 * 1000L;
static final long MILLISECONDS_PER_SECOND = 1000L;

long millis = days * MILLISECONDS_PER_DAY + hours * MILLISECONDS_PER_HOUR
+ minutes * MILLISECONDS_PER_MINUTE
+ seconds * MILLISECONDS_PER_SECOND
+ milliseconds;```
This is a rather simplistic answer to the problem. For more complicated answers see Calendar.

You can use similar logic to deal with other goofy mixed base systems like latitude and longitude with its degrees, minutes and seconds, yards, feet and inches or tons, pounds and ounces. APL (A Programming Language) has built-in operators to neatly handle these. In Java you have to code the conversions out longhand.

Sign Rules

Remainder, modulus and division are often defined in a quirky way in computer languages, often to make it quick and easy to implement on the author’s hardware. Java has %, the remainder operator, but does not have a built-in modulus operator or function.
Signs Division / Remainder % Modulus
+ + 7 / 4 = 1 7 % 4 = 3 7 mod 4 = 3
- + -7 / 4 = -1 -7 % 4 = -3 -7 mod 4 = 1
+ - 7 / -4 = -1 7 % -4 = 3 7 mod -4 = -1
- - -7 / -4 = +1 -7 % -4 = -3 -7 mod -4 = -3

By examining the patterns in the following three tables of Java remainder %, mod mathematical modulus and / integer division, you will have a better intuition of how they work. Note how for Java %, the sign of the divisor is irrelevant. The sign of the result follows the sign of the dividend. Note for mathematical modulus, the result is always in the range 0..divisor-1 for positive divisors, irrespective of the sign of the dividend and the result is always in the range divisor+1..0 for negative divisors, irrespective of the sign of the dividend. % and modulus give the same results when the signs of dividend and divisor match. It is interesting to note how complex the symmetries and repetitions are.
Integer Division: col / row
-10 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 10
-10 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -1 -10
-9 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -1 -1 -9
-8 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -1 -1 -1 -8
-7 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 -1 -1 -1 -1 -7
-6 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 -1 -1 -1 -1 -1 -6
-5 2 1 1 1 1 1 0 0 0 0 0 0 0 0 0 -1 -1 -1 -1 -1 -2 -5
-4 2 2 2 1 1 1 1 0 0 0 0 0 0 0 -1 -1 -1 -1 -2 -2 -2 -4
-3 3 3 2 2 2 1 1 1 0 0 0 0 0 -1 -1 -1 -2 -2 -2 -3 -3 -3
-2 5 4 4 3 3 2 2 1 1 0 0 0 -1 -1 -2 -2 -3 -3 -4 -4 -5 -2
-1 10 9 8 7 6 5 4 3 2 1 0 -1 -2 -3 -4 -5 -6 -7 -8 -9 -10 -1
0 - - - - - - - - - - - - - - - - - - - - - 0
1 -10 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 10 1
2 -5 -4 -4 -3 -3 -2 -2 -1 -1 0 0 0 1 1 2 2 3 3 4 4 5 2
3 -3 -3 -2 -2 -2 -1 -1 -1 0 0 0 0 0 1 1 1 2 2 2 3 3 3
4 -2 -2 -2 -1 -1 -1 -1 0 0 0 0 0 0 0 1 1 1 1 2 2 2 4
5 -2 -1 -1 -1 -1 -1 0 0 0 0 0 0 0 0 0 1 1 1 1 1 2 5
6 -1 -1 -1 -1 -1 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 6
7 -1 -1 -1 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 7
8 -1 -1 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 8
9 -1 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 9
10 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 10
-10 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 10
Java Remainder: col % row == col - row * ( col / row -10 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 ) 0 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 0 -1 0 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 0 1 -2 -1 0 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 0 1 2 -3 -2 -1 0 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 0 1 2 3 -4 -3 -2 -1 0 -5 -4 -3 -2 -1 0 1 2 3 4 5 0 1 2 3 4 0 -4 -3 -2 -1 0 -4 -3 -2 -1 0 1 2 3 4 0 1 2 3 4 0 -2 -1 0 -3 -2 -1 0 -3 -2 -1 0 1 2 3 0 1 2 3 0 1 2 -1 0 -2 -1 0 -2 -1 0 -2 -1 0 1 2 0 1 2 0 1 2 0 1 0 -1 0 -1 0 -1 0 -1 0 -1 0 1 0 1 0 1 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 - - - - - - - - - - - - - - - - - - - - - 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -1 0 -1 0 -1 0 -1 0 -1 0 1 0 1 0 1 0 1 0 1 0 -1 0 -2 -1 0 -2 -1 0 -2 -1 0 1 2 0 1 2 0 1 2 0 1 -2 -1 0 -3 -2 -1 0 -3 -2 -1 0 1 2 3 0 1 2 3 0 1 2 0 -4 -3 -2 -1 0 -4 -3 -2 -1 0 1 2 3 4 0 1 2 3 4 0 -4 -3 -2 -1 0 -5 -4 -3 -2 -1 0 1 2 3 4 5 0 1 2 3 4 -3 -2 -1 0 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 0 1 2 3 -2 -1 0 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 0 1 2 -1 0 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 0 1 0 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 0
Mathematical Modulus: col mod row == (col % row + row) -10 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 % row 0 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 -9 -8 -7 -6 -5 -4 -3 -2 -1 0 -1 0 -8 -7 -6 -5 -4 -3 -2 -1 0 -8 -7 -6 -5 -4 -3 -2 -1 0 -8 -2 -1 0 -7 -6 -5 -4 -3 -2 -1 0 -7 -6 -5 -4 -3 -2 -1 0 -7 -6 -3 -2 -1 0 -6 -5 -4 -3 -2 -1 0 -6 -5 -4 -3 -2 -1 0 -6 -5 -4 -4 -3 -2 -1 0 -5 -4 -3 -2 -1 0 -5 -4 -3 -2 -1 0 -5 -4 -3 -2 0 -4 -3 -2 -1 0 -4 -3 -2 -1 0 -4 -3 -2 -1 0 -4 -3 -2 -1 0 -2 -1 0 -3 -2 -1 0 -3 -2 -1 0 -3 -2 -1 0 -3 -2 -1 0 -3 -2 -1 0 -2 -1 0 -2 -1 0 -2 -1 0 -2 -1 0 -2 -1 0 -2 -1 0 -2 0 -1 0 -1 0 -1 0 -1 0 -1 0 -1 0 -1 0 -1 0 -1 0 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 - - - - - - - - - - - - - - - - - - - - - 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 2 0 1 2 0 1 2 0 1 2 0 1 2 0 1 2 0 1 2 0 1 2 3 0 1 2 3 0 1 2 3 0 1 2 3 0 1 2 3 0 1 2 0 1 2 3 4 0 1 2 3 4 0 1 2 3 4 0 1 2 3 4 0 2 3 4 5 0 1 2 3 4 5 0 1 2 3 4 5 0 1 2 3 4 4 5 6 0 1 2 3 4 5 6 0 1 2 3 4 5 6 0 1 2 3 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 8 0 1 2 3 4 5 6 7 8 0 1 2 3 4 5 6 7 8 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0

Getting the digits of a Number, any Radix

Modulus can be used to take a number apart into digits, decimal, hexadecimal or any other base.

Even or Odd?

You can tell if an int is even or odd by looking at its remainder, modulus 2:
```boolean even = x % 2 == 0;
boolean odd = x % 2 != 0;```
Note this similar code you often see posted will not work for negative numbers:
```boolean even = x % 2 == 0;
boolean odd = x % 2 == 1; // does not work for negative x```
There is a faster way to compute these, by masking off the low order bit:
```boolean even = ( x & 1 ) == 0;
boolean odd = ( x & 1 ) != 0;```
The code can be even faster if you want a number 0 or 1 as the result, say for indexing an array, instead of a boolean:
`int odd = x & 1;`

Every nth

Let’s say you wanted to do something every fourth line, e.g. insert a blank, a coloured bar, a tick…

Other Uses

Modulus can be used in computing the next free circular squirrel cage buffer.
`int nextbuf = ( thisbuf + 1 ) % supply;`
Modulus can be used to turn an offset into a file into a chunk number and offset within that chunk.
```int recordNumber = fileOffset / blockSize;
int recordOffset = fileOffset % blockSize;```

Floating Point %

% is also defined to work with float and double operands, though that use is quite rare.

The result of a floating-point remainder operation as computed by the % operator is not the same as that produced by the remainder operation defined by the IEEE 754 floating point standard. The IEEE (Institute of Electrical & Electronics Engineers) 754 remainder operation computes the remainder from a rounding division, not a truncating division. % on floating-point operations behaves analogously to the integer remainder operator; this may be compared with the C library function fmod. The IEEE 754 remainder operation may be computed by the library routine Math. IEEEremainder. (Note the violation of the naming conventions.)

Learning More

*
+
++
--
/
absolute value
Bali proposal for redefining how % works
division
floating point
mixed base
operator