Extending the mpn interface

[Niels Möller]

nisse at lysator.liu.se (Niels Möller) writes:

> But I miss some features in the public interface to do this
> conveniently; both for mpn <-> mpz interoperation, and there are also
> some mpn functions which would be very useful but which are not part of
> the public interface.

I and Torbjörn had a little offline meeting after lunch today. Some
conclusions:

1. We should add a minimal mpz/mpn interface.

2. We drop the _ from names.

3. We should be a bit more liberal in making mpn functions public.

Below is a revised draft interface. Comments appreciated. I think I'll
try to get this in fairly soon.

I also plan to make additional mpn functions public when I need them,
also with some advance warning to this list.

PS. About use of mpz_t internals in gmp-h.in: I see a couple of uses of
_mp_size, but *no* direct use of _mp_alloc.

Regards,
/Niels

/* Second revision of a minimal mpz/mpn interface. Question: Should we
   use real functions, inline functions, or macros? */

/* Read access to mpz numbers. */

/* Return limb pointer, for read-only operations. Use mpz_size to get
   the number of limbs. */
const mp_limb_t *
mpz_read_limbs (const mpz_srcptr x);

/* Write access to mpz numbers. */

/* Get a limb pointer for writing, previous contents may be destroyed.
   Grows allocation if needed to make room for n limbs. */
mp_limb_t *
mpz_write_limbs (mpz_ptr x, mp_size_t n);

/* Get a limb pointer for writing, previous contents is intact.
   Grows allocation if needed to make room for n limbs. */
mp_limb_t *
mpz_modify_limbs (mpz_ptr x, mp_size_t n);

/* Adjusts the size after writing, to make x properly normalized. n <
   0 means negative. Should have abs(n) <= the argument for the
   preceding mpz_write_limbs or mpz_modify_limbs. Never reallocates x,
   so the pointer from the earlier mpz_write_limbs/mpz_modify_limbs
   remains valid. */
void
mpz_finish_limbs (mpz_ptr x, mp_size_t n);

/* Using an mpn number as an mpz. Can be used for read-only access
   only. x must not be cleared or reallocated. Here and below, xs
   stands for a signed parameter, where abs(xs) is the size, and xs <
   0 indicates a negative number. Returns x, cast to const, so it can
   be used directly as an argument for other mpz functions. */
mpz_srcptr
mpz_init_mpn (mpz_ptr x, const mp_limb_t *xp, mp_size_t xs);

/* Intializer for an mpz_t, having the same effect as calling
   mpz_init_mpn, but without a function call. It can be used to
   initialize variables which are statically allocated and/or const.
   xp would usually be a const mp_limb_t *, but unfortunately, it must
   then be cast to (mp_limb_t *) for use with this macro. */
#define MPZ_MPN_INITIALIZER(xp, xs) { { 0, (xs), (xp) } }



/* Some convenience functions, which we might want to add later. */

/* Copy x, which must be at most xn limbs, to the {xp, xn} area,
   zero-padding if needed. Not sure what to do if x is too large to
   fit, or if x < 0. */
void
mpz_get_mpn (mp_limb_t *xp, mp_size_t xn, const mpz_t x);

/* Assigns x from the area {xp, abs(xs)}. */
void
mpz_set_mpn (mpz_t x, const mp_limb_t *xp, mp_size_t xs);

/* Compares an mpz value to an mpn value. */
int
mpz_cmp_mpn (const mpz_t x, const mp_limb_t *yp, mp_size_t ys);

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