documentation on internals not up to date

[Niels Möller]

"Marco Bodrato" <bodrato at mail.dm.unipi.it> writes:

> What about the following?
>
> Currently there's always at least one readable limb, so for instance
> @code{mpz_get_ui} can fetch @code{_mp_d[0]} unconditionally (though its
> value is then only wanted if @code{_mp_size} is non-zero).

Maybe change "is only wanted if" to "is valid only if" or "is usable
only if". At some point, I suffered the misunderstanding that _mp_size
== 0 implies _mp_d[0] == 0, which isn't right.

> @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)}.
>
> This is not "naturally" true since GMP 6.0, when mpz_roinit_n was added to
> the interface.
>
> Shouldn't we mention that "read-only" values are possible, when
> @code{_mp_alloc} is zero, but @code{_mp_size} is not.

Since this is the section on internals, I think it's appropriate to
document. _mp_alloc == 0 and _mp_size == 0 means that value is zero, and
writable. Writing a new value is valid, and mpz functions will
automatically allocate storage. This is the initial state after
mpz_init.

_mp_alloc == 0 and _mp_size != 0 is a read-only value, _mp_d is neither
written, reallocated or freed by mpz functions. It must not be passed as
destination argument to any mpz function. Should also link to docs for
mpz_roinit_n and MPZ_ROINIT_N.

Regards,
/Niels

-- 
Niels Möller. PGP-encrypted email is preferred. Keyid 368C6677.
Internet email is subject to wholesale government surveillance.