Hi,
The mpz_ptr, mpz_srcptr types, and their many friends, are exposed in
gmp.h, but never seen in the documentation. (unless I'm mistaken.)
Well, almost:
~/gmp $ grep 'mp[a-z]*_[a-z]*ptr' doc/gmp.texi
@deftypefun mpz_srcptr mpz_roinit_n (mpz_t @var{x}, const mp_limb_t *@var{xp},
mp_size_t @var{xs})
(which leaves the reader a but puzzled, as mpz_srcptr is really unheard
of in the doc).
I've personally always used the mpz_ptr and mpz_srcptr in functions that
take mpz arguments, taking the liberty to use this undocumented type.
I vaguely remember that at some point I had a compelling argument for
doing so, like "it's much better for constness", but I'm not so sure now.
Maybe it's just a matter of taste.
A few random thoughts on this. Admittedly, none qualifies as compelling.
- sizeof() of mpz_t arguments would be misleading as it's really the
size of the pointer.
- the gmp.h prototypes are written with mpz_ptr and mpz_srcptr
anyway.
- a custom C++ wrapper type may define an automatic cast to mpz_ptr
and mpz_srcptr, but certainly not to mpz_t.
May I suggest one or several of the following things be done ?
- document the mpz_srcptr type somewhere, so that the documentation is
self-contained.
- document all the mp*_*ptr types
- also define and expose gmp_randstate_{src,}ptr, which are currently
missing.
- (most probably too extreme): document prototypes as they're actually
exposed, that is with mpX_ptr arguments rather than mpX_t.
If the first items are agreed upon, the main question would be "where
should the _ptr types be documented ?". Under "3.5 Parameter
Conventions" maybe ? I might suggest a wording if needed.
Cheers,
E.
_______________________________________________
gmp-devel mailing list
gmp-devel@gmplib.org
https://gmplib.org/mailman/listinfo/gmp-devel
