[API Proposal]: Getting the positive remainder (Mod) when dividing a number by another

[JansthcirlU]

Background and motivation

The case for positive remainders (number division)

Background

This proposal is inspired by a previous request to add an operator dedicated to returning the non-negative remainder when dividing two numbers, but adding a whole operator is way beyond the scope of this API request. Nonetheless, I will be summarising the anecdotal use cases and arguments in favour of adding this functionality to the runtime.

The existing % operator for calculating the remainder

Currently there exists a % operator in C# that yields a remainder when dividing some number a by some other number b, for example 14 % 3 yields 2 because 14 is 2 more than 12, which is the biggest multiple of 3 that fits into 14. Similarly, 8 % 2 is 0 because 8 already is a multiple of 2. This is most likely the most common use case for the % operator, and it works just fine for that purpose.

Issues with the existing % operator

Judging by the example above, you might think that the % operator works like the so-called modular arithmetic, also known as clock arithmetic. Imagine it's 7 PM and you want to know what time it will be in 8 hours. After 5 hours it is 12 AM, so after another 3 hours it will be 3 AM. In other words (7 + 8) % 12 should be equal to 3, which it is in C#. What about going backwards in time? If it's 3 AM, then 8 hours ago it was 7 PM. So does that mean that (3 - 8) % 12 is equal to 7 in C#? Nope, it isn't. For historical reasons, the % operator sometimes yields negative remainders, and (3 - 8) % 12 actually returns -5.

When you only use positive numbers, then the % operator should cause you no headaches. But once negative numbers are involved and you'd like to use it like clock arithmetic, like in the examples above, you're out of luck; you'll have to write your own methods to return a non-negative remainder (modulus) for the various existing numerical types.

For those who are more interested in the differences between the C# remainder and the modulus, Eric Lippert wrote an article on his blog about this very topic. As you can tell from the comments on that article, many developers were not aware of the differences, but are puzzled as to why the operator doesn't produce the more intuitive non-negative modulus.

Practical use cases for a non-negative remainder

Building on the basic clock arithmetic example, a non-negative remainder greatly increases the quality of life for programming anything that is cyclic in nature, such as times, dates, and angles.

Working with angles

It's common to normalise an angle theta so that it always falls within the interval 0 ≤ theta < 2π, for example in robotics and other branches of maths and engineering. If you try to do this with %, then you will run into issues when theta inevitably becomes less than 0. On the other hand, the non-negative modulus will always satisfy this condition.

Cyclical map design (Pacman)

When you make a 2D game that works like Pacman, you may define a playable area where each position can be represented as some coordinate (x, y) where 0 ≤ x < width and 0 ≤ y < height. To allow the player to cross over from one side of the map to the other, you might use the following logic:

// Player movement logic in time increments of dt (delta time)
if (Input.GetKey ("w"))
{
    // Yields a negative position when pos.y - speed * dt is less than zero
    pos.y = (pos.y - speed * dt) % mapHeight;
}
if (Input.GetKey ("a"))
{
    // Yields a negative position when pos.x - speed * dt is less than zero
    pos.x = (pos.x - speed * dt) % mapWidth;
}
if (Input.GetKey ("s"))
{
    pos.y = (pos.y + speed * dt) % mapHeight;
}
if (Input.GetKey ("d"))
{
    pos.x = (pos.x + speed * dt) % mapWidth;
}

As you can see, if the player keeps going up or left, their x or y position will be negative and they will effectively disappear from the playing field. With a nonnegative remainder, their position will always be between 0 and the maximum allowed value.

Cycling over array indices

In this reply to the original discussion, somebody tried to implement cyclical or circular array indexing using the existing % operator. But similarly to the wrapped playing field of Pacman, using negative indices causes an IndexOutOfRangeException when you wouldn't expect one.

With the new range/index features in C# 8, you can actually call elements at an index that counts back from the end of the array. This is something that could easily be accomplished with a non-negative modulus, but rather than adding an out-of-the-box modulus, a whole new ^ operator was added to make backwards indexing possible. If adding the range operator was worth the possible risks, why not instead add a proper modulus operator to keep things nice and uniform?

