PATCH: document pointer types

[John Tobey]

gmp.h contains the following comment above the definitions of mpz_ptr,
mpq_ptr, mpf_ptr, and the corresponding srcptr types:

/* Types for function declarations in gmp files.  */
/* ??? Should not pollute user name space with these ??? */

I consider the types useful enough to document publicly, so I've
attached a patch that does so.  The patch also defines
gmp_randstate_ptr and gmp_randstate_srcptr by analogy to the other
definitions.  The patch does not document the const "srcptr" variants,
but I will be happy to add them (and test the patch) if this gets a
positive response.

Thanks.
-John
-------------- next part --------------
diff -r 692bc6eee88d doc/gmp.texi
--- a/doc/gmp.texi	Thu Apr 19 11:29:36 2012 +0200
+++ b/doc/gmp.texi	Thu Apr 19 10:17:41 2012 -0400
@@ -1936,6 +1936,36 @@
 gmp_randstate_t rstate;
 @end example
 
+ at cindex Argument type
+Each of the types @code{mpz_t}, @code{mpq_t}, @code{mpf_t}, and
+ at code{gmp_randstate_t} is implemented as an array of one element.  (The
+semantics of functions such as @code{mpz_init} implies this.)  When code
+passes a value of such a type to a function, the function actually receives a
+pointer, not a copy of the element.  This presents a problem for code that
+wants to store a function argument in a variable.  As a solution, GMP provides
+an @dfn{argument type}, named by replacing the suffix @code{_t} with
+ at code{_ptr}, corresponding to each array type.
+
+ at tindex @code{mpz_ptr}
+Argument type corresponding to @code{mpz_t}
+
+ at tindex @code{mpq_ptr}
+Argument type corresponding to @code{mpq_t}
+
+ at tindex @code{mpf_ptr}
+Argument type corresponding to @code{mpf_t}
+
+ at tindex @code{gmp_randstate_ptr}
+Argument type corresponding to @code{gmp_randstate_t}
+
+ at example
+void f(mpz_t a) {
+    mpz_t   b = a;   /* error, invalid assigment */
+    mpz_ptr c = a;   /* ok */
+    mpz_neg (c, c);  /* usable with functions taking mpz_t */
+}
+ at end example
+
 Also, in general @code{mp_bitcnt_t} is used for bit counts and ranges, and
 @code{size_t} is used for byte or character counts.
 
diff -r 692bc6eee88d gmp-h.in
--- a/gmp-h.in	Thu Apr 19 11:29:36 2012 +0200
+++ b/gmp-h.in	Thu Apr 19 10:17:41 2012 -0400
@@ -218,14 +218,15 @@
 } __gmp_randstate_struct;
 typedef __gmp_randstate_struct gmp_randstate_t[1];
 
-/* Types for function declarations in gmp files.  */
-/* ??? Should not pollute user name space with these ??? */
+/* Argument types.  */
 typedef const __mpz_struct *mpz_srcptr;
 typedef __mpz_struct *mpz_ptr;
 typedef const __mpf_struct *mpf_srcptr;
 typedef __mpf_struct *mpf_ptr;
 typedef const __mpq_struct *mpq_srcptr;
 typedef __mpq_struct *mpq_ptr;
+typedef const __gmp_randstate_struct *gmp_randstate_srcptr;
+typedef __gmp_randstate_struct *gmp_randstate_ptr;
 
 
 /* This is not wanted in mp.h, so put it outside the __GNU_MP__ common