Deconfuse `%` and `mod` behaviours

[librasteve]

It has been noted that the Raku general modulo operator % and integer modulo operator mod do some unanticipated things.

For example:

Welcome to Rakudo™ v2025.08.

-pi % 1;          #0.8584073464102069
-pi mod 1;        #-0.14159265358979312

#EDIT - I had these results the wrong way round first time - sorry

and

-7.7 % 1.9;       #1.8
-7.7 mod 1.9;     #5.6

for %

the docs say:

multi infix:<%>($x, $y --> Numeric:D)
Modulo operator. Coerces to Numeric first.
Generally the following identity holds:
my ($x, $y) = 1,2;
$x % $y == $x - floor($x / $y) * $y

and Synopsis S03 says:

infix:<%>, modulo

$x % $y
If necessary, coerces non-numeric arguments to an appropriate Numeric type, then calculates the remainder, which is defined as:

$x % $y == $x - floor($x / $y) * $y
If both operands are Ints, the operator returns an Int.

If both operands are of integer or rational type, the operator returns the corresponding Rat value (except when the result does not fit into a Rat, as detailed in S02).

for mod

docs

multi infix:<mod>(Int:D $a, Int:D $b --> Int:D)
Integer modulo operator. Returns the remainder of an integer modulo operation.

S03

infix:<mod>, integer modulo

$x mod $y
Dispatches to the infix:<mod> multi most appropriate to the operand types, returning a value of the same type. Not coercive, so fails on differing types.

This should preserve the identity

$x mod $y == $x - ($x div $y) * $y

so this raises some questions:

• are these two operators well specified?
• does the current Rakudo compiler (v6) implement the specification correctly?
• do the specifications hold water?
• should we consider changing the behaviour (eg in 6.e)?
• do we need to improve ROAST?
• do we need to improve the docs?

I encourage everyone to share their views on these points, mine follow below:

[lizmat]

FWIW, I think the current behaviour of infix:<mod> is incorrect.

It got changed with rakudo/rakudo@71c0151 it seems. And was not caught by spectests.

[librasteve]

Here are my initial answers:

are these two operators well specified?

yes, we may not like it, but S03 is unambiguous

does the current Rakudo compiler (v6) implement the specification correctly?

yes, the source follows the spec

do the specifications hold water?

according to https://en.wikipedia.org/wiki/Modulo:

• there are 3 variants of modulo: truncated, floored and rounded
• C does truncated (Integer) and rounded (Floating-point)
• perl does floored (Integer, %) and truncated (Floating-point POSIX::fmod) [1]

[I believe that the Raku line in the table is incorrect and we should fix wikipedia depending on the outcome of this issue]

in the light of this, my opinion that currently Raku does this:

• % properly follows the floored option
• mod is a (potentially flawed) variant of the floored option

the potential flaw is that, as specified and implemented, the operation $x div $y will coerce $x and $y to Int and, in so doing will truncate eg. pi => 3, 7.7 => 7, 1.9 => 1 and so on ... so feeding non Int operands into mod will trigger this behaviour and often the result of % will differ from mod unexpectedly

apparently Knuth takes a view on this in 'The Art of Computer Programming',

Warning About Inconsistent Computer Implementations
Knuth explicitly warns that many computer languages historically do not follow his convention, leading to:

• Negative remainders
• Inconsistent definitions between division and modulo
  He calls this “a deplorable situation,” emphasizing that any division algorithm should maintain:
  0≤r<∣b∣
  and
  q=⌊a/b⌋

the current Raku implementation of div and mod follow this guidance literally
[imo there is a case that this is done too literally for non Int operands]

so, yes, it can be argued that the specs hold water

should we consider changing the behaviour (eg in 6.e)?

regardless of whether the consensus is that the spec is wrong, we should bear in mind that this would be a breaking change

I would say that requiring the operands of mod to be Int would be an improvement in expectation management and would guard against unintended bugs, then the coder can decide to coerce/truncate as the args are presented to the operation

on balance I think that the breaking change aspect should "win" and we should not make this change

do we need to improve ROAST?

could argue that this is an implementation detail of the compiler, not sure

do we need to improve the docs?

strong yes, we should add this S03 definition to the mod operator section and warn that for non Int operands (i) it may produce unexpected results and that (ii) % and mod results may differ.

comments - feedback welcome!!

[librasteve]

@lizmat - yeees, well according to the literal interpretation I would say that

mod uses div uses .Int correctly - the culprit is that .Int truncates a non Int, would you change that? ;-)

[lizmat]

I think truncating would be the correct thing indeed.

[arkiuat]

should we consider changing the behaviour (eg in 6.e)?