int[] test = new int[5] { 1, 2, 3, 4, 5 };
Console.WriteLine("Iterating over the array twice."); // Expected result: 1234512345
for (int i = 0; i < 10; i++)
{
    Console.Write(test[i % test.Length]); // Works when i >= 0
}
Console.WriteLine("\nIterating backwards over the array twice."); // Expected result 5432154321
for (int i = -1; i >= -10 ; i--)
{
    int index = i % test.Length;
    // Console.Write(test[index]); // Throws IndexOutOfRangeException
    Console.Write(test[index < 0 ? ^-index : index]); // Is this really better than having a proper modulus?
}
Console.WriteLine("\nProgram has finished.");

Conversion from Python (and possibly other languages)

In Python, the same % operator exists, but contrary to C# it already returns the modulus. When you create a software in Python using this operator, and you want to convert your Python code to C# code, it's not unreasonable to think that the operator implementations are the same. Unfortunately, like this person says in the aforementioned discussion, their C# code behaved differently to the Python code they had written.

Why should this be standard?

The scenarios above may seem rather uncommon or niche, and it is true that the average "corporate" programmer may never need this functionality to write an "ordinary" application. However, C# is being used more and more in game development and in embedded development (e.g. robotics, computer vision, etc.), two rather maths-heavy industries. Programmers who are involved with anything geometrical will benefit greatly from a proper modulus function in the runtime.

At the time of writing, there are over 100k results on Github for C# alone when you look up code that contains Math.Mod. Sure, only a fraction of those results are actually custom implementations of the non-negative remainder, but it is being used quite a lot in scientific areas as well as in cryptography.

The modulus function is quickly written, and there certainly are NuGet packages out there for maths extensions like MathNet.Numerics that probably contain a modulus function somewhere, but if it's just this one method that doesn't depend on a whole host of other functionalities, why not just include it in the runtime? The existing % operator is utterly useless half the time, after all.

People who need a modulus function in C# will definitely start looking for it in the Math library first, and go to stack overflow next, eventually finding their way to the discussion that inspired this API request.

API Proposal

namespace System
{
    public static partial class Math
    {
        /// <summary>Calculates the positive remainder when dividing a dividend by a divisor.</summary>
        public static double Mod(double dividend, double divisor)
        {
            double remainder = dividend % divisor;
            if (remainder < 0)
            {
                if (divisor < 0)
                {
                    return remainder - divisor;
                }
                return remainder + divisor;
            }
            return remainder;
        }
    }
}

(similar implementation for other numerical types)

API Usage

Usage examples

Normalising angles

public class Program
{
    public static void Main()
    {
        double theta = 45.0; // theta is between 0° and 360°
        double thetaRad = fortyFive.ToRadians(); // thetaRad is between 0 and 2π
        Console.WriteLine(thetaRad == thetaRad.Normalise()); // true

        double thetaBig = 405.0; // thetaBig is NOT between 0° and 360°
        double thetaBigRad = thetaBig.ToRadians(); // thetaBigRad is NOT between 0 and 2π
        Console.WriteLine(thetaBigRad == thetaBigRad.Normalise()); // false
        Console.WriteLine(thetaRad == thetaBigRad.Normalise()); // true because 405 = 45 + 360
    }
    public static class AngleExtensions
    {
        public static double Normalise(this double radians)
            => Math.Mod(radians, 2 * Math.PI);
        public static double ToDegrees(this double radians)
            => radians * 180.0 / Math.PI;
        public static double ToRadians(this double degrees)
            => degrees * Math.PI / 180.0;
    }
}

Cyclically iterating over arrays

