builtin functions for integer division and remainder division

[andrewrk]

let's define the modulus operator to be euclidean mod. here is some pre-written justification: https://eev.ee/blog/2016/12/01/lets-stop-copying-c/#negative-modulo

We can provide an implementation that achieves this regardless of what instructions are actually available on the system.

If a programmer wants to use a modulus that has undefined behavior for a negative operand, we can provide a builtin for that, and it can have a debug safety check.

[andrewrk]

Proposal:

• remove % binary operator
• add @rem(a, b) builtin function that does remainder division. This is equivalent to % in C (and status quo zig). This has debug safety features for division by zero and overflow. @rem(-5, 3) is -2.
• add @mod(a, b) builtin function that does euclidean modulus. This is equivalent to % in Python. @mod(-5, 3) is 1.

[thejoshwolfe]

@rem(a, b) should assert b > 0. In C, % with a negative denominator is undefined behavior (actually bounded, implementation-defined behavior).

Trying to think of any objections, I suppose I could point out that the name "rem" is somewhat ambiguous. In Batch, "rem" is short for "remark" and starts a single-line comment, but I really don't think we need to worry about that. I do think that out of context, "rem" is usually short for "remove" rather than "remainder", but perhaps the context would be enough to clarify the meaning of the Zig function.

I like the @mod(a, b) proposal, but it's actually not completely specified yet. Python's % is not euclidean modulo. wikipedia calls it "floored division", because the result has the same sign as the divisor. Euclidean modulo always has a positive result.

My hunch of what we should do is make @mod(a, b) also assert b > 0 to avoid all this confusion. Then the important difference between @rem and @mod is when a is negative. I believe I have never in my programming career wanted a negative divisor for a modulo operation, which is partly why I'm proposing this restriction.

So here's a completely specified definition of both functions:

• @rem(a, b): assert(b > 0). Return @sign(a) * @mod(@abs(a), b).
• @mod(a, b): assert(b > 0). Return an integer n such that (0 <= n) && (n < b) && (k * b + n == a) for some integer k.

(Mathematically, @rem is more complicated than @mod, but I believe @rem is easier to implement in hardware.)

Speaking of "some integer k", that's actually the result of floored division. Is the / operator defined as floored division or as C's truncate-toward-zero division? In my programming career, every single time I've wanted modulo with a negative a, I've also wanted floored division at the same time. Do we have a floored division builtin in Zig? As with euclidean modulo, it can be implemented in userspace with enough ifs, but it may be strange to include a builtin for @mod without the corresponding division operation.

[thejoshwolfe]

Here's a radical proposal: allow a / operator for division, but only for floats not integers (reminder that there's no automatic coercion between integers and floats), since float division works very similar to how it works in math, but integer division is more mathematically complicated.

For integer division, we add builtin functions for different variants:

• @divTrunc(-5, 3) == -1: this is llvm's sdiv (or udiv).
• @divFloor(-5, 3) == -2: a little more complicated to implement, but pairs nicely with @mod.
• @divExact(-6, 3) == -2: asserts there is no remainder. this is llvm's sdiv exact.

Negative divisor cases for division (as opposed to remainder) are pretty well defined by math. In all variants of integer division a/b == -a/-b && sign(a/b) == sign(a) * sign(b) (assuming assert(b != 0) and no overflow).

We could also do a @divCeil(5, 3) == 2, but I don't think that's necessary. I also looked into some round-to-nearest division ideas, but there are way too many ways to resolve .5 cases, so that's definitely not a good idea for a builtin function.

Here's my worksheet to make sure the above proposal is coherent:

• @divTrunc(-5, 3) == -1, @divTrunc(5, -3) == -1
• @divTrunc(5, 3) == 1, @divTrunc(-5, -3) == 1
• @divFloor(-5, 3) == -2, @divFloor(5, -3) == -2
• @divFloor(5, 3) == 1, @divFloor(-5, -3) == 1

