documentation issue

Torbjorn Granlund tg at swox.com
Wed Feb 27 17:19:19 CET 2008

Paul Zimmermann <Paul.Zimmermann at loria.fr> writes:

Hi,

the documentation of mpz_invert says:

-- Function: int mpz_invert (mpz_t ROP, mpz_t OP1, mpz_t OP2)
Compute the inverse of OP1 modulo OP2 and put the result in ROP.
If the inverse exists, the return value is non-zero and ROP will
satisfy 0 <= ROP < OP2.  If an inverse doesn't exist the return
^^^^^^^^
value is zero and ROP is undefined.

Unless I'm mistaken, if the inverse exists, ROP cannot be zero for |OP2| >= 2.

Unless I am also mistaken, you're right and the documentation does not
say differently.

One could change the text to "... satisfy 0 < ROP < OP2" and then
speak specifically about |OP2| = 1, but I am not sure such a longer
text would be an improvement.

Also, the behaviour should be specified for OP2 = 0 and |OP2| = 1.

Is something not working right for |OP2| = 1?  The documentation
doesn't mention it explicitly, but since its workding is right for
this case, I don't see any need.  (Just as OP2=4711 does not need
special wording...)

If one assumes that the inverse exists if there exists an integer B
such that ROP*OP1 + B*OP2 = 1, then:

That's a generalized definition, not the one I'd naturally would use.

(a) for OP2=0, only OP1=1 and OP1=-1 admit an inverse, which seems what the
implementation does;
(b) for OP2=1, then any integer ROP is an inverse, since one can take
B = 1 - ROP*OP1. But the return value seems to be always 0 in that case.

I am not sure from your message what changes you're suggesting.  Could