int[] test = new int[5] { 1, 2, 3, 4, 5 };
Console.WriteLine("Iterating over the array twice."); // Expected result: 1234512345
for (int i = 0; i < 10; i++)
{
    Console.Write(test[Math.Mod(i, test.Length]); // Works like i % test.Length
}
Console.WriteLine("\nIterating backwards over the array twice."); // Expected result 5432154321
for (int i = -1; i >= -10 ; i--)
{
    Console.Write(test[Math.Mod(i, test.Length]); // Still works despite i < 0
}
Console.WriteLine("\nProgram has finished.");

Or, if the modulus had had a dedicated operator as proposed in the aforementioned discussion, you could've even written i %% test.Length, which is way more readable than Math.Mod(i, test.Length).

For the other scenarios, replace a % b by Math.Mod(a, b).

Alternative Designs

While a shared Math method is possible, the modulus function might be more appropriate as a static method on the numerical types themselves, for example int.Mod, double.Mod and so on. A similar case can be made for DateOnly.Mod and TimeOnly.Mod.

Risks

I don't see how adding a new method to the Math library or to individual numerical classes would pose any big risks. There is a slight concern for possible bugs because the modulus function would have to be implemented separately for each numerical type (and non-numerical types that would benefit from it), so a simple copy and paste won't cut it, unless the modulus function can be implemented generically somehow.

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

Tagging subscribers to this area: @dotnet/area-system-numerics
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

The case for positive remainders (number division)

Background

This proposal is inspired by a previous request to add an operator dedicated to returning the non-negative remainder when dividing two numbers, but adding a whole operator is way beyond this API request. Nonetheless, I will be summarising the anecdotal use cases and arguments in favour of adding this functionality to the runtime.

The existing % operator for calculating the remainder

Currently there exists a % operator in C# that yields a remainder when dividing some number a by some other number b, for example 14 % 3 yields 2 because 14 is 2 more than 12, which is the biggest multiple of 3 that fits into 14. Similarly, 8 % 2 is 0 because 8 already is a multiple of 2. This is most likely the most common use case for the % operator, and it works just fine for that purpose.

Issues with the existing % operator

Judging by the example above, you might think that the % operator works like the so-called modular arithmetic, also known as clock arithmetic. Imagine it's 7 PM and you want to know what time it will be in 8 hours. After 5 hours it is 12 AM, so after another 3 hours it will be 3 AM. In other words (7 + 8) % 12 should be equal to 3, which it is in C#. What about going backwards in time? If it's 3 AM, then 8 hours ago it was 7 PM. So does that mean that (3 - 8) % 12 is equal to 7 in C#? Nope, it isn't. For historical reasons, the % operator sometimes yields negative remainders, and (3 - 8) % 12 actually returns -5.

When you only use positive numbers, then the % operator should cause you no headaches. But once negative numbers are involved and you'd like to use it like clock arithmetic, like in the examples above, you're out of luck; you'll have to write your own methods to return a non-negative remainder (modulo) for the various existing numerical types.

Practical use cases for a non-negative remainder

Building on the basic clock arithmetic example, a non-negative remainder greatly increases the quality of life for programming anything that is cyclic in nature, such as times, dates, and angles.

Working with angles

It's common to normalise or sanitise an angle theta so that it always falls within the interval 0 ≤ theta < 2π, for example in robotics and other branches of maths and engineering. If you try to do this with %, then you will run into issues when theta inevitably becomes less than 0. On the other hand, the non-negative modulus will always satisfy this condition.

Cyclical map design (Pacman)

When you make a 2D game that works like Pacman, you may define a playable area where each position can be represented as some coordinate (x, y) where 0 ≤ x ≤ width and 0 ≤ y ≤ height. To allow the player to cross over from one side of the map to the other, you might use the following logic:

// Player movement logic in time increments of dt (delta time)
if (Input.GetKey ("w"))
{
    // Yields a negative position when pos.y - speed * dt is less than zero
    pos.y = (pos.y - speed * dt) % mapHeight;
}
if (Input.GetKey ("a"))
{
    // Yields a negative position when pos.x - speed * dt is less than zero
    pos.x = (pos.x - speed * dt) % mapWidth;
}
if (Input.GetKey ("s"))
{
    pos.y = (pos.y + speed * dt) % mapHeight;
}
if (Input.GetKey ("d"))
{
    pos.x = (pos.x + speed * dt) % mapWidth;
}

As you can see, if the player keeps going up or left, their x or y position will be negative and they will effectively disappear from the playing field. With a nonnegative remainder, their position will always be between 0 and the maximum allowed value.

Cycling over array indices

In this reply to the original discussion, somebody tried to implement cyclical or circular array indexing using the existing % operator. But similarly to the wrapped playing field of Pacman, using negative indices causes an IndexOutOfRangeException when you wouldn't expect one.

Conversion from Python (and possibly other languages)

In Python, the same % operator exists, but it always returns a positive remainder. When you create a software in Python using this operator, and you want to convert your Python code to C# code, it's not unreasonable to think that the operator implementations are the same. Unfortunately, like this person says in the aforementioned discussion, their C# code behaved differently to the Python code they had written.

Why should this be standard?

The scenarios above may seem rather uncommon or niche, and it is true that the average "corporate" programmer may never need this functionality to write an "ordinary" application. However, C# is being used more and more in game development and in embedded development (e.g. robotics, computer vision, etc.), two rather maths-heavy industries. Programmers who are involved with anything geometrical will benefit greatly from a proper modulo function in the runtime.

At the time of writing, there are over 100k results on Github for C# alone when you look up code that contains Math.Mod. Sure, only a fraction of those results are actually custom implementations of the non-negative remainder, but it is being used quite a lot in scientific areas as well as in cryptography.

The modulo function is quickly written, and there certainly are NuGet packages out there for maths extensions like MathNet.Numerics that probably contain a modulo function somewhere, but if it's just this one method that doesn't depend on a whole host of other functionalities, why not just include it in the runtime? The existing % operator is utterly useless half the time, after all.

People who need a modulo function in C# will definitely start looking for it in the Math library first, and go to stack overflow next, eventually finding their way to the discussion that inspired this API request.

API Proposal

namespace System
{
    public static partial class Math
    {
        /// <summary>Calculates the positive remainder when dividing a dividend by a divisor.</summary>
        public static double Mod(double dividend, double divisor)
        {
            double remainder = dividend % divisor;
            if (remainder < 0)
            {
                if (divisor < 0)
                {
                    return remainder - divisor;
                }
                return remainder + divisor;
            }
            return remainder;
        }
    }
}

API Usage

Usage examples

Sanitising angles

public class Program
{
    public static void Main()
    {
        double theta = 45.0; // theta is between 0° and 360°
        double thetaRad = fortyFive.ToRadians(); // thetaRad is between 0 and 2π
        Console.WriteLine(thetaRad == thetaRad.Sanitise()); // true

        double thetaBig = 405.0; // thetaBig is NOT between 0° and 360°
        double thetaBigRad = thetaBig.ToRadians(); // thetaBigRad is NOT between 0 and 2π
        Console.WriteLine(thetaBigRad == thetaBigRad.Sanitise()); // false
        Console.WriteLine(thetaRad == thetaBigRad.Sanitise()); // true because 405 = 45 + 360
    }
    public static class AngleExtensions
    {
        public static double Sanitise(this double radians)
            => Math.Mod(radians, 2 * Math.PI);
        public static double ToDegrees(this double radians)
            => radians * 180.0 / Math.PI;
        public static double ToRadians(this double degrees)
            => degrees * Math.PI / 180.0;
    }
}

For the other scenarios, replace a % b by Math.Mod(a, b).

Alternative Designs

While a shared Math method is possible, the modulo function might be more appropriate as a static method on the numerical types themselves, for example int.Mod, double.Mod and so on. A similar case can be made for DateOnly.Mod and TimeOnly.Mod.

Risks

I don't see how adding a new method to the Math library or to individual numerical classes would pose any big risks. There is a slight concern for possible bugs because the modulo function would have to be implemented separately for each numerical type (and non-numerical types that would benefit from it), so a simple copy and paste won't cut it, unless the modulo function can be implemented generically somehow.

Author:	JansthcirlU
Assignees:	-
Labels:	api-suggestion, area-System.Numerics, untriaged
Milestone:	-

[aaronfranke]

I am in agreement with this API proposal except for a few things:

• The behavior should allow for wrapping into negatives when given a negative divisor value. For example, Mod(x, 3) can return 0, 1, or 2, while Mod(x, -3) should return 0, -1, or -2. This means the sign is dependent on the second argument, unlike the current behavior of the % operator where the sign is dependent on the first argument.
• There are optimization opportunities that the C# compiler should take into account that we should define. For example, with Mod(x, 16) where x is an integer, this can be optimized to a bitwise AND operation: x & 15.
• I really do think it would be much better as an operator. I know that there is resistance to this, however.

[JansthcirlU]

@aaronfranke

* The behavior should allow for wrapping into negatives when given a negative divisor value. For example, `Mod(x, 3)` can return 0, 1, or 2, while `Mod(x, -3)` should return 0, -1, or -2. This means the sign is dependent on the second argument, unlike the current behavior of the `%` operator where the sign is dependent on the first argument.

Hard disagree. The proposal is for a positive remainder for a reason. As for your other points, I leave that up to the people working in Numerics but if you have any extra implementation details that you want me to include in the alternatives section let me know.

[tannergooding]

There are optimization opportunities that the C# compiler should take into account that we should define. For example, with Mod(x, 16) where x is an integer, this can be optimized to a bitwise AND operation: x & 15.

The C# compiler couldn't and wouldn't optimize this without it being "built-in" to the language. Even if it was built-in, this is really more of a JIT optimization and should be dependent on what's best for the target platform.

[tannergooding]

---

Overall, I likewise thing this is a good API addition, but the API surface likely needs to be tweaked a bit.

Notably, we are introducing a new feature Generic Math which will involve exposing almost all of the API from Math and MathF on the relevant primitive types. So rather than Math.Max(x, y), you will be able to do int.Max(x, y) (or in a generic context; T.Max(x, y)), etc.

This actually brings the primitive types inline with how most other types in .NET expose their operations. We don't have things like BigIntegerMath, ComplexMath, VectorMath, TensorMath, RationalMath, DateTimeMath, etc. Most types (in the BCL and outside as well) expose these "static 'operator like' methods" on the actual type. So you have BigInteger.Max instead.

There are also versioning issues with exposing methods on Math (this is why we introduced MathF for float) and once a given set of types are supported, adding overloads for new types can be breaking. Due to this (and as from a previous API review), the APIs added to Math and MathF will likely be rare moving forward and new APIs will target the primitives by default.

As such, the API proposal should likely be updated to explicitly call these out as being added as Double.Mod, Single.Mod, and Half.Mod. If the intent is to also cover integer types, they should also explicitly call out and cover Byte, Int16, Int32, Int64, IntPtr, SByte, UInt16, UInt32, UInt64, and UIntPtr.

The name should also be spelled out. Mod itself isn't enough and can be confused between Modular, Modulo, Modulus, etc. Not everything is consistent on which one the term Mod means (and unfortunately the % operator is internally already called op_Modulus in IL).

[tannergooding]

However, I also want to call out that I think some of the motivating scenarios aren't, in my own opinion, realistic as described and while it does allow for a "simpler" algorithm (for some meaning of the word), many of the scenarios where its being raised as applicable wouldn't actually use the operation here.

The generic Mod implementation (like division and remainder) is a relatively "expensive" operation and while the JIT might be able to optimize certain scenarios (namely those involving constants), there are many real scenarios where it couldn't optimize. For cases like games where you may want screen wrapping behavior, its actually much simpler and more efficient to simply do a simple compare and replace/subtract/other operation.

Likewise, with concepts like rotation, normalization is not always appropriate nor is assuming that negative values are invalid. Consider for a moment a clock. The clock face has 12 numbers on it and each number is ~30 degrees apart. Because of this, rotation of a clock hand by 30 and rotation of -330 will both end up with the hand on the 1. However, these are not the same operations. Namely, rotation by 30 degrees will rotate the hand clockwise and so it will cross from twelve down to one and not pass any other numbers. While rotation by -330 degrees will cross from twelve, through 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, and then finish on 1. If you are doing any kind of animations, interpolation, or the like then these are very different and observing them part way through will show different results.

Even with time, while you may just want to know "it was 7", that's technically losing important information. Namely, that there is a transition here between AM and PM (and possibly even day) that is carried by the sign. This means that for the regular % operator, 0 means "no transition", positive means a forward transition, negative means a reverse transition. In the negative case you add to the upper bound (so 12 + (-5)) and in the positive case you add to the lower bound (0 + x). This gives you a correct result and preserves all the relevant information on if the AM/PM transition or a day transition occurred (particularly when used in conjunction with the regular division operation).

So while it is a generally useful operation and I do think its worth adding, we should ensure the use-cases and issues around it are clearly specified and are account for the practical cases where there is a better alternative or where the current % may be more desirable.

This issue has been marked needs-author-action since it may be missing important information. Please refer to our contribution guidelines for tips on how to report issues effectively.

[aaronfranke]

Likewise, with concepts like rotation, normalization is not always appropriate nor is assuming that negative values are invalid.

...which is why you would only use Mod (or %%) when you specifically don't want them.

Namely, that there is a transition here between AM and PM (and possibly even day) that is carried by the sign.
This means that for the regular % operator, 0 means "no transition", positive means a forward transition, negative means a reverse transition.

It's not. That information is not carried by the sign. (7 + 8) % 12 is 3 which transitions between AM/PM, and (7 + 2) % 12 is 9 which does not transition. Both outputs are positive but there is a different in whether there is a transition. Your claim of "0 means "no transition", positive means a forward transition" is just simply false.

[tannergooding]

Both outputs are positive but there is a different in whether there is a transition. Your claim of "0 means "no transition", positive means a forward transition" is just simply false.

You're right, I messed up the statement on the positive case. The negative case is still correct however and it is important information (and also often hardware accelerated/special-cased).