_ptr and _srcptr types

[Emmanuel Thomé]

On Sat, May 26, 2018 at 09:54:37AM +0200, Niels Möller wrote:
> I think I'd like to add something like
> 
>   When an array is used as a function argument in C, it is not passed by
>   value, instead its value is a pointer to the first element. In C
>   jargon, this is sometimes referred to as the array "decaying" to a
>   pointer. For GMP types like mpz_t, that means that the function called
>   gets a pointer to the caller's mpz_t value, which is why no explicit &
>   operator is needed when passing output arguments. [this is related to
>   the section Parameter Conventions]
>   
>   GMP defines names for these pointer types, e.g., mpz_ptr corresponding
>   to mpz_t, and mpz_srcptr corresponding to const mpz_t. Most functions
>   don't need to use these pointer types directly; it works fine to
>   declare a function using the mpz_t or const mpz_t as the argument
>   types, the same "pointer decay" happens in the background regardless.
> 
>   Occasionally, it is useful to manipulate pointers directly, e.g, to
>   conditionally swap *references* to a function's inputs without
>   changing the *values* as seen by the caller, or returning a pointer to
>   an mpz_t which is part of a larger structure. For these cases, the
>   pointer types are necessary. And a mpz_ptr can be passed as argument
>   to any GMP function declared to take an mpz_t argument.

I wondered indeed whether such an explanation is needed. One may consider
that it's not the purpose of the Fine Manual to teach the user about C. I
like your suggested text, though. (typo: "a mpz_ptr" -> "an mpz_ptr").

> > +equivalent to the following code, which is given for illustratory
> > +purposes only:
> > +
> > + at example
> > +    typedef some_internal_data_type mpz_t[1];
> > +    typedef some_internal_data_type * mpz_ptr;
> > +    typedef const some_internal_data_type * mpz_srcptr;
> > + at end example
> 
> I think it's confusing with a made-up name for the internal types, but
> actual names for types defined. I'd prefer to either use the actual
> internal name __mpz_struct instead of some_internal_data_type above, or
> change to the obviously made up name foo consistently, like
> 
>     typedef foo_internal foo_t[1];
>     typedef foo_internal * foo_ptr;
>     typedef const foo_internal * foo_srcptr;

Yes, it's much better (and I have a strong preference for the latter).

E.