[Gmp-commit] /var/hg/gmp: 2 new changesets

[mercurial at gmplib.org]

details:   /var/hg/gmp/rev/f872528a9d00
changeset: 15505:f872528a9d00
user:      Niels M?ller <nisse at lysator.liu.se>
date:      Sun Mar 03 15:26:50 2013 +0100
description:
Add normalization to mpz_init_ro.

details:   /var/hg/gmp/rev/cda2b93f3576
changeset: 15506:cda2b93f3576
user:      Niels M?ller <nisse at lysator.liu.se>
date:      Sun Mar 03 15:28:53 2013 +0100
description:
Document mpz_limbs_read and friends.

diffstat:

 ChangeLog      |   8 ++++++
 doc/gmp.texi   |  75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 mpz/roinit_n.c |   5 +++-
 3 files changed, 86 insertions(+), 2 deletions(-)

diffs (116 lines):

diff -r af4ce4cd36a9 -r cda2b93f3576 ChangeLog
--- a/ChangeLog	Thu Feb 28 13:51:37 2013 +0100
+++ b/ChangeLog	Sun Mar 03 15:28:53 2013 +0100
@@ -1,3 +1,11 @@
+2013-03-03  Niels Möller  <nisse at lysator.liu.se>
+
+	* doc/gmp.texi (Integer Special Functions): Document
+	mpz_limbs_read, mpz_limbs_write, mpz_limbs_modify,
+	mpz_limbs_finish, mpz_roinit_n and MPZ_ROINIT_N.
+
+	* mpz/roinit_n.c (mpz_roinit_n): Normalize the input.
+
 2013-02-27  Niels Möller  <nisse at lysator.liu.se>
 
 	* tune/common.c (speed_measure): Increase repetition count if we
diff -r af4ce4cd36a9 -r cda2b93f3576 doc/gmp.texi
--- a/doc/gmp.texi	Thu Feb 28 13:51:37 2013 +0100
+++ b/doc/gmp.texi	Sun Mar 03 15:28:53 2013 +0100
@@ -4168,7 +4168,80 @@
 @c (@xref{Nomenclature}, for an explanation of the concept @dfn{limb}.)
 @end deftypefun
 
-
+ at deftypefun {const mp_limb_t *} mpz_limbs_read (const mpz_t @var{x})
+Return a pointer to the limb array representing the absolute value of @var{x}.
+The size of the array is @code{mpz_size(@var{x})}. Intended for read access
+only.
+ at end deftypefun
+
+ at deftypefun {mp_limb_t *} mpz_limbs_write (mpz_t @var{x}, mp_size_t @var{n})
+ at deftypefunx {mp_limb_t *} mpz_limbs_modify (mpz_t @var{x}, mp_size_t @var{n})
+Return a pointer to the limb array, intended for write access. The array is
+reallocated as needed, to make room for @var{n} limbs. Requires @math{@var{n}
+> 0}. The @code{mpz_limbs_modify} function returns an array that holds the old
+absolute value of @var{x}, while @code{mpz_limbs_write} may destroy the old
+value and return an array with unspecified contents.
+ at end deftypefun
+
+ at deftypefun void mpz_limbs_finish (mpz_t @var{x}, mp_size_t @var{s})
+Updates the internal size field of @var{x}. Used after writing to the limb
+array pointer returned by @code{mpz_limbs_write} or @code{mpz_limbs_modify} is
+completed. The array should contain @math{@GMPabs{@var{s}}} valid limbs,
+representing the new absolute value for @var{x}, and the sign of @var{x} is
+taken from the sign of @var{s}. This function never reallocates @var{x}, so
+the limb pointer remains valid.
+ at end deftypefun
+
+ at c FIXME: Some more useful and less silly example?
+ at example
+void foo (mpz_t x)
+@{
+  mp_size_t n, i;
+  mp_limb_t *xp;
+  
+  n = mpz_size (x);
+  xp = mpz_limbs_modify(x, 2*nn);
+  for (i = 0; i < n; i++)
+    xp[n+i] = xp[n-1-i];
+  mpz_limbs_finish (x, mpz_sgn (x) < 0 ? - 2*n : 2*n);
+@}
+ at end example
+
+ at deftypefun mpz_srcptr mpz_roinit_n (mpz_t @var{x}, const mp_limb_t *@var{xp}, mp_size_t @var{xs})
+Special initialization of @var{x}, using the given limb array and size.
+ at var{x} should be treated as read-only: it can be passed safely as input to
+any mpz function, but not as an output. The size of the array is
+ at math{@GMPabs{@var{xs}}}, and the sign of @var{x} is the sign of @var{s}. For
+convenience, the function returns @var{x}, but cast to a const pointer type.
+ at end deftypefun
+
+ at example
+void foo (mpz_t x)
+@{
+  static const mp_limb_t y[3] = @{ 0x1, 0x2, 0x3 @};
+  mpz_t tmp;
+  mpz_add (x, x, mpz_roinit_n (tmp, y, 3));
+@}
+ at end example
+
+ at deftypefn Macro mpz_t MPZ_ROINIT_N (mp_limb_t *@var{xp}, mp_size_t @var{xs})
+This macro expands to an initializer which can be assigned to an mpz_t
+variable. Unlike the @code{mpz_roinit_n} function, the limb array must be
+normalized: if @var{xs} is non-zero, then
+ at code{@var{xp}[@math{@GMPabs{@var{xs}}-1}]} must be non-zero. Intended
+primarily for constant values. Using it for non-constant values requires a C
+compiler supporting C99.
+ at end deftypefn
+
+ at example
+void foo (mpz_t x)
+@{
+  static const mp_limb_t ya[3] = @{ 0x1, 0x2, 0x3 @};
+  static const mpz_t y = MPZ_ROINIT_N ((mp_limb_t *) ya, 3);
+
+  mpz_add (x, x, y);
+@}
+ at end example
 
 @node Rational Number Functions, Floating-point Functions, Integer Functions, Top
 @comment  node-name,  next,  previous,  up
diff -r af4ce4cd36a9 -r cda2b93f3576 mpz/roinit_n.c
--- a/mpz/roinit_n.c	Thu Feb 28 13:51:37 2013 +0100
+++ b/mpz/roinit_n.c	Sun Mar 03 15:28:53 2013 +0100
@@ -23,8 +23,11 @@
 mpz_srcptr
 mpz_roinit_n (mpz_ptr x, mp_srcptr xp, mp_size_t xs)
 {
+  mp_size_t xn = ABS(xs);
+  MPN_NORMALIZE (xp, xn);
+
   ALLOC (x) = 0;
-  SIZ (x) = xs;
+  SIZ (x) = xs < 0 ? -xn : xn;
   PTR (x) = (mp_ptr) xp;
   return x;
 }