Annotation of OpenXM_contrib/gmp/gmp.info-1, Revision 1.1.1.2
1.1.1.2 ! maekawa 1: This is gmp.info, produced by makeinfo version 4.0 from gmp.texi.
1.1 maekawa 2:
1.1.1.2 ! maekawa 3: INFO-DIR-SECTION GNU libraries
1.1 maekawa 4: START-INFO-DIR-ENTRY
1.1.1.2 ! maekawa 5: * gmp: (gmp). GNU Multiple Precision Arithmetic Library.
1.1 maekawa 6: END-INFO-DIR-ENTRY
7:
8: This file documents GNU MP, a library for arbitrary-precision
9: arithmetic.
10:
1.1.1.2 ! maekawa 11: Copyright (C) 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000
! 12: Free Software Foundation, Inc.
1.1 maekawa 13:
14: Permission is granted to make and distribute verbatim copies of this
15: manual provided the copyright notice and this permission notice are
16: preserved on all copies.
17:
18: Permission is granted to copy and distribute modified versions of
19: this manual under the conditions for verbatim copying, provided that
20: the entire resulting derived work is distributed under the terms of a
21: permission notice identical to this one.
22:
23: Permission is granted to copy and distribute translations of this
24: manual into another language, under the above conditions for modified
25: versions, except that this permission notice may be stated in a
26: translation approved by the Foundation.
27:
28:
29: File: gmp.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
30:
31: GNU MP
32: ******
33:
34: This manual documents how to install and use the GNU multiple
1.1.1.2 ! maekawa 35: precision arithmetic library, version 3.1.
1.1 maekawa 36:
37: * Menu:
38:
1.1.1.2 ! maekawa 39: * Copying:: GMP Copying Conditions (LGPL).
! 40: * Introduction to GMP:: Brief introduction to GNU MP.
! 41: * Installing GMP:: How to configure and compile the GMP library.
! 42: * GMP Basics:: What every GMP user should now.
! 43: * Reporting Bugs:: How to usefully report bugs.
! 44: * Integer Functions:: Functions for arithmetic on signed integers.
! 45: * Rational Number Functions:: Functions for arithmetic on rational numbers.
! 46: * Floating-point Functions:: Functions for arithmetic on floats.
! 47: * Low-level Functions:: Fast functions for natural numbers.
! 48: * Random Number Functions:: Functions for generating random numbers.
! 49: * BSD Compatible Functions:: All functions found in BSD MP.
! 50: * Custom Allocation:: How to customize the internal allocation.
1.1 maekawa 51:
1.1.1.2 ! maekawa 52: * Contributors:: Who brings your this library?
! 53: * References:: Some useful papers and books to read.
1.1 maekawa 54: * Concept Index::
55: * Function Index::
56:
57:
1.1.1.2 ! maekawa 58: File: gmp.info, Node: Copying, Next: Introduction to GMP, Prev: Top, Up: Top
1.1 maekawa 59:
60: GNU MP Copying Conditions
61: *************************
62:
63: This library is "free"; this means that everyone is free to use it
64: and free to redistribute it on a free basis. The library is not in the
65: public domain; it is copyrighted and there are restrictions on its
66: distribution, but these restrictions are designed to permit everything
67: that a good cooperating citizen would want to do. What is not allowed
68: is to try to prevent others from further sharing any version of this
69: library that they might get from you.
70:
71: Specifically, we want to make sure that you have the right to give
72: away copies of the library, that you receive source code or else can
73: get it if you want it, that you can change this library or use pieces
74: of it in new free programs, and that you know you can do these things.
75:
76: To make sure that everyone has such rights, we have to forbid you to
77: deprive anyone else of these rights. For example, if you distribute
78: copies of the GNU MP library, you must give the recipients all the
79: rights that you have. You must make sure that they, too, receive or
80: can get the source code. And you must tell them their rights.
81:
82: Also, for our own protection, we must make certain that everyone
83: finds out that there is no warranty for the GNU MP library. If it is
84: modified by someone else and passed on, we want their recipients to
85: know that what they have is not what we distributed, so that any
86: problems introduced by others will not reflect on our reputation.
87:
88: The precise conditions of the license for the GNU MP library are
89: found in the Library General Public License that accompany the source
90: code.
91:
92:
1.1.1.2 ! maekawa 93: File: gmp.info, Node: Introduction to GMP, Next: Installing GMP, Prev: Copying, Up: Top
1.1 maekawa 94:
95: Introduction to GNU MP
96: **********************
97:
98: GNU MP is a portable library written in C for arbitrary precision
99: arithmetic on integers, rational numbers, and floating-point numbers.
100: It aims to provide the fastest possible arithmetic for all applications
101: that need higher precision than is directly supported by the basic C
102: types.
103:
104: Many applications use just a few hundred bits of precision; but some
1.1.1.2 ! maekawa 105: applications may need thousands or even millions of bits. GMP is
1.1 maekawa 106: designed to give good performance for both, by choosing algorithms
107: based on the sizes of the operands, and by carefully keeping the
108: overhead at a minimum.
109:
1.1.1.2 ! maekawa 110: The speed of GMP is achieved by using fullwords as the basic
1.1 maekawa 111: arithmetic type, by using sophisticated algorithms, by including
112: carefully optimized assembly code for the most common inner loops for
113: many different CPUs, and by a general emphasis on speed (as opposed to
114: simplicity or elegance).
115:
1.1.1.2 ! maekawa 116: There is carefully optimized assembly code for these CPUs: ARM, DEC
! 117: Alpha 21064, 21164, and 21264, AMD 29000, AMD K6 and Athlon, Hitachi
! 118: SuperH and SH-2, HPPA 1.0, 1.1 and 2.0, Intel Pentium, Pentium
! 119: Pro/Pentium II, generic x86, Intel i960, Motorola MC68000, MC68020,
! 120: MC88100, and MC88110, Motorola/IBM PowerPC 32 and 64, National NS32000,
! 121: IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC, generic SPARCv8,
! 122: UltraSPARC, DEC VAX, and Zilog Z8000. Some optimizations also for
! 123: Clipper, IBM ROMP (RT), and Pyramid AP/XP.
! 124:
! 125: There is a mailing list for GMP users. To join it, send a mail to
! 126: <gmp-request@swox.com> with the word `subscribe' in the message *body*
! 127: (not in the subject line).
! 128:
! 129: For up-to-date information on GMP, please see the GMP Home Pages at
! 130: `http://www.swox.com/gmp/'.
1.1 maekawa 131:
132: How to use this Manual
133: ======================
134:
1.1.1.2 ! maekawa 135: Everyone should read *Note GMP Basics::. If you need to install the
! 136: library yourself, you need to read *Note Installing GMP::, too.
1.1 maekawa 137:
138: The rest of the manual can be used for later reference, although it
139: is probably a good idea to glance through it.
140:
141:
1.1.1.2 ! maekawa 142: File: gmp.info, Node: Installing GMP, Next: GMP Basics, Prev: Introduction to GMP, Up: Top
! 143:
! 144: Installing GMP
! 145: **************
! 146:
! 147: GMP has an autoconf/automake/libtool based configuration system. On a
! 148: Unix-like system a basic build can be done with
! 149:
! 150: ./configure
! 151: make
1.1 maekawa 152:
1.1.1.2 ! maekawa 153: Some self-tests can be run with
1.1 maekawa 154:
1.1.1.2 ! maekawa 155: make check
! 156:
! 157: And you can install (under `/usr/local' by default) with
! 158:
! 159: make install
! 160:
! 161: If you experience problems, please report them to <bug-gmp@gnu.org>.
! 162: (*Note Reporting Bugs::, for information on what to include in useful
! 163: bug reports.)
! 164:
! 165: * Menu:
! 166:
! 167: * Build Options::
! 168: * ABI and ISA::
! 169: * Notes for Package Builds::
! 170: * Notes for Particular Systems::
! 171: * Known Build Problems::
! 172:
! 173:
! 174: File: gmp.info, Node: Build Options, Next: ABI and ISA, Prev: Installing GMP, Up: Installing GMP
! 175:
! 176: Build Options
! 177: =============
! 178:
! 179: All the usual autoconf configure options are available, run `./configure
! 180: --help' for a summary.
! 181:
! 182: Non-Unix Systems
! 183: `configure' needs various Unix-like tools installed. On an MS-DOS
! 184: system cygwin or djgpp should work. It might be possible to build
! 185: without the help of `configure', certainly all the code is there,
! 186: but unfortunately you'll be on your own.
! 187:
! 188: Object Directory
! 189: To compile in a separate object directory, `cd' to that directory,
! 190: and prefix the configure command with the path to the GMP source
! 191: directory. For example `../src/gmp/configure'. Not all `make'
! 192: programs have the necessary features (`VPATH') to support this.
! 193: In particular, SunOS and Slowaris `make' have bugs that make them
! 194: unable to build from a separate object directory. Use GNU `make'
! 195: instead.
! 196:
! 197: `--disable-shared', `--disable-static'
! 198: By default both shared and static libraries are built (where
! 199: possible), but one or other can be disabled. Shared libraries are
! 200: very slightly slower, having a small cost on each function call,
! 201: but result in smaller executables and permit code sharing between
! 202: separate running processes.
! 203:
! 204: `--target=CPU-VENDOR-OS'
! 205: The build target can be specified in the usual way, for either
! 206: native or cross compilation.
! 207:
! 208: If `--target' isn't given, `./configure' builds for the host
! 209: system as determined by `./config.guess'. On some systems this
! 210: can't distinguish between different CPUs in a family, and you
! 211: should check the guess. Running `./config.guess' on the target
! 212: system will also show the relevant `VENDOR-OS', if you don't
! 213: already know what it should be.
1.1 maekawa 214:
215: In general, if you want a library that runs as fast as possible,
1.1.1.2 ! maekawa 216: you should configure GMP for the exact CPU type your system uses.
! 217: However, this may mean the binaries won't run on older members of
! 218: the family, and might run slower on other members, older or newer.
! 219: The best idea is always to build GMP for the exact machine type
! 220: you intend to run it on.
! 221:
! 222: The following CPU targets have specific assembly code support. See
! 223: `configure.in' for which `mpn' subdirectories get used by each.
! 224:
! 225: * Alpha: `alpha', `alphaev5', `alphaev6'
! 226:
! 227: * Hitachi: `sh', `sh2'
! 228:
! 229: * HPPA: `hppa1.0', `hppa1.1', `hppa2.0', `hppa2.0w'
! 230:
! 231: * MIPS: `mips', `mips3',
! 232:
! 233: * Motorola: `m68000', `m68k', `m88k', `m88110'
1.1 maekawa 234:
1.1.1.2 ! maekawa 235: * POWER: `power1', `power2', `power2sc', `powerpc', `powerpc64'
! 236:
! 237: * SPARC: `sparc', `sparcv8', `microsparc', `supersparc',
! 238: `sparcv9', `ultrasparc', `sparc64'
! 239:
! 240: * 80x86 family: `i386', `i486', `i586', `pentium', `pentiummmx',
! 241: `pentiumpro', `pentium2', `pentium3', `k6', `k62', `k63',
! 242: `athlon'
! 243:
! 244: * Other: `a29k', `arm', `clipper', `i960', `ns32k', `pyramid',
! 245: `vax', `z8k'
! 246:
! 247: CPUs not listed use generic C code. If some of the assembly code
! 248: causes problems, the generic C code can be selected with CPU
! 249: `none'.
! 250:
! 251: `CC', `CFLAGS'
! 252: The C compiler used is chosen from among some likely candidates,
! 253: with GCC normally preferred if it's present. The usual
! 254: `CC=whatever' can be passed to `./configure' to choose something
! 255: different.
! 256:
! 257: For some configurations specific compiler flags are set based on
! 258: the target CPU and compiler, for others `CFLAGS="-whatever"' can
! 259: be used to set the best flags.
! 260:
! 261: If `CC' is set then `CFLAGS' must also be set. This applies even
! 262: if `CC' is merely one of the choices GMP would make itself. This
! 263: may change in a future release.
! 264:
! 265: `--disable-alloca'
! 266: By default, GMP allocates temporary workspace using `alloca' if
! 267: that function is available, or `malloc' if not. If you're working
! 268: with large numbers and `alloca' overflows the available stack
! 269: space, you can build with `--disable-alloca' to use `malloc'
! 270: instead. `malloc' will probably be slightly slower than `alloca'.
! 271:
! 272: When not using `alloca', it's actually the allocation function
! 273: selected with `mp_set_memory_functions' that's used, this being
! 274: `malloc' by default. *Note Custom Allocation::.
! 275:
! 276: Depending on your system, the only indication of stack overflow
! 277: might be a segmentation violation. It might be possible to
! 278: increase available stack space with `limit', `ulimit' or
! 279: `setrlimit', or under DJGPP with `stubedit' or `_stklen'.
! 280:
! 281: `--enable-fft'
! 282: By default multiplications are done using Karatsuba and 3-way
! 283: Toom-Cook algorithms, but a Fermat FFT can be enabled, for use on
! 284: large to very large operands. Currently the FFT is recommended
! 285: only for knowledgeable users who check the algorithm thresholds
! 286: for their CPU.
! 287:
! 288: `--enable-mpbsd'
! 289: The Berkeley MP compatibility library (`libmp.a') and header file
! 290: (`mp.h') are built and installed only if `--enable-mpbsd' is used.
! 291: *Note BSD Compatible Functions::.
! 292:
! 293: `MPN_PATH'
! 294: Various assembler versions of mpn subroutines are provided, and,
! 295: for a given CPU target, a search is made though a path to choose a
! 296: version of each. For example `sparcv8' has path `"sparc32/v8
! 297: sparc32 generic"', which means it looks first for v8 code, falls
! 298: back on plain sparc32, and finally falls back on generic C.
! 299: Knowledgeable users with special requirements can specify a path
! 300: with `MPN_PATH="dir list"'. This will normally be unnecessary
! 301: because all sensible paths should be available under one or other
! 302: CPU target.
! 303:
! 304: Demonstration Programs
! 305: The `demos' subdirectory has some sample programs using GMP. These
! 306: aren't built or installed, but there's a `Makefile' with rules for
! 307: them. For instance, `make pexpr' and then `./pexpr 68^975+10'.
! 308:
! 309: Documentation
! 310: The document you're now reading is `gmp.texi'. The usual automake
! 311: targets are available to make `gmp.ps' and/or `gmp.dvi'. Some
! 312: supplementary notes can be found in the `doc' subdirectory.
! 313:
! 314:
! 315: File: gmp.info, Node: ABI and ISA, Next: Notes for Package Builds, Prev: Build Options, Up: Installing GMP
1.1 maekawa 316:
1.1.1.2 ! maekawa 317: ABI and ISA
! 318: ===========
1.1 maekawa 319:
1.1.1.2 ! maekawa 320: ABI (Application Binary Interface) refers to the calling conventions
! 321: between functions, meaning what registers are used and what sizes the
! 322: various C data types are. ISA (Instruction Set Architecture) refers to
! 323: the instructions and registers a CPU has available.
1.1 maekawa 324:
1.1.1.2 ! maekawa 325: Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI
! 326: defined, the latter for compatibility with older CPUs in the family.
! 327: GMP chooses the best ABI available for a given target system, and this
! 328: generally gives significantly greater speed.
1.1 maekawa 329:
1.1.1.2 ! maekawa 330: The burden is on application programs and cooperating libraries to
! 331: ensure they match the ABI chosen by GMP. Fortunately this presents a
! 332: difficulty only on a few systems, and if you have one of them then the
! 333: performance gains are enough to make it worth the trouble.
1.1 maekawa 334:
1.1.1.2 ! maekawa 335: Some of what's described in this section may change in future
! 336: releases of GMP.
1.1 maekawa 337:
1.1.1.2 ! maekawa 338: HPPA 2.0
! 339: CPU target `hppa2.0' uses the hppa2.0n 32-bit ABI, but either a
! 340: 32-bit or 64-bit limb.
1.1 maekawa 341:
1.1.1.2 ! maekawa 342: A 64-bit limb is available on HP-UX 10 or up when using `c89'. No
! 343: `gcc' support is planned for 64-bit operations in this ABI.
! 344: Applications must be compiled with the same options as GMP, which
! 345: means
1.1 maekawa 346:
1.1.1.2 ! maekawa 347: c89 +DA2.0 +e -D_LONG_LONG_LIMB
1.1 maekawa 348:
1.1.1.2 ! maekawa 349: A 32-bit limb is used in other cases, and no special compiler
! 350: options are needed.
1.1 maekawa 351:
1.1.1.2 ! maekawa 352: CPU target `hppa2.0w' uses the hppa2.0w 64-bit ABI, which is
! 353: available on HP-UX 11 or up when using `c89'. `gcc' support for
! 354: this is in progress. Applications must be compiled for the same
! 355: ABI, which means
1.1 maekawa 356:
1.1.1.2 ! maekawa 357: c89 +DD64
1.1 maekawa 358:
1.1.1.2 ! maekawa 359: MIPS 3 and 4 under IRIX 6
! 360: Targets `mips*-*-irix6*' use the n32 ABI and a 64-bit limb.
! 361: Applications must be compiled for the same ABI, which means either
1.1 maekawa 362:
1.1.1.2 ! maekawa 363: gcc -mabi=n32
! 364: cc -n32
1.1 maekawa 365:
1.1.1.2 ! maekawa 366: PowerPC 64
! 367: CPU target `powerpc64' uses either the 32-bit ABI or the AIX
! 368: 64-bit ABI. The latter is used on targets `powerpc64-*-aix*' and
! 369: applications must be compiled using either
1.1 maekawa 370:
1.1.1.2 ! maekawa 371: gcc -maix64
! 372: xlc -q64
1.1 maekawa 373:
1.1.1.2 ! maekawa 374: On other systems the 32-bit ABI is used, but with 64-bit limbs
! 375: provided by `long long' in `gcc'. Applications must be compiled
! 376: using
1.1 maekawa 377:
1.1.1.2 ! maekawa 378: gcc -D_LONG_LONG_LIMB
1.1 maekawa 379:
1.1.1.2 ! maekawa 380: Sparc V9
! 381: On a sparc v9 CPU, either the v8plus 32-bit ABI or v9 64-bit ABI
! 382: is used. Targets `ultrasparc*-*-solaris2.[7-9]',
! 383: `sparcv9-*-solaris2.[7-9]' and `sparc64-*-linux*' use the v9 ABI,
! 384: if the compiler supports it. Other targets use the v8plus ABI
! 385: (but with as much of the v9 ISA as possible in the circumstances).
! 386: Note that Solaris prior to 2.7 doesn't save all registers
! 387: properly, and hence uses the v8plus ABI.
1.1 maekawa 388:
1.1.1.2 ! maekawa 389: For the v8plus ABI, applications can be compiled with either
1.1 maekawa 390:
1.1.1.2 ! maekawa 391: gcc -mv8plus
! 392: cc -xarch=v8plus
! 393:
! 394: For the v9 ABI, applications must be compiled with either
! 395:
! 396: gcc -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9
! 397: cc -xarch=v9
! 398:
! 399: Don't be confused by the names of these options, they're called
! 400: `arch' but they effectively control the ABI.
! 401:
! 402:
! 403: File: gmp.info, Node: Notes for Package Builds, Next: Notes for Particular Systems, Prev: ABI and ISA, Up: Installing GMP
! 404:
! 405: Notes for Package Builds
! 406: ========================
! 407:
! 408: GMP should present no great difficulties for packaging in a binary
! 409: distribution.
! 410:
! 411: Libtool is used to build the library and `-version-info' is set
! 412: appropriately, having started from `3:0:0' in GMP 3.0. The GMP 3 series
! 413: will be upwardly binary compatible in each release, but may be adding
! 414: additional function interfaces. On systems where libtool versioning is
! 415: not fully checked by the loader, an auxiliary mechanism may be needed
! 416: to express that a dynamic linked application depends on a new enough
! 417: minor version of GMP.
! 418:
! 419: When building a package for a CPU family, care should be taken to use
! 420: `--target' to choose the least common denominator among the CPUs which
! 421: might use the package. For example this might necessitate `i386' for
! 422: x86s, or plain `sparc' (meaning V7) for SPARCs.
! 423:
! 424: Users who care about speed will want GMP built for their exact CPU
! 425: type, to make use of the available optimizations. Providing a way to
! 426: suitably rebuild a package may be useful. This could be as simple as
! 427: making it possible for a user to omit `--target' in a build so
! 428: `./config.guess' will detect the CPU. But a way to manually specify a
! 429: `--target' will be wanted for systems where `./config.guess' is inexact.
! 430:
! 431:
! 432: File: gmp.info, Node: Notes for Particular Systems, Next: Known Build Problems, Prev: Notes for Package Builds, Up: Installing GMP
! 433:
! 434: Notes for Particular Systems
! 435: ============================
! 436:
! 437: AIX 4.3
! 438: Targets `*-*-aix4.[3-9]*' have shared libraries disabled since
! 439: they seem to fail on AIX 4.3.
! 440:
! 441: OpenBSD 2.6
! 442: `m4' in this release of OpenBSD has a bug in `eval' that makes it
! 443: unsuitable for `.asm' file processing. `./configure' will detect
! 444: the problem and either abort or choose another m4 in the `PATH'.
! 445: The bug is fixed in OpenBSD 2.7, so either upgrade or use GNU m4.
! 446:
! 447: Sparc V8
! 448: Using CPU target `sparcv8' or `supersparc' on relevant systems will
! 449: give a significant performance increase over the V7 code.
! 450:
! 451: SunOS 4
! 452: `/usr/bin/m4' lacks various features needed to process `.asm'
! 453: files, and instead `./configure' will automatically use
! 454: `/usr/5bin/m4', which we believe is always available (if not then
! 455: use GNU m4).
! 456:
! 457: x86 Pentium and PentiumPro
! 458: The Intel Pentium P5 code is good for its intended P5, but quite
! 459: slow when run on Intel P6 class chips (PPro, P-II, P-III). `i386'
! 460: is a better choice if you're making binaries that must run on both.
! 461:
! 462: x86 MMX and old GAS
! 463: Old versions of GAS don't support MMX instructions, in particular
! 464: version 1.92.3 that comes with FreeBSD 2.2.8 doesn't (and
! 465: unfortunately there's no newer assembler for that system).
! 466:
! 467: If the target CPU has MMX code but the assembler doesn't support
! 468: it, a warning is given and non-MMX code is used instead. This
! 469: will be an inferior build, since the MMX code that's present is
! 470: there because it's faster than the corresponding plain integer
! 471: code.
! 472:
! 473: x86 GCC 2.95.2 `-march=pentiumpro'
! 474: GCC 2.95.2 miscompiles `mpz/powm.c' when `-march=pentiumpro' is
! 475: used, so that option is omitted from the `CFLAGS' chosen for
! 476: relevant CPUs. The problem is believed to be fixed in GCC 2.96.
! 477:
! 478:
! 479: File: gmp.info, Node: Known Build Problems, Prev: Notes for Particular Systems, Up: Installing GMP
1.1 maekawa 480:
481: Known Build Problems
482: ====================
483:
1.1.1.2 ! maekawa 484: You might find more up-to-date information at
! 485: `http://www.swox.com/gmp/'.
! 486:
! 487: Generic C on a 64-bit system
! 488: When making a generic C build using `--target=none' on a 64-bit
! 489: system (meaning where `unsigned long' is 64 bits),
! 490: `BITS_PER_MP_LIMB', `BITS_PER_LONGINT' and `BYTES_PER_MP_LIMB' in
! 491: `mpn/generic/gmp-mparam.h' need to be changed to 64 and 8. This
! 492: will hopefully be automated in a future version of GMP.
! 493:
! 494: NeXT prior to 3.3
! 495: The system compiler on old versions of NeXT was a massacred and
! 496: old GCC, even if it called itself `cc'. This compiler cannot be
! 497: used to build GMP, you need to get a real GCC, and install that
! 498: before you compile GMP. (NeXT may have fixed this in release 3.3
! 499: of their system.)
! 500:
! 501: POWER and PowerPC
! 502: Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP
! 503: on POWER or PowerPC. If you want to use GCC for these machines,
! 504: get GCC 2.7.2.1 (or later).
! 505:
! 506: Sequent Symmetry
! 507: Use the GNU assembler instead of the system assembler, since the
! 508: latter has serious bugs.
! 509:
! 510: Stripped Libraries
! 511: GNU binutils `strip' should not be used on the static libraries
! 512: `libgmp.a' and `libmp.a', neither directly nor via `make
! 513: install-strip'. It can be used on the shared libraries
! 514: `libgmp.so' and `libmp.so' though.
! 515:
! 516: Currently (binutils 2.10.0), `strip' extracts archives into a
! 517: single directory, but GMP contains multiple object files of the
! 518: same name (eg. three versions of `init.o'), and they overwrite
! 519: each other, leaving only the one that happens to be last.
! 520:
! 521: If stripped static libraries are wanted, the suggested workaround
! 522: is to build normally, strip the separate object files, and do
! 523: another `make all' to rebuild. Alternately `CFLAGS' with `-g'
! 524: omitted can always be used if it's just debugging which is
! 525: unwanted.
! 526:
! 527: SunOS 4 Native Tools
! 528: The setting for `GSYM_PREFIX' in `config.m4' may be incorrectly
! 529: determined when using the native `grep', leading at link-time to
! 530: undefined symbols like `___gmpn_add_n'. To fix this, after running
! 531: `./configure', change the relevant line in `config.m4' to
! 532: `define(<GSYM_PREFIX>, <_>)'.
! 533:
! 534: The `ranlib' command will need to be run manually when building a
! 535: static library with the native `ar'. After `make', run `ranlib
! 536: .libs/libgmp.a', and when using `--enable-mpbsd' run `ranlib
! 537: .libs/libmp.a' too.
! 538:
! 539: VAX running Ultrix
! 540: You need to build and install the GNU assembler before you compile
! 541: GMP. The VAX assembly in GMP uses an instruction (`jsobgtr') that
! 542: cannot be assembled by the Ultrix assembler.
1.1 maekawa 543:
544:
1.1.1.2 ! maekawa 545: File: gmp.info, Node: GMP Basics, Next: Reporting Bugs, Prev: Installing GMP, Up: Top
1.1 maekawa 546:
1.1.1.2 ! maekawa 547: GMP Basics
! 548: **********
1.1 maekawa 549:
1.1.1.2 ! maekawa 550: All declarations needed to use GMP are collected in the include file
1.1 maekawa 551: `gmp.h'. It is designed to work with both C and C++ compilers.
552:
1.1.1.2 ! maekawa 553: *Using functions, macros, data types, etc. not documented in this
! 554: manual is strongly discouraged. If you do so your application is
! 555: guaranteed to be incompatible with future versions of GMP.*
! 556:
! 557: * Menu:
! 558:
! 559: * Nomenclature and Types:: Which data types are there?
! 560: * Function Classes:: How the functions are organized.
! 561: * GMP Variable Conventions:: Some rules and hints about variables.
! 562: * GMP and Reentrancy:: What about reentrancy?
! 563: * Useful Macros and Constants:: Convenient helpers.
! 564: * Compatibility with older versions:: Compatibility issues.
! 565: * Getting the Latest Version of GMP:: How to get the software.
! 566:
! 567:
! 568: File: gmp.info, Node: Nomenclature and Types, Next: Function Classes, Prev: GMP Basics, Up: GMP Basics
! 569:
1.1 maekawa 570: Nomenclature and Types
571: ======================
572:
573: In this manual, "integer" usually means a multiple precision integer, as
1.1.1.2 ! maekawa 574: defined by the GMP library. The C data type for such integers is
1.1 maekawa 575: `mpz_t'. Here are some examples of how to declare such integers:
576:
577: mpz_t sum;
578:
579: struct foo { mpz_t x, y; };
580:
581: mpz_t vec[20];
582:
583: "Rational number" means a multiple precision fraction. The C data type
584: for these fractions is `mpq_t'. For example:
585:
586: mpq_t quotient;
587:
588: "Floating point number" or "Float" for short, is an arbitrary precision
1.1.1.2 ! maekawa 589: mantissa with a limited precision exponent. The C data type for such
1.1 maekawa 590: objects is `mpf_t'.
591:
592: A "limb" means the part of a multi-precision number that fits in a
593: single word. (We chose this word because a limb of the human body is
594: analogous to a digit, only larger, and containing several digits.)
595: Normally a limb contains 32 or 64 bits. The C data type for a limb is
596: `mp_limb_t'.
597:
1.1.1.2 ! maekawa 598:
! 599: File: gmp.info, Node: Function Classes, Next: GMP Variable Conventions, Prev: Nomenclature and Types, Up: GMP Basics
! 600:
1.1 maekawa 601: Function Classes
602: ================
603:
1.1.1.2 ! maekawa 604: There are six classes of functions in the GMP library:
1.1 maekawa 605:
606: 1. Functions for signed integer arithmetic, with names beginning with
607: `mpz_'. The associated type is `mpz_t'. There are about 100
608: functions in this class.
609:
610: 2. Functions for rational number arithmetic, with names beginning with
611: `mpq_'. The associated type is `mpq_t'. There are about 20
612: functions in this class, but the functions in the previous class
613: can be used for performing arithmetic on the numerator and
614: denominator separately.
615:
616: 3. Functions for floating-point arithmetic, with names beginning with
617: `mpf_'. The associated type is `mpf_t'. There are about 50
618: functions is this class.
619:
1.1.1.2 ! maekawa 620: 4. Functions compatible with Berkeley GMP, such as `itom', `madd', and
1.1 maekawa 621: `mult'. The associated type is `MINT'.
622:
623: 5. Fast low-level functions that operate on natural numbers. These
624: are used by the functions in the preceding groups, and you can
625: also call them directly from very time-critical user programs.
626: These functions' names begin with `mpn_'. There are about 30
627: (hard-to-use) functions in this class.
628:
629: The associated type is array of `mp_limb_t'.
630:
631: 6. Miscellaneous functions. Functions for setting up custom
1.1.1.2 ! maekawa 632: allocation and functions for generating random numbers.
! 633:
! 634:
! 635: File: gmp.info, Node: GMP Variable Conventions, Next: GMP and Reentrancy, Prev: Function Classes, Up: GMP Basics
1.1 maekawa 636:
1.1.1.2 ! maekawa 637: GMP Variable Conventions
! 638: ========================
1.1 maekawa 639:
1.1.1.2 ! maekawa 640: As a general rule, all GMP functions expect output arguments before
1.1 maekawa 641: input arguments. This notation is based on an analogy with the
642: assignment operator. (The BSD MP compatibility functions disobey this
643: rule, having the output argument(s) last.)
644:
1.1.1.2 ! maekawa 645: GMP lets you use the same variable for both input and output in one
! 646: call. For example, the main function for integer multiplication,
! 647: `mpz_mul', can be used to square `x' and put the result back in `x' with
1.1 maekawa 648:
1.1.1.2 ! maekawa 649: mpz_mul (x, x, x);
! 650:
! 651: Before you can assign to a GMP variable, you need to initialize it
1.1 maekawa 652: by calling one of the special initialization functions. When you're
653: done with a variable, you need to clear it out, using one of the
654: functions for that purpose. Which function to use depends on the type
655: of variable. See the chapters on integer functions, rational number
656: functions, and floating-point functions for details.
657:
658: A variable should only be initialized once, or at least cleared out
659: between each initialization. After a variable has been initialized, it
660: may be assigned to any number of times.
661:
1.1.1.2 ! maekawa 662: For efficiency reasons, avoid initializing and clearing out a GMP
! 663: variable in a loop. Instead, initialize it before entering the loop,
! 664: and clear it out after the loop has exited.
! 665:
! 666: GMP variables are small, containing only a couple of sizes, and
! 667: pointers to allocated data. Once you have initialized a GMP variable,
! 668: you don't need to worry about space allocation. All functions in GMP
! 669: automatically allocate additional space when a variable does not
! 670: already have enough. They do not, however, reduce the space when a
! 671: smaller value is stored. Most of the time this policy is best, since
! 672: it avoids frequent re-allocation.
! 673:
! 674: When a variable of type `mpz_t' is used as a function parameter, it's
! 675: effectively a call-by-reference, meaning anything the function does to
! 676: it will be be done to the original in the caller. When a function is
! 677: going to return an `mpz_t' result, it should provide a separate
! 678: parameter or parameters that it sets, like the GMP library functions
! 679: do. A `return' of an `mpz_t' doesn't return the object, only a pointer
! 680: to it, and this is almost certainly not what you want. All this
! 681: applies to `mpq_t' and `mpf_t' too.
! 682:
! 683: Here's an example function accepting an `mpz_t' parameter, doing a
! 684: certain calculation, and returning a result.
! 685:
! 686: void
! 687: myfunction (mpz_t result, mpz_t param, unsigned long n)
! 688: {
! 689: unsigned long i;
! 690:
! 691: mpz_mul_ui (result, param, n);
! 692: for (i = 1; i < n; i++)
! 693: mpz_add_ui (result, result, i*7);
! 694: }
! 695:
! 696: int
! 697: main (void)
! 698: {
! 699: mpz_t r, n;
! 700: mpz_init (r);
! 701: mpz_init_set_str (n, "123456", 0);
! 702:
! 703: myfunction (r, n, 20L);
! 704: mpz_out_str (stdout, 10, r); printf ("\n");
! 705:
! 706: return 0;
! 707: }
! 708:
! 709: This example will work if `result' and `param' are the same
! 710: variable, just like the library functions. But sometimes this is
! 711: tricky to arrange, and an application might not want to bother for its
! 712: own subroutines.
! 713:
! 714: `mpz_t' is actually implemented as a one-element array of a certain
! 715: structure type. This is why using it to declare a variable gives an
! 716: object with the fields GMP needs, but then using it as a parameter
! 717: passes a pointer to the object. Note that the actual contents of an
! 718: `mpz_t' are for internal use only and you should not access them
! 719: directly if you want your code to be compatible with future GMP
! 720: releases.
! 721:
! 722:
! 723: File: gmp.info, Node: GMP and Reentrancy, Next: Useful Macros and Constants, Prev: GMP Variable Conventions, Up: GMP Basics
! 724:
! 725: GMP and Reentrancy
! 726: ==================
! 727:
! 728: The GMP code is reentrant and thread-safe, with some exceptions:
! 729:
! 730: * The function `mpf_set_default_prec' saves the selected precision in
! 731: a global variable.
! 732:
! 733: * The function `mp_set_memory_functions' uses several global
! 734: variables for storing the selected memory allocation functions.
! 735:
! 736: * If the memory allocation functions set by a call to
! 737: `mp_set_memory_functions' (or `malloc' and friends by default) are
! 738: not reentrant, GMP will not be reentrant either.
! 739:
! 740: * The old random number functions (`mpz_random', etc) use a random
! 741: number generator from the C library, usually `mrand48' or
! 742: `random'. These routines are not reentrant, since they rely on
! 743: global state. (However the newer random number functions that
! 744: accept a `gmp_randstate_t' parameter are reentrant.)
! 745:
! 746:
! 747: File: gmp.info, Node: Useful Macros and Constants, Next: Compatibility with older versions, Prev: GMP and Reentrancy, Up: GMP Basics
1.1 maekawa 748:
749: Useful Macros and Constants
750: ===========================
751:
752: - Global Constant: const int mp_bits_per_limb
753: The number of bits per limb.
754:
755: - Macro: __GNU_MP_VERSION
756: - Macro: __GNU_MP_VERSION_MINOR
1.1.1.2 ! maekawa 757: - Macro: __GNU_MP_VERSION_PATCHLEVEL
! 758: The major and minor GMP version, and patch level, respectively, as
! 759: integers. For GMP i.j, these numbers will be i, j, and 0,
! 760: respectively. For GMP i.j.k, these numbers will be i, j, and k,
! 761: respectively.
1.1 maekawa 762:
1.1.1.2 ! maekawa 763:
! 764: File: gmp.info, Node: Compatibility with older versions, Next: Getting the Latest Version of GMP, Prev: Useful Macros and Constants, Up: GMP Basics
1.1 maekawa 765:
1.1.1.2 ! maekawa 766: Compatibility with older versions
! 767: =================================
1.1 maekawa 768:
1.1.1.2 ! maekawa 769: This version of GMP is upwardly binary compatible with versions 3.0
! 770: and 3.0.1, and upwardly compatible at the source level with versions
! 771: 2.0, 2.0.1, and 2.0.2, with the following exceptions.
1.1 maekawa 772:
1.1.1.2 ! maekawa 773: * `mpn_gcd' had its source arguments swapped as of GMP 3.0 for
! 774: consistency with other `mpn' functions.
1.1 maekawa 775:
1.1.1.2 ! maekawa 776: * `mpf_get_prec' counted precision slightly differently in GMP 3.0
! 777: and 3.0.1, but in 3.1 has reverted to the 2.0.x style.
1.1 maekawa 778:
779:
1.1.1.2 ! maekawa 780: There are a number of compatibility issues between GMP 1 and GMP 2
! 781: that of course also apply when porting applications from GMP 1 to GMP
! 782: 3. Please see the GMP 2 manual for details.
1.1 maekawa 783:
1.1.1.2 ! maekawa 784:
! 785: File: gmp.info, Node: Getting the Latest Version of GMP, Prev: Compatibility with older versions, Up: GMP Basics
1.1 maekawa 786:
1.1.1.2 ! maekawa 787: Getting the Latest Version of GMP
! 788: =================================
1.1 maekawa 789:
1.1.1.2 ! maekawa 790: The latest version of the GMP library is available at
! 791: `ftp://ftp.gnu.org/pub/gnu/gmp'. Many sites around the world mirror
! 792: `ftp.gnu.org'; please use a mirror site near you, see
! 793: `http://www.gnu.org/order/ftp.html'.
1.1 maekawa 794:
795:
1.1.1.2 ! maekawa 796: File: gmp.info, Node: Reporting Bugs, Next: Integer Functions, Prev: GMP Basics, Up: Top
1.1 maekawa 797:
798: Reporting Bugs
799: **************
800:
1.1.1.2 ! maekawa 801: If you think you have found a bug in the GMP library, please
1.1 maekawa 802: investigate it and report it. We have made this library available to
1.1.1.2 ! maekawa 803: you, and it is not too much to ask you to report the bugs you find.
! 804: Before you report a bug, you may want to check
! 805: `http://www.swox.com/gmp/' for patches for this release.
! 806:
! 807: Please include the following in any report,
! 808:
! 809: * The GMP version number, and if pre-packaged or patched then say so.
1.1 maekawa 810:
1.1.1.2 ! maekawa 811: * A test program that makes it possible for us to reproduce the bug.
! 812: Include instructions on how to run the program.
1.1 maekawa 813:
1.1.1.2 ! maekawa 814: * A description of what is wrong. If the results are incorrect, in
! 815: what way. If you get a crash, say so.
1.1 maekawa 816:
1.1.1.2 ! maekawa 817: * If you get a crash, include a stack backtrace from the debugger if
! 818: it's informative (`where' in `gdb', or `$C' in `adb').
! 819:
! 820: * *Please do not send core dumps, executables or `strace's.*
! 821:
! 822: * The configuration options you used when building GMP, if any.
! 823:
! 824: * The name of the compiler and its version. For `gcc', get the
! 825: version with `gcc -v', otherwise perhaps `what `which cc`', or
! 826: similar.
! 827:
! 828: * The output from running `uname -a'.
! 829:
! 830: * The output from running `./config.guess'.
! 831:
! 832: * If the bug is related to `configure', then the contents of
! 833: `config.log'.
! 834:
! 835: * If the bug is related to an `asm' file not assembling, then the
! 836: contents of `config.m4'.
1.1 maekawa 837:
838: It is not uncommon that an observed problem is actually due to a bug
1.1.1.2 ! maekawa 839: in the compiler; the GMP code tends to explore interesting corners in
! 840: compilers.
1.1 maekawa 841:
1.1.1.2 ! maekawa 842: If your bug report is good, we will do our best to help you get a
1.1 maekawa 843: corrected version of the library; if the bug report is poor, we won't
1.1.1.2 ! maekawa 844: do anything about it (except maybe ask you to send a better report).
1.1 maekawa 845:
1.1.1.2 ! maekawa 846: Send your report to: <bug-gmp@gnu.org>.
1.1 maekawa 847:
848: If you think something in this manual is unclear, or downright
849: incorrect, or if the language needs to be improved, please send a note
850: to the same address.
851:
852:
853: File: gmp.info, Node: Integer Functions, Next: Rational Number Functions, Prev: Reporting Bugs, Up: Top
854:
855: Integer Functions
856: *****************
857:
1.1.1.2 ! maekawa 858: This chapter describes the GMP functions for performing integer
1.1 maekawa 859: arithmetic. These functions start with the prefix `mpz_'.
860:
1.1.1.2 ! maekawa 861: GMP integers are stored in objects of type `mpz_t'.
1.1 maekawa 862:
863: * Menu:
864:
865: * Initializing Integers::
866: * Assigning Integers::
867: * Simultaneous Integer Init & Assign::
868: * Converting Integers::
869: * Integer Arithmetic::
1.1.1.2 ! maekawa 870: * Integer Division::
! 871: * Integer Exponentiation::
! 872: * Integer Roots::
! 873: * Number Theoretic Functions::
! 874: * Integer Comparisons::
1.1 maekawa 875: * Integer Logic and Bit Fiddling::
876: * I/O of Integers::
1.1.1.2 ! maekawa 877: * Integer Random Numbers::
1.1 maekawa 878: * Miscellaneous Integer Functions::
879:
880:
1.1.1.2 ! maekawa 881: File: gmp.info, Node: Initializing Integers, Next: Assigning Integers, Prev: Integer Functions, Up: Integer Functions
1.1 maekawa 882:
1.1.1.2 ! maekawa 883: Initialization Functions
! 884: ========================
1.1 maekawa 885:
886: The functions for integer arithmetic assume that all integer objects
887: are initialized. You do that by calling the function `mpz_init'.
888:
889: - Function: void mpz_init (mpz_t INTEGER)
890: Initialize INTEGER with limb space and set the initial numeric
891: value to 0. Each variable should normally only be initialized
892: once, or at least cleared out (using `mpz_clear') between each
893: initialization.
894:
895: Here is an example of using `mpz_init':
896:
897: {
898: mpz_t integ;
899: mpz_init (integ);
900: ...
901: mpz_add (integ, ...);
902: ...
903: mpz_sub (integ, ...);
904:
905: /* Unless the program is about to exit, do ... */
906: mpz_clear (integ);
907: }
908:
909: As you can see, you can store new values any number of times, once an
910: object is initialized.
911:
912: - Function: void mpz_clear (mpz_t INTEGER)
913: Free the limb space occupied by INTEGER. Make sure to call this
914: function for all `mpz_t' variables when you are done with them.
915:
916: - Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC)
917: Change the limb space allocation to NEW_ALLOC limbs. This
918: function is not normally called from user code, but it can be used
919: to give memory back to the heap, or to increase the space of a
920: variable to avoid repeated automatic re-allocation.
921:
922: - Function: void mpz_array_init (mpz_t INTEGER_ARRAY[], size_t
923: ARRAY_SIZE, mp_size_t FIXED_NUM_BITS)
924: Allocate *fixed* limb space for all ARRAY_SIZE integers in
925: INTEGER_ARRAY. The fixed allocation for each integer in the array
926: is enough to store FIXED_NUM_BITS. If the fixed space will be
927: insufficient for storing the result of a subsequent calculation,
928: the result is unpredictable.
929:
930: This function is useful for decreasing the working set for some
931: algorithms that use large integer arrays.
932:
933: There is no way to de-allocate the storage allocated by this
934: function. Don't call `mpz_clear'!
935:
936:
937: File: gmp.info, Node: Assigning Integers, Next: Simultaneous Integer Init & Assign, Prev: Initializing Integers, Up: Integer Functions
938:
939: Assignment Functions
1.1.1.2 ! maekawa 940: ====================
1.1 maekawa 941:
942: These functions assign new values to already initialized integers
1.1.1.2 ! maekawa 943: (*note Initializing Integers::).
1.1 maekawa 944:
945: - Function: void mpz_set (mpz_t ROP, mpz_t OP)
946: - Function: void mpz_set_ui (mpz_t ROP, unsigned long int OP)
947: - Function: void mpz_set_si (mpz_t ROP, signed long int OP)
948: - Function: void mpz_set_d (mpz_t ROP, double OP)
949: - Function: void mpz_set_q (mpz_t ROP, mpq_t OP)
950: - Function: void mpz_set_f (mpz_t ROP, mpf_t OP)
951: Set the value of ROP from OP.
952:
953: - Function: int mpz_set_str (mpz_t ROP, char *STR, int BASE)
954: Set the value of ROP from STR, a '\0'-terminated C string in base
955: BASE. White space is allowed in the string, and is simply
956: ignored. The base may vary from 2 to 36. If BASE is 0, the
957: actual base is determined from the leading characters: if the
958: first two characters are `0x' or `0X', hexadecimal is assumed,
959: otherwise if the first character is `0', octal is assumed,
960: otherwise decimal is assumed.
961:
962: This function returns 0 if the entire string up to the '\0' is a
963: valid number in base BASE. Otherwise it returns -1.
964:
1.1.1.2 ! maekawa 965: [It turns out that it is not entirely true that this function
! 966: ignores white-space. It does ignore it between digits, but not
! 967: after a minus sign or within or after "0x". We are considering
! 968: changing the definition of this function, making it fail when
! 969: there is any white-space in the input, since that makes a lot of
! 970: sense. Please tell us your opinion about this change. Do you
! 971: really want it to accept "3 14" as meaning 314 as it does now?]
! 972:
! 973: - Function: void mpz_swap (mpz_t ROP1, mpz_t ROP2)
! 974: Swap the values ROP1 and ROP2 efficiently.
! 975:
1.1 maekawa 976:
977: File: gmp.info, Node: Simultaneous Integer Init & Assign, Next: Converting Integers, Prev: Assigning Integers, Up: Integer Functions
978:
979: Combined Initialization and Assignment Functions
1.1.1.2 ! maekawa 980: ================================================
1.1 maekawa 981:
1.1.1.2 ! maekawa 982: For convenience, GMP provides a parallel series of
! 983: initialize-and-set functions which initialize the output and then store
! 984: the value there. These functions' names have the form `mpz_init_set...'
1.1 maekawa 985:
986: Here is an example of using one:
987:
988: {
989: mpz_t pie;
990: mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10);
991: ...
992: mpz_sub (pie, ...);
993: ...
994: mpz_clear (pie);
995: }
996:
997: Once the integer has been initialized by any of the `mpz_init_set...'
998: functions, it can be used as the source or destination operand for the
999: ordinary integer functions. Don't use an initialize-and-set function
1000: on a variable already initialized!
1001:
1002: - Function: void mpz_init_set (mpz_t ROP, mpz_t OP)
1003: - Function: void mpz_init_set_ui (mpz_t ROP, unsigned long int OP)
1004: - Function: void mpz_init_set_si (mpz_t ROP, signed long int OP)
1005: - Function: void mpz_init_set_d (mpz_t ROP, double OP)
1006: Initialize ROP with limb space and set the initial numeric value
1007: from OP.
1008:
1009: - Function: int mpz_init_set_str (mpz_t ROP, char *STR, int BASE)
1010: Initialize ROP and set its value like `mpz_set_str' (see its
1011: documentation above for details).
1012:
1013: If the string is a correct base BASE number, the function returns
1014: 0; if an error occurs it returns -1. ROP is initialized even if
1015: an error occurs. (I.e., you have to call `mpz_clear' for it.)
1016:
1017:
1018: File: gmp.info, Node: Converting Integers, Next: Integer Arithmetic, Prev: Simultaneous Integer Init & Assign, Up: Integer Functions
1019:
1020: Conversion Functions
1021: ====================
1022:
1.1.1.2 ! maekawa 1023: This section describes functions for converting GMP integers to
! 1024: standard C types. Functions for converting _to_ GMP integers are
! 1025: described in *Note Assigning Integers:: and *Note I/O of Integers::.
! 1026:
! 1027: - Function: mp_limb_t mpz_getlimbn (mpz_t OP, mp_size_t N)
! 1028: Return limb #N from OP. This function allows for very efficient
! 1029: decomposition of a number in its limbs.
! 1030:
! 1031: The function `mpz_size' can be used to determine the useful range
! 1032: for N.
1.1 maekawa 1033:
1034: - Function: unsigned long int mpz_get_ui (mpz_t OP)
1035: Return the least significant part from OP. This function combined
1036: with
1037: `mpz_tdiv_q_2exp(..., OP, CHAR_BIT*sizeof(unsigned long int))' can
1.1.1.2 ! maekawa 1038: be used to decompose an integer into unsigned longs.
1.1 maekawa 1039:
1040: - Function: signed long int mpz_get_si (mpz_t OP)
1041: If OP fits into a `signed long int' return the value of OP.
1042: Otherwise return the least significant part of OP, with the same
1043: sign as OP.
1044:
1045: If OP is too large to fit in a `signed long int', the returned
1.1.1.2 ! maekawa 1046: result is probably not very useful. To find out if the value will
! 1047: fit, use the function `mpz_fits_slong_p'.
1.1 maekawa 1048:
1049: - Function: double mpz_get_d (mpz_t OP)
1050: Convert OP to a double.
1051:
1052: - Function: char * mpz_get_str (char *STR, int BASE, mpz_t OP)
1053: Convert OP to a string of digits in base BASE. The base may vary
1054: from 2 to 36.
1055:
1.1.1.2 ! maekawa 1056: If STR is `NULL', space for the result string is allocated using
! 1057: the default allocation function.
1.1 maekawa 1058:
1.1.1.2 ! maekawa 1059: If STR is not `NULL', it should point to a block of storage enough
1.1 maekawa 1060: large for the result. To find out the right amount of space to
1061: provide for STR, use `mpz_sizeinbase (OP, BASE) + 2'. The two
1062: extra bytes are for a possible minus sign, and for the terminating
1063: null character.
1064:
1.1.1.2 ! maekawa 1065: A pointer to the result string is returned. This pointer will
! 1066: will either equal STR, or if that is `NULL', will point to the
! 1067: allocated storage.
! 1068:
1.1 maekawa 1069:
1.1.1.2 ! maekawa 1070: File: gmp.info, Node: Integer Arithmetic, Next: Integer Division, Prev: Converting Integers, Up: Integer Functions
1.1 maekawa 1071:
1072: Arithmetic Functions
1073: ====================
1074:
1075: - Function: void mpz_add (mpz_t ROP, mpz_t OP1, mpz_t OP2)
1076: - Function: void mpz_add_ui (mpz_t ROP, mpz_t OP1, unsigned long int
1077: OP2)
1078: Set ROP to OP1 + OP2.
1079:
1080: - Function: void mpz_sub (mpz_t ROP, mpz_t OP1, mpz_t OP2)
1081: - Function: void mpz_sub_ui (mpz_t ROP, mpz_t OP1, unsigned long int
1082: OP2)
1083: Set ROP to OP1 - OP2.
1084:
1085: - Function: void mpz_mul (mpz_t ROP, mpz_t OP1, mpz_t OP2)
1.1.1.2 ! maekawa 1086: - Function: void mpz_mul_si (mpz_t ROP, mpz_t OP1, long int OP2)
1.1 maekawa 1087: - Function: void mpz_mul_ui (mpz_t ROP, mpz_t OP1, unsigned long int
1088: OP2)
1089: Set ROP to OP1 times OP2.
1090:
1.1.1.2 ! maekawa 1091: - Function: void mpz_addmul_ui (mpz_t ROP, mpz_t OP1, unsigned long
! 1092: int OP2)
! 1093: Add OP1 times OP2 to ROP.
! 1094:
1.1 maekawa 1095: - Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, unsigned long int
1096: OP2)
1097: Set ROP to OP1 times 2 raised to OP2. This operation can also be
1098: defined as a left shift, OP2 steps.
1099:
1100: - Function: void mpz_neg (mpz_t ROP, mpz_t OP)
1101: Set ROP to -OP.
1102:
1103: - Function: void mpz_abs (mpz_t ROP, mpz_t OP)
1104: Set ROP to the absolute value of OP.
1105:
1.1.1.2 ! maekawa 1106:
! 1107: File: gmp.info, Node: Integer Division, Next: Integer Exponentiation, Prev: Integer Arithmetic, Up: Integer Functions
1.1 maekawa 1108:
1.1.1.2 ! maekawa 1109: Division Functions
! 1110: ==================
1.1 maekawa 1111:
1112: Division is undefined if the divisor is zero, and passing a zero
1113: divisor to the divide or modulo functions, as well passing a zero mod
1114: argument to the `mpz_powm' and `mpz_powm_ui' functions, will make these
1.1.1.2 ! maekawa 1115: functions intentionally divide by zero. This lets the user handle
! 1116: arithmetic exceptions in these functions in the same manner as other
! 1117: arithmetic exceptions.
1.1 maekawa 1118:
1119: There are three main groups of division functions:
1.1.1.2 ! maekawa 1120: * Functions that truncate the quotient towards 0. The names of
! 1121: these functions start with `mpz_tdiv'. The `t' in the name is
! 1122: short for `truncate'.
1.1 maekawa 1123:
1.1.1.2 ! maekawa 1124: * Functions that round the quotient towards -infinity). The names
! 1125: of these routines start with `mpz_fdiv'. The `f' in the name is
1.1 maekawa 1126: short for `floor'.
1127:
1128: * Functions that round the quotient towards +infinity. The names of
1129: these routines start with `mpz_cdiv'. The `c' in the name is
1130: short for `ceil'.
1131:
1132: For each rounding mode, there are a couple of variants. Here `q'
1133: means that the quotient is computed, while `r' means that the remainder
1134: is computed. Functions that compute both the quotient and remainder
1135: have `qr' in the name.
1136:
1.1.1.2 ! maekawa 1137: - Function: void mpz_tdiv_q (mpz_t Q, mpz_t N, mpz_t D)
! 1138: - Function: unsigned long int mpz_tdiv_q_ui (mpz_t Q, mpz_t N,
! 1139: unsigned long int D)
! 1140: Set Q to [N/D], truncated towards 0.
! 1141:
! 1142: The function `mpz_tdiv_q_ui' returns the absolute value of the true
! 1143: remainder.
! 1144:
! 1145: - Function: void mpz_tdiv_r (mpz_t R, mpz_t N, mpz_t D)
! 1146: - Function: unsigned long int mpz_tdiv_r_ui (mpz_t R, mpz_t N,
! 1147: unsigned long int D)
! 1148: Set R to (N - [N/D] * D), where the quotient is truncated towards
! 1149: 0. Unless R becomes zero, it will get the same sign as N.
! 1150:
! 1151: The function `mpz_tdiv_r_ui' returns the absolute value of the
! 1152: remainder.
! 1153:
! 1154: - Function: void mpz_tdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D)
! 1155: - Function: unsigned long int mpz_tdiv_qr_ui (mpz_t Q, mpz_t R, mpz_t
! 1156: N, unsigned long int D)
! 1157: Set Q to [N/D], truncated towards 0. Set R to (N - [N/D] * D).
! 1158: Unless R becomes zero, it will get the same sign as N. If Q and R
! 1159: are the same variable, the results are undefined.
! 1160:
! 1161: The function `mpz_tdiv_qr_ui' returns the absolute value of the
! 1162: remainder.
! 1163:
! 1164: - Function: unsigned long int mpz_tdiv_ui (mpz_t N, unsigned long int
! 1165: D)
! 1166: Like `mpz_tdiv_r_ui', but the remainder is not stored anywhere; its
! 1167: absolute value is just returned.
! 1168:
! 1169: - Function: void mpz_fdiv_q (mpz_t Q, mpz_t N, mpz_t D)
! 1170: - Function: unsigned long int mpz_fdiv_q_ui (mpz_t Q, mpz_t N,
! 1171: unsigned long int D)
! 1172: Set Q to N/D, rounded towards -infinity.
! 1173:
! 1174: The function `mpz_fdiv_q_ui' returns the remainder.
! 1175:
! 1176: - Function: void mpz_fdiv_r (mpz_t R, mpz_t N, mpz_t D)
! 1177: - Function: unsigned long int mpz_fdiv_r_ui (mpz_t R, mpz_t N,
! 1178: unsigned long int D)
! 1179: Set R to (N - N/D * D), where the quotient is rounded towards
! 1180: -infinity. Unless R becomes zero, it will get the same sign as D.
! 1181:
! 1182: The function `mpz_fdiv_r_ui' returns the remainder.
! 1183:
! 1184: - Function: void mpz_fdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D)
! 1185: - Function: unsigned long int mpz_fdiv_qr_ui (mpz_t Q, mpz_t R, mpz_t
! 1186: N, unsigned long int D)
! 1187: Set Q to N/D, rounded towards -infinity. Set R to (N - N/D * D).
! 1188: Unless R becomes zero, it will get the same sign as D. If Q and R
! 1189: are the same variable, the results are undefined.
! 1190:
! 1191: The function `mpz_fdiv_qr_ui' returns the remainder.
! 1192:
! 1193: - Function: unsigned long int mpz_fdiv_ui (mpz_t N, unsigned long int
! 1194: D)
! 1195: Like `mpz_fdiv_r_ui', but the remainder is not stored anywhere; it
! 1196: is just returned.
! 1197:
! 1198: - Function: void mpz_cdiv_q (mpz_t Q, mpz_t N, mpz_t D)
! 1199: - Function: unsigned long int mpz_cdiv_q_ui (mpz_t Q, mpz_t N,
! 1200: unsigned long int D)
! 1201: Set Q to N/D, rounded towards +infinity.
! 1202:
! 1203: The function `mpz_cdiv_q_ui' returns the negated remainder.
! 1204:
! 1205: - Function: void mpz_cdiv_r (mpz_t R, mpz_t N, mpz_t D)
! 1206: - Function: unsigned long int mpz_cdiv_r_ui (mpz_t R, mpz_t N,
! 1207: unsigned long int D)
! 1208: Set R to (N - N/D * D), where the quotient is rounded towards
! 1209: +infinity. Unless R becomes zero, it will get the opposite sign
! 1210: as D.
! 1211:
! 1212: The function `mpz_cdiv_r_ui' returns the negated remainder.
! 1213:
! 1214: - Function: void mpz_cdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D)
! 1215: - Function: unsigned long int mpz_cdiv_qr_ui (mpz_t Q, mpz_t R, mpz_t
! 1216: N, unsigned long int D)
! 1217: Set Q to N/D, rounded towards +infinity. Set R to (N - N/D * D).
! 1218: Unless R becomes zero, it will get the opposite sign as D. If Q
! 1219: and R are the same variable, the results are undefined.
! 1220:
! 1221: The function `mpz_cdiv_qr_ui' returns the negated remainder.
! 1222:
! 1223: - Function: unsigned long int mpz_cdiv_ui (mpz_t N, unsigned long int
! 1224: D)
! 1225: Like `mpz_tdiv_r_ui', but the remainder is not stored anywhere; its
! 1226: negated value is just returned.
! 1227:
! 1228: - Function: void mpz_mod (mpz_t R, mpz_t N, mpz_t D)
! 1229: - Function: unsigned long int mpz_mod_ui (mpz_t R, mpz_t N, unsigned
! 1230: long int D)
! 1231: Set R to N `mod' D. The sign of the divisor is ignored; the
! 1232: result is always non-negative.
! 1233:
! 1234: The function `mpz_mod_ui' returns the remainder.
! 1235:
! 1236: - Function: void mpz_divexact (mpz_t Q, mpz_t N, mpz_t D)
! 1237: Set Q to N/D. This function produces correct results only when it
! 1238: is known in advance that D divides N.
1.1 maekawa 1239:
1240: Since mpz_divexact is much faster than any of the other routines
1.1.1.2 ! maekawa 1241: that produce the quotient (*note References:: Jebelean), it is the
! 1242: best choice for instances in which exact division is known to
1.1 maekawa 1243: occur, such as reducing a rational to lowest terms.
1244:
1.1.1.2 ! maekawa 1245: - Function: void mpz_tdiv_q_2exp (mpz_t Q, mpz_t N, unsigned long int
! 1246: D)
! 1247: Set Q to N divided by 2 raised to D. The quotient is truncated
! 1248: towards 0.
! 1249:
! 1250: - Function: void mpz_tdiv_r_2exp (mpz_t R, mpz_t N, unsigned long int
! 1251: D)
! 1252: Divide N by (2 raised to D), rounding the quotient towards 0, and
! 1253: put the remainder in R. Unless it is zero, R will have the same
! 1254: sign as N.
! 1255:
! 1256: - Function: void mpz_fdiv_q_2exp (mpz_t Q, mpz_t N, unsigned long int
! 1257: D)
! 1258: Set Q to N divided by 2 raised to D, rounded towards -infinity.
! 1259: This operation can also be defined as arithmetic right shift D bit
! 1260: positions.
! 1261:
! 1262: - Function: void mpz_fdiv_r_2exp (mpz_t R, mpz_t N, unsigned long int
! 1263: D)
! 1264: Divide N by (2 raised to D), rounding the quotient towards
! 1265: -infinity, and put the remainder in R. The sign of R will always
! 1266: be positive. This operation can also be defined as masking of the
! 1267: D least significant bits.
1.1 maekawa 1268:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gmp.info-1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gmp