[Gmp-commit] /var/hg/gmp: doc/gmp.texi (Integer Internals): Lazy allocation a...

[mercurial at gmplib.org]

details:   /var/hg/gmp/rev/110bcd4c29f4
changeset: 17619:110bcd4c29f4
user:      Marco Bodrato <bodrato at mail.dm.unipi.it>
date:      Sun May 06 08:48:36 2018 +0200
description:
doc/gmp.texi (Integer Internals): Lazy allocation and read-only

diffstat:

 ChangeLog       |   2 ++
 doc/gmp.texi    |  16 ++++++++++------
 mini-gmp/README |   2 ++
 3 files changed, 14 insertions(+), 6 deletions(-)

diffs (63 lines):

diff -r 85eda8a9f6e2 -r 110bcd4c29f4 ChangeLog
--- a/ChangeLog	Fri May 04 21:43:34 2018 +0200
+++ b/ChangeLog	Sun May 06 08:48:36 2018 +0200
@@ -3,6 +3,8 @@
 	* doc/gmp.texi (mpq_*_str): Document the full base allowed range.
 	* mpq/get_str.c: Make all bases either work or return an error.
 
+	* doc/gmp.texi (Integer Internals): Lazy allocation and read-only.
+
 2018-04-27  Niels Möller  <nisse at lysator.liu.se>
 
 	* mpn/generic/div_q.c (mpn_div_q): Replace dead code with ASSERT.
diff -r 85eda8a9f6e2 -r 110bcd4c29f4 doc/gmp.texi
--- a/doc/gmp.texi	Fri May 04 21:43:34 2018 +0200
+++ b/doc/gmp.texi	Sun May 06 08:48:36 2018 +0200
@@ -10155,7 +10155,7 @@
 @item @code{_mp_size}
 The number of limbs, or the negative of that when representing a negative
 integer.  Zero is represented by @code{_mp_size} set to zero, in which case
-the @code{_mp_d} data is unused.
+the @code{_mp_d} data is undefined.
 
 @item @code{_mp_d}
 A pointer to an array of limbs which is the magnitude.  These are stored
@@ -10164,17 +10164,21 @@
 significant.  Whenever @code{_mp_size} is non-zero, the most significant limb
 is non-zero.
 
-Currently there's always at least one limb allocated, so for instance
- at code{mpz_set_ui} never needs to reallocate, and @code{mpz_get_ui} can fetch
- at code{_mp_d[0]} unconditionally (though its value is then only wanted if
- at code{_mp_size} is non-zero).
+Currently there's always at least one readable limb, so for instance
+ at code{mpz_get_ui} can fetch @code{_mp_d[0]} unconditionally (though its value
+is undefined if @code{_mp_size} is zero).
 
 @item @code{_mp_alloc}
 @code{_mp_alloc} is the number of limbs currently allocated at @code{_mp_d},
-and naturally @code{_mp_alloc >= ABS(_mp_size)}.  When an @code{mpz} routine
+and normally @code{_mp_alloc >= ABS(_mp_size)}.  When an @code{mpz} routine
 is about to (or might be about to) increase @code{_mp_size}, it checks
 @code{_mp_alloc} to see whether there's enough space, and reallocates if not.
 @code{MPZ_REALLOC} is generally used for this.
+
+ at code{mpz_t} variables initialised with the @code{mpz_roinit_n} function or
+the @code{MPZ_ROINIT_N} macro have @code{_mp_alloc = 0} but can have a
+non-zero @code{_mp_size}.  They can only be used as read-only constants. See
+ at ref{Integer Special Functions} for details.
 @end table
 
 The various bitwise logical functions like @code{mpz_and} behave as if
diff -r 85eda8a9f6e2 -r 110bcd4c29f4 mini-gmp/README
--- a/mini-gmp/README	Fri May 04 21:43:34 2018 +0200
+++ b/mini-gmp/README	Sun May 06 08:48:36 2018 +0200
@@ -50,6 +50,8 @@
   allocated block in the corresponding argument. mini-gmp always
   passes zero for these rarely used arguments.
 
+  When mpz_get_str allocates the block, it can be longer than needed.
+
 The performance target for mini-gmp is to be at most 10 times slower
 than the real GMP library, for numbers of size up to a few hundred
 bits. No asymptotically fast algorithms are included in mini-gmp, so