regardless of whether the consensus is that the spec is wrong, we should bear in mind that this would be a breaking change

I'm not sure I understand. Wasn't rakudo/rakudo@71c0151, which only came in with 2024.02, a breaking change of older established behavior? Has the bug been around long enough that we have to consider fixing the bug a breaking change?

I would say that requiring the operands of mod to be Int would be an improvement in expectation management and would guard against unintended bugs, then the coder can decide to coerce/truncate as the args are presented to the operation

on balance I think that the breaking change aspect should "win" and we should not make this change

Okay, this would be a breaking change (although probably a good idea, with the usual advance warnings given), but I thought above you were just referring to returning to the pre-2024.02 behavior.

do we need to improve ROAST?

could argue that this is an implementation detail of the compiler, not sure

Seems like it would have been good if the ROAST tests had been detailed enough to prevent the problem being introduced in 2024.02.

do we need to improve the docs?

strong yes, we should add this S03 definition to the mod operator section and warn that for non Int operands (i) it may produce unexpected results and that (ii) % and mod results may differ.

It does seem like a good idea to add a warning to the docs about different behavior inadvertently introduced from 2024.02 onwards, but I'd want to understand more about the exact behavior of these two operators before 2024.02 and how the current behavior differs from the old before I would want to try to write that warning.

As for inserting S03 definitions (that aren't there already) into the docs, I'd want to wait for the outcome of further discussion before doing that. There might be good reasons why the S03 definitions aren't already in the docs.

[librasteve]

Redoing the examples on Rakudo prior to the function change.

Welcome to Rakudo™ v2024.01.

-pi % 1;          #0.8584073464102069 (**same**)
-pi mod 1;        #Cannot resolve caller infix:<div>(Num:D, Int:D); none of these signatures matches:
    (Int:D $a, Int:D $b --> Int:D)
    (int $a, int $b --> int)
    (uint $a, uint $b --> uint)

and

-7.7 % 1.9;       #1.8 (**same**)
-7.7 mod 1.9;     #Cannot resolve caller infix:<div>(Rat:D, Rat:D); none of these signatures matches:
    (Int:D $a, Int:D $b --> Int:D)
    (int $a, int $b --> int)
    (uint $a, uint $b --> uint)

[librasteve]

Following the trial from the change mentioned by @arkuiat above rakudo/rakudo@71c0151, there are two other relevant discussions:

• div and mod don't convert to Int, unlike everything else #326, and thence
• https://stackoverflow.com/questions/71067633/whats-the-point-of-rakus-mod-operator/71072660?answertab=createdasc#tab-top

I note with humiliation that my reply on SO was wrong (since Raku is not doing IEEE P754 rounded modulo, but rather floored modulo) and I note with a wry smile that my comment on the Issue #326 was spot on in that Raku should reject rather than coerce ;-) [although I had forgotten I ever write that]

Looking at the relevant commit, I note that the prior version rejects on both mod and div (but that the mod function "delegates" this to the div that it calls)

I propose that we back out the change and alter this line as follows to make the reject of non Int more explicit.

multi sub infix:<mod>(Real:D $a, Real:D $b) { $a - ($a div $b) * $b }

multi sub infix:<mod>(Int:D $a, Int:D $b) { $a - ($a div $b) * $b }

[arkiuat]

I think truncating would be the correct thing indeed.

Just to check my understanding here (it's pretty clear in the context @librasteve provided, but just making sure):

You're saying that the correct infix:<mod> for Raku would be { $^a - $^b * ($^a div $^b).Int } , right?

I know the .Int is redundant there if we assume that infix:<div> is defined as { ($^a/$^b).Int } but there are three different alt-definitions of div corresponding to each of the alt-mods, using .floor or .round(1) --if .round(1) "rounds toward even", which it doesn't-- or that Euclidean contraption with .sign and .abs. It seems that the current post-2024.02 raku does one of the .floored variants, as @librasteve has pointed out.)

Also stating explicitly that .Int here is equivalent to .truncate, which maybe we should be using instead in discussions of this kind. Sorry, it's just that all of this is confusing for me, and spelling things out like this helps: I hope it may help others.

Just as an aside, it kind of bugs me that no one seems sure of why Raku even has two separate operators, infix:<mod> and infix:<%>; if there were consensus on the rationale for having two distinct operators, we probably couldn't have gotten into this mess in the first place. Based on what @raiph has posted elsewhere, it seems to be based on a decision @TimToady made at some point but never thoroughly explained the rationale for. Maybe we can ask Audrey?

Also thanks to @librasteve for pointing out the edit that someone will need to make to that Wikipedia article once this gets resolved.