What is this zero-invariant modulus function called?

Question

I've got some code that calculates a cyclic offset for a given integer, and I want it to calculate the cyclic-offset such that the function's output will not show any anomalous behavior as the input value transitions from positive to negative and back.

Here's my current implementation, which appears to work correctly, AFAICT:

 #include <stdio.h>

 unsigned int PositiveModulus(int value, unsigned int divisor)
 {
    if (value < 0)
    {
       const int numCyclesToAdd = 1+((-value)/divisor);
       value += numCyclesToAdd*divisor;
    }
    return value%divisor;
 }

 // unit test
 int main(int argc, char ** argv)
 {
    for (int i=-10; i<=10; i++) printf("%i -> %u\n", i, PositiveModulus(i,5));
    return 0;
 }

... in particular, when I run the above, I get the following output, which demonstrates the behavior I want:

 $ ./a.out
 -10 -> 0
 -9 -> 1
 -8 -> 2
 -7 -> 3
 -6 -> 4
 -5 -> 0
 -4 -> 1
 -3 -> 2
 -2 -> 3
 -1 -> 4   // note output transitions from 4 to 0 on these two
 0 -> 0    // lines, just like every other iteration of the cycle
 1 -> 1
 2 -> 2
 3 -> 3
 4 -> 4
 5 -> 0
 6 -> 1
 7 -> 2
 8 -> 3
 9 -> 4
 10 -> 0

My question is, does this function have a well-known/official name? (Searching for "positive modulus" returns some results, but the function described in those results doesn't seem to behave the same as the above code)

... and a bonus question is: Is the function shown above the best way to implement this behavior, or is there another approach that is more concise and/or mathematically correct?

Answer 1

What is this zero-invariant modulus function called?

A potential C-like name is Euclidean modulo.
Just mod(), @lockcmpxchg8b, would be OK if parameters were both int, yet int value, unsigned divisor is a special combination.

---

Here's my current implementation, which appears to work correctly, AFAICT:

Code has avoidable corner issues on this line of code:

const int numCyclesToAdd = 1+((-value)/divisor);

PositiveModulus(INT_MIN, any_divisor)
// UB (undefined behavior)
// int overflow with -INT_MIN

PositiveModulus(INT_MIN+1, 1)
// Implementation defined behavior on conversion `unsigned` to `int` during assignment.
// int numCyclesToAdd = 1+((-(INT_MIN+1)/1u);

---

Candidate improvement useful when * is expensive.

Even works when value == INT_MIN and avoids the UB of OP's (-INT_MIN).

unsigned PositiveModulus(int value, unsigned divisor) {
  unsigned result;
  if (value < 0) {
    unsigned uv = -1 - value;
    uv %= divisor;
    result = divisor - 1 - uv;
  } else {
    result = value%divisor;
  }
  return result;
}

Answer 2

Not sure about the name of the function, but there is a slightly better way.

If you simply return value%divisor from the function and change divisor and the return value to int, you get this:

-10 -> 0
-9 -> -4
-8 -> -3
-7 -> -2
-6 -> -1
-5 -> 0
-4 -> -4
-3 -> -3
-2 -> -2
-1 -> -1
0 -> 0
1 -> 1
2 -> 2
3 -> 3
4 -> 4
5 -> 0
6 -> 1
7 -> 2
8 -> 3
9 -> 4
10 -> 0

Note that you can go from the negative mod to the positive mod by just adding the divisor. So you can simplify the function like this:

unsigned int PositiveModulus(int value, int divisor)
{
    int result = value%divisor;
    if (result < 0) {
        return result + divisor;
    } else {
        return result;
    }
}

Note that it's necessary to change the type of divisor to int instead of unsigned, otherwise a negative value gets converted to a large unsigned values.