VB: Modulus operator should be referred to as Remainder

[BillWagner]

See #4860

The operator referred to as "modulus" performs a "remainder" operation. There are subtle differences, primarily with negative numbers.

As pointed out in the PR, the Mod operator name complicates this. (Similarly op_Modulus in IL complicates the explanation as well.

[KathleenDollard]

For reference: Eric Lippert explains modulus vs remainder

I believe the word "modulus" in common usage is remainder, and the conversations I found regarding it's use in the sense Eric uses it is all around congruence, and this is an arithmetic operator.

Overall the VB page does a great job explaining what the operator does, with minimum use of the word modulus. I would leave the text as is, but add the note below.

NOTE: There is a difference between "remainder" and "modulus" in mathematics, with different results for negative numbers. The MOD operator in Visual Basic, and the underlying op_Modulus IL instruction are remainder operations. The result of -123 MOD 30 is 3 and -123 MOD 4 is -30.

[aaronfranke]

@KathleenDollard I would use smaller numbers for a more clear example:

The result of 7 MOD 3 is 1 and -7 MOD 3 is -1 (as opposed to 2).

For reference, here's the new C# definition, adjusted* for VB, with % replaced with MOD:

The formula a MOD b will always return a value on the range (-b, b), exclusive (it can never return b or -b), keeping the sign of the dividend. For integer division, the remainder operator MOD satisfies the rule a MOD b = a - (a / b) * b.

This is not to be confused with canonical modulus, which satisfies a similar rule but with floored division and returns values on the range [0, b). VB does not have an operator for canonical modulus. However, the behavior is the same for positive dividends.

* I don't know VB, so there may be syntax errors here...

[KathleenDollard]

I'm fine with the smaller number.

I think saying '(as opposed to 2)' or anything similar is just confusing and I would prefer not to put the two C# paragraphs in. I don't feel they add anything. I think we are just muddying the water talking about something most people will never need to know about.

We could say '"canonical modulus" in mathematics' to further distinguish that it's not what we are talking about.

I find those C# paragraphs very confusing. Everyone knows what "remainder" means and that is all that is mentioned in the documentation for the other languages I just looked up.

[aaronfranke]

In hindsight, it might also be a good idea to add the word Rem as an alias for VB's Mod operator. Not only to match the functionality and docs, but there's also the Math.DivRem method referenced here. It'd also somewhat match Math.IEEERemainder (which could be given a shorter name some day).

[KathleenDollard]

Rem is a Visual Basic keyword for a comment. It is rarely used as the apostrophe is much more common. Rem follows the script/DOS meaning of the word.

If there is a place that the functionality and docs still don't match on this, please let us know.