documentation issue

[Torbjorn Granlund]

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
you please be more specific?

-- 
Torbjörn