Home | History | Annotate | Line # | Download | only in perl
      1 # GMP perl module
      2 
      3 # Copyright 2001-2004 Free Software Foundation, Inc.
      4 #
      5 #  This file is part of the GNU MP Library.
      6 #
      7 #  The GNU MP Library is free software; you can redistribute it and/or modify
      8 #  it under the terms of either:
      9 #
     10 #    * the GNU Lesser General Public License as published by the Free
     11 #      Software Foundation; either version 3 of the License, or (at your
     12 #      option) any later version.
     13 #
     14 #  or
     15 #
     16 #    * the GNU General Public License as published by the Free Software
     17 #      Foundation; either version 2 of the License, or (at your option) any
     18 #      later version.
     19 #
     20 #  or both in parallel, as here.
     21 #
     22 #  The GNU MP Library is distributed in the hope that it will be useful, but
     23 #  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
     24 #  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
     25 #  for more details.
     26 #
     27 #  You should have received copies of the GNU General Public License and the
     28 #  GNU Lesser General Public License along with the GNU MP Library.  If not,
     29 #  see https://www.gnu.org/licenses/.
     30 
     31 # [Note: The above copyright notice is repeated in the documentation section
     32 # below, in order to get it into man pages etc generated by the various pod
     33 # conversions.  When changing, be sure to update below too.]
     34 
     35 
     36 # This code is designed to work with perl 5.005, so it and the sub-packages
     37 # aren't as modern as they could be.
     38 
     39 package GMP;
     40 
     41 require Symbol;
     42 require Exporter;
     43 require DynaLoader;
     44 @ISA = qw(Exporter DynaLoader);
     45 
     46 @EXPORT = qw();
     47 @EXPORT_OK = qw(version);
     48 %EXPORT_TAGS = ('all' => [qw(
     49                              get_d get_d_2exp get_si get_str integer_p
     50                              printf sgn sprintf)],
     51 		'constants' => [()]);
     52 Exporter::export_ok_tags('all');
     53 
     54 $VERSION = '2.00';
     55 bootstrap GMP $VERSION;
     56 
     57 
     58 # The format string is cut up into "%" specifiers so GMP types can be
     59 # passed to GMP::sprintf_internal.  Any "*"s are interpolated before
     60 # calling sprintf_internal, which saves worrying about variable
     61 # argument lists there.
     62 #
     63 # Because sprintf_internal is only called after the conversion and
     64 # operand have been checked there won't be any crashes from a bad
     65 # format string.
     66 #
     67 sub sprintf {
     68   my $fmt = shift;
     69   my $out = '';
     70   my ($pre, $dummy, $pat, $rest);
     71 
     72   while (($pre, $dummy, $pat, $rest) = ($fmt =~ /^((%%|[^%])*)(%[- +#.*hlLqv\d]*[bcdfeEgGinopsuxX])(.*)$/s)) {
     73 
     74     $out .= $pre;
     75 
     76     my $pat2 = $pat;    # $pat with "*"s expanded
     77     my @params = ();    # arguments per "*"s
     78     while ($pat2 =~ /[*]/) {
     79       my $arg = shift;
     80       $pat2 =~ s/[*]/$arg/;
     81       push @params, $arg;
     82     }
     83 
     84     if (UNIVERSAL::isa($_[0],"GMP::Mpz")) {
     85       if ($pat2 !~ /[dioxX]$/) {
     86 	die "GMP::sprintf: unsupported output format for mpz: $pat2\n";
     87       }
     88       $pat2 =~ s/(.)$/Z$1/;
     89       $out .= sprintf_internal ($pat2, shift);
     90 
     91     } elsif (UNIVERSAL::isa($_[0],"GMP::Mpq")) {
     92       if ($pat2 !~ /[dioxX]$/) {
     93 	die "GMP::sprintf: unsupported output format for mpq: $pat2\n";
     94       }
     95       $pat2 =~ s/(.)$/Q$1/;
     96       $out .= sprintf_internal ($pat2, shift);
     97 
     98     } elsif (UNIVERSAL::isa($_[0],"GMP::Mpf")) {
     99       if ($pat2 !~ /[eEfgG]$/) {
    100 	die "GMP::sprintf: unsupported output format for mpf: $pat2\n";
    101       }
    102       $pat2 =~ s/(.)$/F$1/;
    103       $out .= sprintf_internal ($pat2, shift);
    104 
    105     } elsif ($pat =~ /n$/) {
    106       # do it this way so h, l or V type modifiers are respected, and use a
    107       # dummy variable to avoid a warning about discarding the value
    108       my $dummy = sprintf "%s$pat", $out, $_[0];
    109       shift;
    110 
    111     } else {
    112       $out .= sprintf $pat, @params, shift;
    113     }
    114 
    115     $fmt = $rest;
    116   }
    117   $out .= $fmt;
    118   return $out;
    119 }
    120 
    121 sub printf {
    122   if (ref($_[0]) eq 'GLOB') {
    123     my $h = Symbol::qualify_to_ref(shift, caller);
    124     print $h GMP::sprintf(@_);
    125   } else {
    126     print STDOUT GMP::sprintf(@_);
    127   }
    128 }
    129 
    130 1;
    131 __END__
    132 
    133 
    134 
    135 =head1 NAME
    136 
    137 GMP - Perl interface to the GNU Multiple Precision Arithmetic Library
    138 
    139 =head1 SYNOPSIS
    140 
    141     use GMP;
    142     use GMP::Mpz;
    143     use GMP::Mpq;
    144     use GMP::Mpf;
    145     use GMP::Rand;
    146 
    147 =head1 DESCRIPTION
    148 
    149 This module provides access to GNU MP arbitrary precision integers,
    150 rationals and floating point.
    151 
    152 No functions are exported from these packages by default, but can be
    153 selected in the usual way, or the tag :all for everything.
    154 
    155     use GMP::Mpz qw(gcd, lcm);   # just these functions
    156     use GMP::Mpq qw(:all);       # everything in mpq
    157 
    158 =head2 GMP::Mpz
    159 
    160 This class provides arbitrary precision integers.  A new mpz can be
    161 constructed with C<mpz>.  The initial value can be an integer, float,
    162 string, mpz, mpq or mpf.  Floats, mpq and mpf will be automatically
    163 truncated to an integer.
    164 
    165     use GMP::Mpz qw(:all);
    166     my $a = mpz(123);
    167     my $b = mpz("0xFFFF");
    168     my $c = mpz(1.5);       # truncated
    169 
    170 The following overloaded operators are available, and corresponding
    171 assignment forms like C<+=>,
    172 
    173 =over 4
    174 
    175 =item
    176 
    177 + - * / % E<lt>E<lt> E<gt>E<gt> ** & | ^ ! E<lt> E<lt>= == != E<gt> E<gt>=
    178 E<lt>=E<gt> abs not sqrt
    179 
    180 =back
    181 
    182 C</> and C<%> round towards zero (as per the C<tdiv> functions in GMP).
    183 
    184 The following functions are available, behaving the same as the
    185 corresponding GMP mpz functions,
    186 
    187 =over 4
    188 
    189 =item
    190 
    191 bin, cdiv, cdiv_2exp, clrbit, combit, congruent_p, congruent_2exp_p,
    192 divexact, divisible_p, divisible_2exp_p, even_p, fac, fdiv, fdiv_2exp, fib,
    193 fib2, gcd, gcdext, hamdist, invert, jacobi, kronecker, lcm, lucnum, lucnum2,
    194 mod, mpz_export, mpz_import, nextprime, odd_p, perfect_power_p,
    195 perfect_square_p, popcount, powm, probab_prime_p, realloc, remove, root,
    196 roote, scan0, scan1, setbit, sizeinbase, sqrtrem, tdiv, tdiv_2exp, tstbit
    197 
    198 =back
    199 
    200 C<cdiv>, C<fdiv> and C<tdiv> and their C<2exp> variants return a
    201 quotient/remainder pair.  C<fib2> returns a pair F[n] and F[n-1], similarly
    202 C<lucnum2>.  C<gcd> and C<lcm> accept a variable number of arguments (one or
    203 more).  C<gcdext> returns a triplet of gcd and two cofactors, for example
    204 
    205     use GMP::Mpz qw(:all);
    206     $a = 7257;
    207     $b = 10701;
    208     ($g, $x, $y) = gcdext ($a, $b);
    209     print "gcd($a,$b) is $g, and $g == $a*$x + $b*$y\n";
    210 
    211 C<mpz_import> and C<mpz_export> are so named to avoid the C<import> keyword.
    212 Their parameters are as follows,
    213 
    214     $z = mpz_import ($order, $size, $endian, $nails, $string);
    215     $string = mpz_export ($order, $size, $endian, $nails, $z);
    216 
    217 The order, size, endian and nails parameters are as per the corresponding C
    218 functions.  The string input for C<mpz_import> is interpreted as byte data
    219 and must be a multiple of $size bytes.  C<mpz_export> conversely returns a
    220 string of byte data, which will be a multiple of $size bytes.
    221 
    222 C<invert> returns the inverse, or undef if it doesn't exist.  C<remove>
    223 returns a remainder/multiplicity pair.  C<root> returns the nth root, and
    224 C<roote> returns a root/bool pair, the bool indicating whether the root is
    225 exact.  C<sqrtrem> and C<rootrem> return a root/remainder pair.
    226 
    227 C<clrbit>, C<combit> and C<setbit> expect a variable which they can modify,
    228 it doesn't make sense to pass a literal constant.  Only the given variable
    229 is modified, if other variables are referencing the same mpz object then a
    230 new copy is made of it.  If the variable isn't an mpz it will be coerced to
    231 one.  For instance,
    232 
    233     use GMP::Mpz qw(setbit);
    234     setbit (123, 0);  # wrong, don't pass a constant
    235     $a = mpz(6);
    236     $b = $a;
    237     setbit ($a, 0);   # $a becomes 7, $b stays at 6
    238 
    239 C<scan0> and C<scan1> return ~0 if no 0 or 1 bit respectively is found.
    240 
    241 =head2 GMP::Mpq
    242 
    243 This class provides rationals with arbitrary precision numerators and
    244 denominators.  A new mpq can be constructed with C<mpq>.  The initial value
    245 can be an integer, float, string, mpz, mpq or mpf, or a pair of integers or
    246 mpz's.  No precision is lost when converting a float or mpf, the exact value
    247 is retained.
    248 
    249     use GMP::Mpq qw(:all);
    250     $a = mpq();              # zero
    251     $b = mpq(0.5);           # gives 1/2
    252     $b = mpq(14);            # integer 14
    253     $b = mpq(3,4);           # fraction 3/4
    254     $b = mpq("7/12");        # fraction 7/12
    255     $b = mpq("0xFF/0x100");  # fraction 255/256
    256 
    257 When a fraction is given, it should be in the canonical form specified in
    258 the GMP manual, which is denominator positive, no common factors, and zero
    259 always represented as 0/1.  If not then C<canonicalize> can be called to put
    260 it in that form.  For example,
    261 
    262     use GMP::Mpq qw(:all);
    263     $q = mpq(21,15);   # eek! common factor 3
    264     canonicalize($q);  # get rid of it
    265 
    266 The following overloaded operators are available, and corresponding
    267 assignment forms like C<+=>,
    268 
    269 =over 4
    270 
    271 =item
    272 
    273 + - * / E<lt>E<lt> E<gt>E<gt> ** ! E<lt> E<lt>= == != E<gt> E<gt>=
    274 E<lt>=E<gt> abs not
    275 
    276 =back
    277 
    278 The following functions are available,
    279 
    280 =over 4
    281 
    282 =item
    283 
    284 den, inv, num
    285 
    286 =back
    287 
    288 C<inv> calculates 1/q, as per the corresponding GMP function.  C<num> and
    289 C<den> return an mpz copy of the numerator or denominator respectively.  In
    290 the future C<num> and C<den> might give lvalues so the original mpq can be
    291 modified through them, but this is not done currently.
    292 
    293 =head2 GMP::Mpf
    294 
    295 This class provides arbitrary precision floating point numbers.  The
    296 mantissa is an arbitrary user-selected precision and the exponent is a fixed
    297 size (one machine word).
    298 
    299 A new mpf can be constructed with C<mpf>.  The initial value can be an
    300 integer, float, string, mpz, mpq or mpf.  The second argument specifies the
    301 desired precision in bits, or if omitted then the default precision is used.
    302 
    303     use GMP::Mpf qw(:all);
    304     $a = mpf();         # zero
    305     $b = mpf(-7.5);     # default precision
    306     $c = mpf(1.5, 500); # 500 bits precision
    307     $d = mpf("1.0000000000000001");
    308 
    309 The following overloaded operators are available, with the corresponding
    310 assignment forms like C<+=>,
    311 
    312 =over 4
    313 
    314 =item
    315 
    316 + - * / E<lt>E<lt> E<gt>E<gt> ** ! E<lt> E<lt>= == != E<gt> E<gt>=
    317 E<lt>=E<gt> abs not sqrt
    318 
    319 =back
    320 
    321 The following functions are available, behaving the same as the
    322 corresponding GMP mpf functions,
    323 
    324 =over 4
    325 
    326 =item
    327 
    328 ceil, floor, get_default_prec, get_prec, mpf_eq, set_default_prec, set_prec,
    329 trunc
    330 
    331 =back
    332 
    333 C<mpf_eq> is so named to avoid clashing with the perl C<eq> operator.
    334 
    335 C<set_prec> expects a variable which it can modify, it doesn't make sense to
    336 pass a literal constant.  Only the given variable is modified, if other
    337 variables are referencing the same mpf object then a new copy is made of it.
    338 If the variable isn't an mpf it will be coerced to one.
    339 
    340 Results are the same precision as inputs, or if two mpf's are given to a
    341 binary operator then the precision of the first is used.  For example,
    342 
    343     use GMP::Mpf qw(mpf);
    344     $a = mpf(2.0, 100);
    345     $b = mpf(2.0, 500);
    346     $c = $a + $b;         # gives 100 bits precision
    347 
    348 Mpf to string conversion via "" or the usual string contexts uses C<$#> the
    349 same as normal float to string conversions, or defaults to C<%.g> if C<$#>
    350 is not defined.  C<%.g> means all significant digits in the selected
    351 precision.
    352 
    353 =head2 GMP class
    354 
    355 The following functions are available in the GMP class,
    356 
    357 =over 4
    358 
    359 =item
    360 
    361 fits_slong_p, get_d, get_d_2exp, get_si, get_str, integer_p, printf, sgn,
    362 sprintf, version
    363 
    364 =back
    365 
    366 C<get_d_2exp> accepts any integer, string, float, mpz, mpq or mpf operands
    367 and returns a float and an integer exponent,
    368 
    369     ($dbl, $exp) = get_d_2exp (mpf ("3.0"));
    370     # dbl is 0.75, exp is 2
    371 
    372 C<get_str> takes an optional second argument which is the base, defaulting
    373 to decimal.  A negative base means upper case, as per the C functions.  For
    374 integer, integer string, mpz or mpq operands a string is returned.
    375 
    376     use GMP qw(:all);
    377     use GMP::Mpq qw(:all);
    378     print get_str(mpq(-5,8)),"\n";      # -5/8
    379     print get_str(255,16),"\n";         # ff
    380 
    381 For float, float strings or mpf operands, C<get_str> accepts an optional
    382 third parameter being how many digits to produce, defaulting to 0 which
    383 means all digits.  (Only as many digits as can be accurately represented by
    384 the float precision are ever produced though.)  A string/exponent pair is
    385 returned, as per the C mpf_get_str function.  For example,
    386 
    387     use GMP qw(:all);
    388     use GMP::Mpf qw(:all);
    389     ($s, $e) = get_str(111.111111111, 10, 4);
    390     printf ".$se$e\n";                  # .1111e3
    391     ($s, $e) = get_str(1.625, 10);
    392     print "0.$s*10^$e\n";               # 0.1625*10^1
    393     ($s, $e) = get_str(mpf(2)**20, 16);
    394     printf ".%s@%x\n", $s, $e;          # .1@14
    395 
    396 C<printf> and C<sprintf> allow formatted output of GMP types.  mpz and mpq
    397 values can be used with integer conversions (d, o, x, X) and mpf with float
    398 conversions (f, e, E, g, G).  All the standard perl printf features are
    399 available too.  For example,
    400 
    401     use GMP::Mpz qw(mpz);
    402     use GMP::Mpf qw(mpf);
    403     GMP::printf ("%d %d %s", 123, mpz(2)**128, 'foo');
    404     GMP::printf STDERR "%.40f", mpf(1.234);
    405 
    406 In perl 5.6.1 it doesn't seem to work to export C<printf>, the plain builtin
    407 C<printf> is reached unless calls are C<&printf()> style.  Explicit use of
    408 C<GMP::printf> is suggested.  C<sprintf> doesn't suffer this problem.
    409 
    410     use GMP qw(sprintf);
    411     use GMP::Mpq qw(mpq);
    412     $s = sprintf "%x", mpq(15,16);
    413 
    414 C<version> is not exported by default or by tag :all, calling it as
    415 C<GMP::version()> is recommended.  It returns the GMP library version
    416 string, which is not to be confused with the module version number.
    417 
    418 The other GMP module functions behave as per the corresponding GMP routines,
    419 and accept any integer, string, float, mpz, mpq or mpf.  For example,
    420 
    421     use GMP qw(:all);
    422     use GMP::Mpz qw(mpz);
    423     $z = mpz(123);
    424     print sgn($z);    # gives 1
    425 
    426 Because each of GMP::Mpz, GMP::Mpq and GMP::Mpf is a sub-class of GMP,
    427 C<-E<gt>> style calls work too.
    428 
    429     use GMP qw(:all);
    430     use GMP::Mpq qw(mpf);
    431     $q = mpq(-5,7);
    432     if ($q->integer_p())   # false
    433       ...
    434 
    435 =head2 GMP::Rand
    436 
    437 This class provides objects holding an algorithm and state for random number
    438 generation.  C<randstate> creates a new object, for example,
    439 
    440     use GMP::Rand qw(randstate);
    441     $r = randstate();
    442     $r = randstate('lc_2exp_size', 64);
    443     $r = randstate('lc_2exp', 43840821, 1, 32);
    444     $r = randstate('mt');
    445     $r = randstate($another_r);
    446 
    447 With no parameters this corresponds to the C function
    448 C<gmp_randinit_default>, and is a compromise between speed and randomness.
    449 'lc_2exp_size' corresponds to C<gmp_randinit_lc_2exp_size>, 'lc_2exp'
    450 corresponds to C<gmp_randinit_lc_2exp>, and 'mt' corresponds to
    451 C<gmp_randinit_mt>.  Or when passed another randstate object, a copy of that
    452 object is made.
    453 
    454 'lc_2exp_size' can fail if the requested size is bigger than the internal
    455 table provides for, in which case undef is returned.  The maximum size
    456 currently supported is 128.  The other forms always succeed.
    457 
    458 A randstate can be seeded with an integer or mpz, using the C<seed> method.
    459 /dev/random might be a good source of randomness, or time() or
    460 Time::HiRes::time() might be adequate, depending on the application.
    461 
    462     $r->seed(time()));
    463 
    464 Random numbers can be generated with the following functions,
    465 
    466 =over 4
    467 
    468 =item
    469 
    470 mpf_urandomb, mpz_rrandomb, mpz_urandomb, mpz_urandomm,
    471 gmp_urandomb_ui, gmp_urandomm_ui
    472 
    473 =back
    474 
    475 Each constructs a new mpz or mpf and with a distribution per the
    476 corresponding GMP function.  For example,
    477 
    478     use GMP::Rand (:all);
    479     $r = randstate();
    480     $a = mpz_urandomb($r,256);         # uniform mpz, 256 bits
    481     $b = mpz_urandomm($r,mpz(3)**100); # uniform mpz, 0 to 3**100-1
    482     $c = mpz_rrandomb($r,1024);        # special mpz, 1024 bits
    483     $f = mpf_urandomb($r,128);         # uniform mpf, 128 bits, 0<=$f<1
    484     $f = gmp_urandomm_ui($r,56);       # uniform int, 0 to 55
    485 
    486 =head2 Coercion
    487 
    488 Arguments to operators and functions are converted as necessary to the
    489 appropriate type.  For instance C<**> requires an unsigned integer exponent,
    490 and an mpq argument will be converted, so long as it's an integer in the
    491 appropriate range.
    492 
    493     use GMP::Mpz (mpz);
    494     use GMP::Mpq (mpq);
    495     $p = mpz(3) ** mpq(45);   # allowed, 45 is an integer
    496 
    497 It's an error if a conversion to an integer or mpz would cause any
    498 truncation.  For example,
    499 
    500     use GMP::Mpz (mpz);
    501     $p = mpz(3) + 1.25;       # not allowed
    502     $p = mpz(3) + mpz(1.25);  # allowed, explicit truncation
    503 
    504 Comparisons, however, accept any combination of operands and are always done
    505 exactly.  For example,
    506 
    507     use GMP::Mpz (mpz);
    508     print mpz(3) < 3.1;       # true
    509 
    510 Variables used on the left of an assignment operator like C<+=> are subject
    511 to coercion too.  An integer, float or string will change type when an mpz,
    512 mpq or mpf is applied to it.  For example,
    513 
    514     use GMP::Mpz (mpz);
    515     $a = 1;
    516     $a += mpz(1234);   # $a becomes an mpz
    517 
    518 =head2 Overloading
    519 
    520 The rule for binary operators in the C<overload> mechanism is that if both
    521 operands are class objects then the method from the first is used.  This
    522 determines the result type when mixing GMP classes.  For example,
    523 
    524     use GMP::Mpz (mpz);
    525     use GMP::Mpq (mpq);
    526     use GMP::Mpf (mpf);
    527     $z = mpz(123);
    528     $q = mpq(3,2);
    529     $f = mpf(1.375)
    530     print $q+$f;     # gives an mpq
    531     print $f+$z;     # gives an mpf
    532     print $z+$f;     # not allowed, would lose precision
    533 
    534 =head2 Constants
    535 
    536 A special tag C<:constants> is recognised in the module exports list.  It
    537 doesn't select any functions, but indicates that perl constants should be
    538 GMP objects.  This can only be used on one of GMP::Mpz, GMP::Mpq or GMP::Mpf
    539 at any one time, since they apply different rules.
    540 
    541 GMP::Mpz will treat constants as mpz's if they're integers, or ordinary
    542 floats if not.  For example,
    543 
    544     use GMP::Mpz qw(:constants);
    545     print 764861287634126387126378128,"\n";   # an mpz
    546     print 1.25,"\n";                          # a float
    547 
    548 GMP::Mpq is similar, treating integers as mpq's and leaving floats to the
    549 normal perl handling.  Something like 3/4 is read as two integer mpq's and a
    550 division, but that's fine since it gives the intended fraction.
    551 
    552     use GMP::Mpq qw(:constants);
    553     print 3/4,"\n";    # an mpq
    554     print 1.25,"\n";   # a float
    555 
    556 GMP::Mpf will treat all constants as mpf's using the default precision.
    557 BEGIN blocks can be used to set that precision while the code is parsed.
    558 For example,
    559 
    560     use GMP::Mpf qw(:constants);
    561     BEGIN { GMP::Mpf::set_default_prec(256); }
    562     print 1/3;
    563     BEGIN { GMP::Mpf::set_default_prec(64); }
    564     print 5/7;
    565 
    566 A similar special tag :noconstants is recognised to turn off the constants
    567 feature.  For example,
    568 
    569     use GMP::Mpz qw(:constants);
    570     print 438249738748174928193,"\n";   # an mpz
    571     use GMP::Mpz qw(:noconstants);
    572     print 438249738748174928193,"\n";   # now a float
    573 
    574 All three 'integer', 'binary' and 'float' constant methods are captured.
    575 'float' is captured even for GMP::Mpz and GMP::Mpq since perl by default
    576 treats integer strings as floats if they don't fit a plain integer.
    577 
    578 =head1 SEE ALSO
    579 
    580 GMP manual, L<perl>, L<overload>.
    581 
    582 =head1 BUGS
    583 
    584 In perl 5.005_03 on i386 FreeBSD, the overloaded constants sometimes provoke
    585 seg faults.  Don't know if that's a perl bug or a GMP module bug, though it
    586 does seem to go bad before reaching anything in GMP.xs.
    587 
    588 There's no way to specify an arbitrary base when converting a string to an
    589 mpz (or mpq or mpf), only hex or octal with 0x or 0 (for mpz and mpq, but
    590 not for mpf).
    591 
    592 These modules are not reentrant or thread safe, due to the implementation of
    593 the XSUBs.
    594 
    595 Returning a new object from the various functions is convenient, but
    596 assignment versions could avoid creating new objects.  Perhaps they could be
    597 named after the C language functions, eg. mpq_inv($q,$q);
    598 
    599 It'd be good if C<num> and C<den> gave lvalues so the underlying mpq could
    600 be manipulated.
    601 
    602 C<printf> could usefully accept %b for mpz, mpq and mpf, and perhaps %x for
    603 mpf too.
    604 
    605 C<get_str> returning different style values for integer versus float is a
    606 bit unfortunate.  With mpz, mpq and mpf objects there's no doubt what it
    607 will do, but on a plain scalar its action depends on whether the scalar was
    608 promoted to a float at any stage, and then on the GMP module rules about
    609 using the integer or float part.
    610 
    611 =head1 INTERNALS
    612 
    613 In usual perl object style, an mpz is a reference to an object blessed into
    614 class C<GMP::Mpz>.  The object holds a pointer to the C language C<mpz_t>
    615 structure.  Similarly for mpq, mpf and randstate.
    616 
    617 A free list of mpz and mpq values is kept to avoid repeated initializing and
    618 clearing when objects are created and destroyed.  This aims to help speed,
    619 but it's not clear whether it's really needed.
    620 
    621 mpf doesn't use a free list because the precision of new objects can be
    622 different each time.
    623 
    624 No interface to C<mpf_set_prec_raw> is provided.  It wouldn't be very useful
    625 since there's no way to make an operation store its result in a particular
    626 object.  The plain C<set_prec> is useful though, for truncating to a lower
    627 precision, or as a sort of directive that subsequent calculations involving
    628 that variable should use a higher precision.
    629 
    630 The overheads of perl dynamic typing (operator dispatch, operand type
    631 checking or coercion) will mean this interface is slower than using C
    632 directly.
    633 
    634 Some assertion checking is available as a compile-time option.
    635 
    636 =head1 COPYRIGHT
    637 
    638 Copyright 2001-2004 Free Software Foundation, Inc.
    639 
    640 This file is part of the GNU MP Library.
    641 
    642 The GNU MP Library is free software; you can redistribute it and/or modify
    643 it under the terms of either:
    644 
    645   * the GNU Lesser General Public License as published by the Free
    646     Software Foundation; either version 3 of the License, or (at your
    647     option) any later version.
    648 
    649 or
    650 
    651   * the GNU General Public License as published by the Free Software
    652     Foundation; either version 2 of the License, or (at your option) any
    653     later version.
    654 
    655 or both in parallel, as here.
    656 
    657 The GNU MP Library is distributed in the hope that it will be useful, but
    658 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    659 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
    660 for more details.
    661 
    662 You should have received copies of the GNU General Public License and the
    663 GNU Lesser General Public License along with the GNU MP Library.  If not,
    664 see https://www.gnu.org/licenses/.
    665 
    666 =cut
    667 
    668 # Local variables:
    669 # perl-indent-level: 2
    670 # fill-column: 76
    671 # End:
    672