Here's a userland implementation of @divFloor:

fn divFloor(a: i32, b: i32) -> i32 {
    %%divFloorOverflow(a, b)
}
fn divFloorOverflow(a: i32, b: i32) -> %i32 {
    assert(b != 0);
    if (b < 0) {
        // canonicalize the sign of the divisor
        return divFloorOverflow(
            // note that some "overflow" cases might actually be capable of returning mathematically correct results,
            // but it's easier for implementations to define division such that negation overflow cases are also overflow cases for the division.
            %return math.mulOverflow(a, -1),
            %return math.mulOverflow(b, -1),
        );
    }
    if (a >= 0) {
        // we've already checked for negative b, so overflow cannot happen here
        return @divTrunc(a, b);
    } else {
        return -@divTrunc(
            // see above comment about overflow
            %return math.addOverflow(
                %return math.mulOverflow(a, -1), b - 1),
            b,
        );
    }
}

Here are test cases that hit each of the %returns in the above code. These are all cases where the overflow could be considered "unfair", since there is a mathematically correct answer that the algorithm didn't figure out.

• @divFloor(-0x80000000, -2): overflow, even though 0x40000000 is mathematically correct.
• @divFloor(0, -0x80000000): overflow, even though 0 is mathematically correct.
• @divFloor(-0x40000001, 0x40000000): overflow, even though -0x80000000 is mathematically correct.
• @divFloor(-0x80000000, 1): overflow, even though -0x80000000 is mathematically correct.

[andrewrk]

This proposal goes nicely with the modulus/remainder proposal.

An alternate set of proposals:

• Keep % and / operators for integers. Have them be floored modulus and floored division, respectively, the idea being that this is what programmers want, almost every time.
• Add @rem and @divTrunc as described.

[thejoshwolfe]

Is it safe to claim (in a Zig user guide, for example) that @divTrunc and @rem have better performance than @divFloor and @mod? For reference, LLVM IR only has primitive functions for the former, not the latter. So as long as Zig is backed by LLVM, it seems like a pretty safe claim.

With that in mind, I'm not comfortable encouraging users to use slower functions when they might know that they don't need the negative cases at all. One happy coincidence of my proposal above is that all three functions have the same size name. This means Zig is not biasing programmers to use any of them over the others. As an additional bonus, when programmers find out that there's no / operator for integers, they'll discover all three division functions at once. This way Zig is encouraging users to know what they're doing instead of encouraging users to do what Zig thinks they should be doing.

It might be worth noting that for unsigned integers, @divTrunc and @divFloor are identical. I argue that this doesn't violate orthogonality though, because we want the functions to work when the integer type is generic, and we don't want generic functions to have to use a different function depending on the signedness of a caller-supplied type.

[andrewrk]

Is it safe to claim (in a Zig user guide, for example) that @divTrunc and @rem have better performance than @divFloor and @mod? For reference, LLVM IR only has primitive functions for the former, not the latter. So as long as Zig is backed by LLVM, it seems like a pretty safe claim.

I agree with your reasoning here, and I think this is a pretty good argument for accepting your proposal, where integer division is done via builtin functions, not the / operator.

[andrewrk]

One more thing: should we allow / for unsigned integers and positive number literals, since @divTrunc and @divFloor are identical?

[thejoshwolfe]

should we allow / for unsigned integers and positive number literals, since @divTrunc and @divFloor are identical?

More generally, we could allow / when @divTrunc and @divFloor would be identical, such as diving a slice.len by a @sizeOf.

But that actually leaves out @divExact. In the case of slice.len / @sizeOf(T), it seems like @divExact might be a better fit than @divTrunc. Do we even want to bother with @divExact? I only propose it because LLVM IR supports it, and it seems useful in some cases, but we can definitely do without it.

[andrewrk]

Fun fact, we already have @divExact and it works exactly as you proposed.