1 This is ../../gmp/doc/gmp.info, produced by makeinfo version 4.13 from 2 ../../gmp/doc/gmp.texi. 3 4 This manual describes how to install and use the GNU multiple precision 5 arithmetic library, version 5.0.5. 6 7 Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 8 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 9 Free Software Foundation, Inc. 10 11 Permission is granted to copy, distribute and/or modify this 12 document under the terms of the GNU Free Documentation License, Version 13 1.3 or any later version published by the Free Software Foundation; 14 with no Invariant Sections, with the Front-Cover Texts being "A GNU 15 Manual", and with the Back-Cover Texts being "You have freedom to copy 16 and modify this GNU Manual, like GNU software". A copy of the license 17 is included in *note GNU Free Documentation License::. 18 19 INFO-DIR-SECTION GNU libraries 20 START-INFO-DIR-ENTRY 21 * gmp: (gmp). GNU Multiple Precision Arithmetic Library. 22 END-INFO-DIR-ENTRY 23 24 25 File: gmp.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) 26 27 GNU MP 28 ****** 29 30 This manual describes how to install and use the GNU multiple 31 precision arithmetic library, version 5.0.5. 32 33 Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 34 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 35 Free Software Foundation, Inc. 36 37 Permission is granted to copy, distribute and/or modify this 38 document under the terms of the GNU Free Documentation License, Version 39 1.3 or any later version published by the Free Software Foundation; 40 with no Invariant Sections, with the Front-Cover Texts being "A GNU 41 Manual", and with the Back-Cover Texts being "You have freedom to copy 42 and modify this GNU Manual, like GNU software". A copy of the license 43 is included in *note GNU Free Documentation License::. 44 45 46 * Menu: 47 48 * Copying:: GMP Copying Conditions (LGPL). 49 * Introduction to GMP:: Brief introduction to GNU MP. 50 * Installing GMP:: How to configure and compile the GMP library. 51 * GMP Basics:: What every GMP user should know. 52 * Reporting Bugs:: How to usefully report bugs. 53 * Integer Functions:: Functions for arithmetic on signed integers. 54 * Rational Number Functions:: Functions for arithmetic on rational numbers. 55 * Floating-point Functions:: Functions for arithmetic on floats. 56 * Low-level Functions:: Fast functions for natural numbers. 57 * Random Number Functions:: Functions for generating random numbers. 58 * Formatted Output:: `printf' style output. 59 * Formatted Input:: `scanf' style input. 60 * C++ Class Interface:: Class wrappers around GMP types. 61 * BSD Compatible Functions:: All functions found in BSD MP. 62 * Custom Allocation:: How to customize the internal allocation. 63 * Language Bindings:: Using GMP from other languages. 64 * Algorithms:: What happens behind the scenes. 65 * Internals:: How values are represented behind the scenes. 66 67 * Contributors:: Who brings you this library? 68 * References:: Some useful papers and books to read. 69 * GNU Free Documentation License:: 70 * Concept Index:: 71 * Function Index:: 72 73 74 File: gmp.info, Node: Copying, Next: Introduction to GMP, Prev: Top, Up: Top 75 76 GNU MP Copying Conditions 77 ************************* 78 79 This library is "free"; this means that everyone is free to use it and 80 free to redistribute it on a free basis. The library is not in the 81 public domain; it is copyrighted and there are restrictions on its 82 distribution, but these restrictions are designed to permit everything 83 that a good cooperating citizen would want to do. What is not allowed 84 is to try to prevent others from further sharing any version of this 85 library that they might get from you. 86 87 Specifically, we want to make sure that you have the right to give 88 away copies of the library, that you receive source code or else can 89 get it if you want it, that you can change this library or use pieces 90 of it in new free programs, and that you know you can do these things. 91 92 To make sure that everyone has such rights, we have to forbid you to 93 deprive anyone else of these rights. For example, if you distribute 94 copies of the GNU MP library, you must give the recipients all the 95 rights that you have. You must make sure that they, too, receive or 96 can get the source code. And you must tell them their rights. 97 98 Also, for our own protection, we must make certain that everyone 99 finds out that there is no warranty for the GNU MP library. If it is 100 modified by someone else and passed on, we want their recipients to 101 know that what they have is not what we distributed, so that any 102 problems introduced by others will not reflect on our reputation. 103 104 The precise conditions of the license for the GNU MP library are 105 found in the Lesser General Public License version 3 that accompanies 106 the source code, see `COPYING.LIB'. Certain demonstration programs are 107 provided under the terms of the plain General Public License version 3, 108 see `COPYING'. 109 110 111 File: gmp.info, Node: Introduction to GMP, Next: Installing GMP, Prev: Copying, Up: Top 112 113 1 Introduction to GNU MP 114 ************************ 115 116 GNU MP is a portable library written in C for arbitrary precision 117 arithmetic on integers, rational numbers, and floating-point numbers. 118 It aims to provide the fastest possible arithmetic for all applications 119 that need higher precision than is directly supported by the basic C 120 types. 121 122 Many applications use just a few hundred bits of precision; but some 123 applications may need thousands or even millions of bits. GMP is 124 designed to give good performance for both, by choosing algorithms 125 based on the sizes of the operands, and by carefully keeping the 126 overhead at a minimum. 127 128 The speed of GMP is achieved by using fullwords as the basic 129 arithmetic type, by using sophisticated algorithms, by including 130 carefully optimized assembly code for the most common inner loops for 131 many different CPUs, and by a general emphasis on speed (as opposed to 132 simplicity or elegance). 133 134 There is assembly code for these CPUs: ARM, DEC Alpha 21064, 21164, 135 and 21264, AMD 29000, AMD K6, K6-2, Athlon, and Athlon64, Hitachi 136 SuperH and SH-2, HPPA 1.0, 1.1 and 2.0, Intel Pentium, Pentium 137 Pro/II/III, Pentium 4, generic x86, Intel IA-64, i960, Motorola 138 MC68000, MC68020, MC88100, and MC88110, Motorola/IBM PowerPC 32 and 64, 139 National NS32000, IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC, 140 generic SPARCv8, UltraSPARC, DEC VAX, and Zilog Z8000. Some 141 optimizations also for Cray vector systems, Clipper, IBM ROMP (RT), and 142 Pyramid AP/XP. 143 144 For up-to-date information on GMP, please see the GMP web pages at 145 146 `http://gmplib.org/' 147 148 The latest version of the library is available at 149 150 `ftp://ftp.gnu.org/gnu/gmp/' 151 152 Many sites around the world mirror `ftp.gnu.org', please use a mirror 153 near you, see `http://www.gnu.org/order/ftp.html' for a full list. 154 155 There are three public mailing lists of interest. One for release 156 announcements, one for general questions and discussions about usage of 157 the GMP library and one for bug reports. For more information, see 158 159 `http://gmplib.org/mailman/listinfo/'. 160 161 The proper place for bug reports is <gmp-bugs (a] gmplib.org>. See 162 *note Reporting Bugs:: for information about reporting bugs. 163 164 165 1.1 How to use this Manual 166 ========================== 167 168 Everyone should read *note GMP Basics::. If you need to install the 169 library yourself, then read *note Installing GMP::. If you have a 170 system with multiple ABIs, then read *note ABI and ISA::, for the 171 compiler options that must be used on applications. 172 173 The rest of the manual can be used for later reference, although it 174 is probably a good idea to glance through it. 175 176 177 File: gmp.info, Node: Installing GMP, Next: GMP Basics, Prev: Introduction to GMP, Up: Top 178 179 2 Installing GMP 180 **************** 181 182 GMP has an autoconf/automake/libtool based configuration system. On a 183 Unix-like system a basic build can be done with 184 185 ./configure 186 make 187 188 Some self-tests can be run with 189 190 make check 191 192 And you can install (under `/usr/local' by default) with 193 194 make install 195 196 If you experience problems, please report them to 197 <gmp-bugs (a] gmplib.org>. See *note Reporting Bugs::, for information on 198 what to include in useful bug reports. 199 200 * Menu: 201 202 * Build Options:: 203 * ABI and ISA:: 204 * Notes for Package Builds:: 205 * Notes for Particular Systems:: 206 * Known Build Problems:: 207 * Performance optimization:: 208 209 210 File: gmp.info, Node: Build Options, Next: ABI and ISA, Prev: Installing GMP, Up: Installing GMP 211 212 2.1 Build Options 213 ================= 214 215 All the usual autoconf configure options are available, run `./configure 216 --help' for a summary. The file `INSTALL.autoconf' has some generic 217 installation information too. 218 219 Tools 220 `configure' requires various Unix-like tools. See *note Notes for 221 Particular Systems::, for some options on non-Unix systems. 222 223 It might be possible to build without the help of `configure', 224 certainly all the code is there, but unfortunately you'll be on 225 your own. 226 227 Build Directory 228 To compile in a separate build directory, `cd' to that directory, 229 and prefix the configure command with the path to the GMP source 230 directory. For example 231 232 cd /my/build/dir 233 /my/sources/gmp-5.0.5/configure 234 235 Not all `make' programs have the necessary features (`VPATH') to 236 support this. In particular, SunOS and Slowaris `make' have bugs 237 that make them unable to build in a separate directory. Use GNU 238 `make' instead. 239 240 `--prefix' and `--exec-prefix' 241 The `--prefix' option can be used in the normal way to direct GMP 242 to install under a particular tree. The default is `/usr/local'. 243 244 `--exec-prefix' can be used to direct architecture-dependent files 245 like `libgmp.a' to a different location. This can be used to share 246 architecture-independent parts like the documentation, but 247 separate the dependent parts. Note however that `gmp.h' and 248 `mp.h' are architecture-dependent since they encode certain 249 aspects of `libgmp', so it will be necessary to ensure both 250 `$prefix/include' and `$exec_prefix/include' are available to the 251 compiler. 252 253 `--disable-shared', `--disable-static' 254 By default both shared and static libraries are built (where 255 possible), but one or other can be disabled. Shared libraries 256 result in smaller executables and permit code sharing between 257 separate running processes, but on some CPUs are slightly slower, 258 having a small cost on each function call. 259 260 Native Compilation, `--build=CPU-VENDOR-OS' 261 For normal native compilation, the system can be specified with 262 `--build'. By default `./configure' uses the output from running 263 `./config.guess'. On some systems `./config.guess' can determine 264 the exact CPU type, on others it will be necessary to give it 265 explicitly. For example, 266 267 ./configure --build=ultrasparc-sun-solaris2.7 268 269 In all cases the `OS' part is important, since it controls how 270 libtool generates shared libraries. Running `./config.guess' is 271 the simplest way to see what it should be, if you don't know 272 already. 273 274 Cross Compilation, `--host=CPU-VENDOR-OS' 275 When cross-compiling, the system used for compiling is given by 276 `--build' and the system where the library will run is given by 277 `--host'. For example when using a FreeBSD Athlon system to build 278 GNU/Linux m68k binaries, 279 280 ./configure --build=athlon-pc-freebsd3.5 --host=m68k-mac-linux-gnu 281 282 Compiler tools are sought first with the host system type as a 283 prefix. For example `m68k-mac-linux-gnu-ranlib' is tried, then 284 plain `ranlib'. This makes it possible for a set of 285 cross-compiling tools to co-exist with native tools. The prefix 286 is the argument to `--host', and this can be an alias, such as 287 `m68k-linux'. But note that tools don't have to be setup this 288 way, it's enough to just have a `PATH' with a suitable 289 cross-compiling `cc' etc. 290 291 Compiling for a different CPU in the same family as the build 292 system is a form of cross-compilation, though very possibly this 293 would merely be special options on a native compiler. In any case 294 `./configure' avoids depending on being able to run code on the 295 build system, which is important when creating binaries for a 296 newer CPU since they very possibly won't run on the build system. 297 298 In all cases the compiler must be able to produce an executable 299 (of whatever format) from a standard C `main'. Although only 300 object files will go to make up `libgmp', `./configure' uses 301 linking tests for various purposes, such as determining what 302 functions are available on the host system. 303 304 Currently a warning is given unless an explicit `--build' is used 305 when cross-compiling, because it may not be possible to correctly 306 guess the build system type if the `PATH' has only a 307 cross-compiling `cc'. 308 309 Note that the `--target' option is not appropriate for GMP. It's 310 for use when building compiler tools, with `--host' being where 311 they will run, and `--target' what they'll produce code for. 312 Ordinary programs or libraries like GMP are only interested in the 313 `--host' part, being where they'll run. (Some past versions of 314 GMP used `--target' incorrectly.) 315 316 CPU types 317 In general, if you want a library that runs as fast as possible, 318 you should configure GMP for the exact CPU type your system uses. 319 However, this may mean the binaries won't run on older members of 320 the family, and might run slower on other members, older or newer. 321 The best idea is always to build GMP for the exact machine type 322 you intend to run it on. 323 324 The following CPUs have specific support. See `configure.in' for 325 details of what code and compiler options they select. 326 327 * Alpha: alpha, alphaev5, alphaev56, alphapca56, alphapca57, 328 alphaev6, alphaev67, alphaev68 alphaev7 329 330 * Cray: c90, j90, t90, sv1 331 332 * HPPA: hppa1.0, hppa1.1, hppa2.0, hppa2.0n, hppa2.0w, hppa64 333 334 * IA-64: ia64, itanium, itanium2 335 336 * MIPS: mips, mips3, mips64 337 338 * Motorola: m68k, m68000, m68010, m68020, m68030, m68040, 339 m68060, m68302, m68360, m88k, m88110 340 341 * POWER: power, power1, power2, power2sc 342 343 * PowerPC: powerpc, powerpc64, powerpc401, powerpc403, 344 powerpc405, powerpc505, powerpc601, powerpc602, powerpc603, 345 powerpc603e, powerpc604, powerpc604e, powerpc620, powerpc630, 346 powerpc740, powerpc7400, powerpc7450, powerpc750, powerpc801, 347 powerpc821, powerpc823, powerpc860, powerpc970 348 349 * SPARC: sparc, sparcv8, microsparc, supersparc, sparcv9, 350 ultrasparc, ultrasparc2, ultrasparc2i, ultrasparc3, sparc64 351 352 * x86 family: i386, i486, i586, pentium, pentiummmx, pentiumpro, 353 pentium2, pentium3, pentium4, k6, k62, k63, athlon, amd64, 354 viac3, viac32 355 356 * Other: a29k, arm, clipper, i960, ns32k, pyramid, sh, sh2, vax, 357 z8k 358 359 CPUs not listed will use generic C code. 360 361 Generic C Build 362 If some of the assembly code causes problems, or if otherwise 363 desired, the generic C code can be selected with CPU `none'. For 364 example, 365 366 ./configure --host=none-unknown-freebsd3.5 367 368 Note that this will run quite slowly, but it should be portable 369 and should at least make it possible to get something running if 370 all else fails. 371 372 Fat binary, `--enable-fat' 373 Using `--enable-fat' selects a "fat binary" build on x86, where 374 optimized low level subroutines are chosen at runtime according to 375 the CPU detected. This means more code, but gives good 376 performance on all x86 chips. (This option might become available 377 for more architectures in the future.) 378 379 `ABI' 380 On some systems GMP supports multiple ABIs (application binary 381 interfaces), meaning data type sizes and calling conventions. By 382 default GMP chooses the best ABI available, but a particular ABI 383 can be selected. For example 384 385 ./configure --host=mips64-sgi-irix6 ABI=n32 386 387 See *note ABI and ISA::, for the available choices on relevant 388 CPUs, and what applications need to do. 389 390 `CC', `CFLAGS' 391 By default the C compiler used is chosen from among some likely 392 candidates, with `gcc' normally preferred if it's present. The 393 usual `CC=whatever' can be passed to `./configure' to choose 394 something different. 395 396 For various systems, default compiler flags are set based on the 397 CPU and compiler. The usual `CFLAGS="-whatever"' can be passed to 398 `./configure' to use something different or to set good flags for 399 systems GMP doesn't otherwise know. 400 401 The `CC' and `CFLAGS' used are printed during `./configure', and 402 can be found in each generated `Makefile'. This is the easiest way 403 to check the defaults when considering changing or adding 404 something. 405 406 Note that when `CC' and `CFLAGS' are specified on a system 407 supporting multiple ABIs it's important to give an explicit 408 `ABI=whatever', since GMP can't determine the ABI just from the 409 flags and won't be able to select the correct assembly code. 410 411 If just `CC' is selected then normal default `CFLAGS' for that 412 compiler will be used (if GMP recognises it). For example 413 `CC=gcc' can be used to force the use of GCC, with default flags 414 (and default ABI). 415 416 `CPPFLAGS' 417 Any flags like `-D' defines or `-I' includes required by the 418 preprocessor should be set in `CPPFLAGS' rather than `CFLAGS'. 419 Compiling is done with both `CPPFLAGS' and `CFLAGS', but 420 preprocessing uses just `CPPFLAGS'. This distinction is because 421 most preprocessors won't accept all the flags the compiler does. 422 Preprocessing is done separately in some configure tests, and in 423 the `ansi2knr' support for K&R compilers. 424 425 `CC_FOR_BUILD' 426 Some build-time programs are compiled and run to generate 427 host-specific data tables. `CC_FOR_BUILD' is the compiler used 428 for this. It doesn't need to be in any particular ABI or mode, it 429 merely needs to generate executables that can run. The default is 430 to try the selected `CC' and some likely candidates such as `cc' 431 and `gcc', looking for something that works. 432 433 No flags are used with `CC_FOR_BUILD' because a simple invocation 434 like `cc foo.c' should be enough. If some particular options are 435 required they can be included as for instance `CC_FOR_BUILD="cc 436 -whatever"'. 437 438 C++ Support, `--enable-cxx' 439 C++ support in GMP can be enabled with `--enable-cxx', in which 440 case a C++ compiler will be required. As a convenience 441 `--enable-cxx=detect' can be used to enable C++ support only if a 442 compiler can be found. The C++ support consists of a library 443 `libgmpxx.la' and header file `gmpxx.h' (*note Headers and 444 Libraries::). 445 446 A separate `libgmpxx.la' has been adopted rather than having C++ 447 objects within `libgmp.la' in order to ensure dynamic linked C 448 programs aren't bloated by a dependency on the C++ standard 449 library, and to avoid any chance that the C++ compiler could be 450 required when linking plain C programs. 451 452 `libgmpxx.la' will use certain internals from `libgmp.la' and can 453 only be expected to work with `libgmp.la' from the same GMP 454 version. Future changes to the relevant internals will be 455 accompanied by renaming, so a mismatch will cause unresolved 456 symbols rather than perhaps mysterious misbehaviour. 457 458 In general `libgmpxx.la' will be usable only with the C++ compiler 459 that built it, since name mangling and runtime support are usually 460 incompatible between different compilers. 461 462 `CXX', `CXXFLAGS' 463 When C++ support is enabled, the C++ compiler and its flags can be 464 set with variables `CXX' and `CXXFLAGS' in the usual way. The 465 default for `CXX' is the first compiler that works from a list of 466 likely candidates, with `g++' normally preferred when available. 467 The default for `CXXFLAGS' is to try `CFLAGS', `CFLAGS' without 468 `-g', then for `g++' either `-g -O2' or `-O2', or for other 469 compilers `-g' or nothing. Trying `CFLAGS' this way is convenient 470 when using `gcc' and `g++' together, since the flags for `gcc' will 471 usually suit `g++'. 472 473 It's important that the C and C++ compilers match, meaning their 474 startup and runtime support routines are compatible and that they 475 generate code in the same ABI (if there's a choice of ABIs on the 476 system). `./configure' isn't currently able to check these things 477 very well itself, so for that reason `--disable-cxx' is the 478 default, to avoid a build failure due to a compiler mismatch. 479 Perhaps this will change in the future. 480 481 Incidentally, it's normally not good enough to set `CXX' to the 482 same as `CC'. Although `gcc' for instance recognises `foo.cc' as 483 C++ code, only `g++' will invoke the linker the right way when 484 building an executable or shared library from C++ object files. 485 486 Temporary Memory, `--enable-alloca=<choice>' 487 GMP allocates temporary workspace using one of the following three 488 methods, which can be selected with for instance 489 `--enable-alloca=malloc-reentrant'. 490 491 * `alloca' - C library or compiler builtin. 492 493 * `malloc-reentrant' - the heap, in a re-entrant fashion. 494 495 * `malloc-notreentrant' - the heap, with global variables. 496 497 For convenience, the following choices are also available. 498 `--disable-alloca' is the same as `no'. 499 500 * `yes' - a synonym for `alloca'. 501 502 * `no' - a synonym for `malloc-reentrant'. 503 504 * `reentrant' - `alloca' if available, otherwise 505 `malloc-reentrant'. This is the default. 506 507 * `notreentrant' - `alloca' if available, otherwise 508 `malloc-notreentrant'. 509 510 `alloca' is reentrant and fast, and is recommended. It actually 511 allocates just small blocks on the stack; larger ones use 512 malloc-reentrant. 513 514 `malloc-reentrant' is, as the name suggests, reentrant and thread 515 safe, but `malloc-notreentrant' is faster and should be used if 516 reentrancy is not required. 517 518 The two malloc methods in fact use the memory allocation functions 519 selected by `mp_set_memory_functions', these being `malloc' and 520 friends by default. *Note Custom Allocation::. 521 522 An additional choice `--enable-alloca=debug' is available, to help 523 when debugging memory related problems (*note Debugging::). 524 525 FFT Multiplication, `--disable-fft' 526 By default multiplications are done using Karatsuba, 3-way Toom, 527 higher degree Toom, and Fermat FFT. The FFT is only used on large 528 to very large operands and can be disabled to save code size if 529 desired. 530 531 Berkeley MP, `--enable-mpbsd' 532 The Berkeley MP compatibility library (`libmp') and header file 533 (`mp.h') are built and installed only if `--enable-mpbsd' is used. 534 *Note BSD Compatible Functions::. 535 536 Assertion Checking, `--enable-assert' 537 This option enables some consistency checking within the library. 538 This can be of use while debugging, *note Debugging::. 539 540 Execution Profiling, `--enable-profiling=prof/gprof/instrument' 541 Enable profiling support, in one of various styles, *note 542 Profiling::. 543 544 `MPN_PATH' 545 Various assembly versions of each mpn subroutines are provided. 546 For a given CPU, a search is made though a path to choose a 547 version of each. For example `sparcv8' has 548 549 MPN_PATH="sparc32/v8 sparc32 generic" 550 551 which means look first for v8 code, then plain sparc32 (which is 552 v7), and finally fall back on generic C. Knowledgeable users with 553 special requirements can specify a different path. Normally this 554 is completely unnecessary. 555 556 Documentation 557 The source for the document you're now reading is `doc/gmp.texi', 558 in Texinfo format, see *note Texinfo: (texinfo)Top. 559 560 Info format `doc/gmp.info' is included in the distribution. The 561 usual automake targets are available to make PostScript, DVI, PDF 562 and HTML (these will require various TeX and Texinfo tools). 563 564 DocBook and XML can be generated by the Texinfo `makeinfo' program 565 too, see *note Options for `makeinfo': (texinfo)makeinfo options. 566 567 Some supplementary notes can also be found in the `doc' 568 subdirectory. 569 570 571 572 File: gmp.info, Node: ABI and ISA, Next: Notes for Package Builds, Prev: Build Options, Up: Installing GMP 573 574 2.2 ABI and ISA 575 =============== 576 577 ABI (Application Binary Interface) refers to the calling conventions 578 between functions, meaning what registers are used and what sizes the 579 various C data types are. ISA (Instruction Set Architecture) refers to 580 the instructions and registers a CPU has available. 581 582 Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI 583 defined, the latter for compatibility with older CPUs in the family. 584 GMP supports some CPUs like this in both ABIs. In fact within GMP 585 `ABI' means a combination of chip ABI, plus how GMP chooses to use it. 586 For example in some 32-bit ABIs, GMP may support a limb as either a 587 32-bit `long' or a 64-bit `long long'. 588 589 By default GMP chooses the best ABI available for a given system, 590 and this generally gives significantly greater speed. But an ABI can 591 be chosen explicitly to make GMP compatible with other libraries, or 592 particular application requirements. For example, 593 594 ./configure ABI=32 595 596 In all cases it's vital that all object code used in a given program 597 is compiled for the same ABI. 598 599 Usually a limb is implemented as a `long'. When a `long long' limb 600 is used this is encoded in the generated `gmp.h'. This is convenient 601 for applications, but it does mean that `gmp.h' will vary, and can't be 602 just copied around. `gmp.h' remains compiler independent though, since 603 all compilers for a particular ABI will be expected to use the same 604 limb type. 605 606 Currently no attempt is made to follow whatever conventions a system 607 has for installing library or header files built for a particular ABI. 608 This will probably only matter when installing multiple builds of GMP, 609 and it might be as simple as configuring with a special `libdir', or it 610 might require more than that. Note that builds for different ABIs need 611 to done separately, with a fresh `./configure' and `make' each. 612 613 614 AMD64 (`x86_64') 615 On AMD64 systems supporting both 32-bit and 64-bit modes for 616 applications, the following ABI choices are available. 617 618 `ABI=64' 619 The 64-bit ABI uses 64-bit limbs and pointers and makes full 620 use of the chip architecture. This is the default. 621 Applications will usually not need special compiler flags, 622 but for reference the option is 623 624 gcc -m64 625 626 `ABI=32' 627 The 32-bit ABI is the usual i386 conventions. This will be 628 slower, and is not recommended except for inter-operating 629 with other code not yet 64-bit capable. Applications must be 630 compiled with 631 632 gcc -m32 633 634 (In GCC 2.95 and earlier there's no `-m32' option, it's the 635 only mode.) 636 637 638 HPPA 2.0 (`hppa2.0*', `hppa64') 639 640 `ABI=2.0w' 641 The 2.0w ABI uses 64-bit limbs and pointers and is available 642 on HP-UX 11 or up. Applications must be compiled with 643 644 gcc [built for 2.0w] 645 cc +DD64 646 647 `ABI=2.0n' 648 The 2.0n ABI means the 32-bit HPPA 1.0 ABI and all its normal 649 calling conventions, but with 64-bit instructions permitted 650 within functions. GMP uses a 64-bit `long long' for a limb. 651 This ABI is available on hppa64 GNU/Linux and on HP-UX 10 or 652 higher. Applications must be compiled with 653 654 gcc [built for 2.0n] 655 cc +DA2.0 +e 656 657 Note that current versions of GCC (eg. 3.2) don't generate 658 64-bit instructions for `long long' operations and so may be 659 slower than for 2.0w. (The GMP assembly code is the same 660 though.) 661 662 `ABI=1.0' 663 HPPA 2.0 CPUs can run all HPPA 1.0 and 1.1 code in the 32-bit 664 HPPA 1.0 ABI. No special compiler options are needed for 665 applications. 666 667 All three ABIs are available for CPU types `hppa2.0w', `hppa2.0' 668 and `hppa64', but for CPU type `hppa2.0n' only 2.0n or 1.0 are 669 considered. 670 671 Note that GCC on HP-UX has no options to choose between 2.0n and 672 2.0w modes, unlike HP `cc'. Instead it must be built for one or 673 the other ABI. GMP will detect how it was built, and skip to the 674 corresponding `ABI'. 675 676 677 IA-64 under HP-UX (`ia64*-*-hpux*', `itanium*-*-hpux*') 678 HP-UX supports two ABIs for IA-64. GMP performance is the same in 679 both. 680 681 `ABI=32' 682 In the 32-bit ABI, pointers, `int's and `long's are 32 bits 683 and GMP uses a 64 bit `long long' for a limb. Applications 684 can be compiled without any special flags since this ABI is 685 the default in both HP C and GCC, but for reference the flags 686 are 687 688 gcc -milp32 689 cc +DD32 690 691 `ABI=64' 692 In the 64-bit ABI, `long's and pointers are 64 bits and GMP 693 uses a `long' for a limb. Applications must be compiled with 694 695 gcc -mlp64 696 cc +DD64 697 698 On other IA-64 systems, GNU/Linux for instance, `ABI=64' is the 699 only choice. 700 701 702 MIPS under IRIX 6 (`mips*-*-irix[6789]') 703 IRIX 6 always has a 64-bit MIPS 3 or better CPU, and supports ABIs 704 o32, n32, and 64. n32 or 64 are recommended, and GMP performance 705 will be the same in each. The default is n32. 706 707 `ABI=o32' 708 The o32 ABI is 32-bit pointers and integers, and no 64-bit 709 operations. GMP will be slower than in n32 or 64, this 710 option only exists to support old compilers, eg. GCC 2.7.2. 711 Applications can be compiled with no special flags on an old 712 compiler, or on a newer compiler with 713 714 gcc -mabi=32 715 cc -32 716 717 `ABI=n32' 718 The n32 ABI is 32-bit pointers and integers, but with a 719 64-bit limb using a `long long'. Applications must be 720 compiled with 721 722 gcc -mabi=n32 723 cc -n32 724 725 `ABI=64' 726 The 64-bit ABI is 64-bit pointers and integers. Applications 727 must be compiled with 728 729 gcc -mabi=64 730 cc -64 731 732 Note that MIPS GNU/Linux, as of kernel version 2.2, doesn't have 733 the necessary support for n32 or 64 and so only gets a 32-bit limb 734 and the MIPS 2 code. 735 736 737 PowerPC 64 (`powerpc64', `powerpc620', `powerpc630', `powerpc970', `power4', `power5') 738 739 `ABI=aix64' 740 The AIX 64 ABI uses 64-bit limbs and pointers and is the 741 default on PowerPC 64 `*-*-aix*' systems. Applications must 742 be compiled with 743 744 gcc -maix64 745 xlc -q64 746 747 `ABI=mode64' 748 The `mode64' ABI uses 64-bit limbs and pointers, and is the 749 default on 64-bit GNU/Linux, BSD, and Mac OS X/Darwin 750 systems. Applications must be compiled with 751 752 gcc -m64 753 754 `ABI=mode32' 755 The `mode32' ABI uses a 64-bit `long long' limb but with the 756 chip still in 32-bit mode and using 32-bit calling 757 conventions. This is the default for systems where the true 758 64-bit ABI is unavailable. No special compiler options are 759 typically needed for applications. 760 761 `ABI=32' 762 This is the basic 32-bit PowerPC ABI, with a 32-bit limb. No 763 special compiler options are needed for applications. 764 765 GMP's speed is greatest for `aix64' and `mode64'. In `ABI=32' 766 only the 32-bit ISA is used and this doesn't make full use of a 767 64-bit chip. On a suitable system we could perhaps use more of 768 the ISA, but there are no plans to do so. 769 770 771 Sparc V9 (`sparc64', `sparcv9', `ultrasparc*') 772 773 `ABI=64' 774 The 64-bit V9 ABI is available on the various BSD sparc64 775 ports, recent versions of Sparc64 GNU/Linux, and Solaris 2.7 776 and up (when the kernel is in 64-bit mode). GCC 3.2 or 777 higher, or Sun `cc' is required. On GNU/Linux, depending on 778 the default `gcc' mode, applications must be compiled with 779 780 gcc -m64 781 782 On Solaris applications must be compiled with 783 784 gcc -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9 785 cc -xarch=v9 786 787 On the BSD sparc64 systems no special options are required, 788 since 64-bits is the only ABI available. 789 790 `ABI=32' 791 For the basic 32-bit ABI, GMP still uses as much of the V9 792 ISA as it can. In the Sun documentation this combination is 793 known as "v8plus". On GNU/Linux, depending on the default 794 `gcc' mode, applications may need to be compiled with 795 796 gcc -m32 797 798 On Solaris, no special compiler options are required for 799 applications, though using something like the following is 800 recommended. (`gcc' 2.8 and earlier only support `-mv8' 801 though.) 802 803 gcc -mv8plus 804 cc -xarch=v8plus 805 806 GMP speed is greatest in `ABI=64', so it's the default where 807 available. The speed is partly because there are extra registers 808 available and partly because 64-bits is considered the more 809 important case and has therefore had better code written for it. 810 811 Don't be confused by the names of the `-m' and `-x' compiler 812 options, they're called `arch' but effectively control both ABI 813 and ISA. 814 815 On Solaris 2.6 and earlier, only `ABI=32' is available since the 816 kernel doesn't save all registers. 817 818 On Solaris 2.7 with the kernel in 32-bit mode, a normal native 819 build will reject `ABI=64' because the resulting executables won't 820 run. `ABI=64' can still be built if desired by making it look 821 like a cross-compile, for example 822 823 ./configure --build=none --host=sparcv9-sun-solaris2.7 ABI=64 824 825 826 File: gmp.info, Node: Notes for Package Builds, Next: Notes for Particular Systems, Prev: ABI and ISA, Up: Installing GMP 827 828 2.3 Notes for Package Builds 829 ============================ 830 831 GMP should present no great difficulties for packaging in a binary 832 distribution. 833 834 Libtool is used to build the library and `-version-info' is set 835 appropriately, having started from `3:0:0' in GMP 3.0 (*note Library 836 interface versions: (libtool)Versioning.). 837 838 The GMP 4 series will be upwardly binary compatible in each release 839 and will be upwardly binary compatible with all of the GMP 3 series. 840 Additional function interfaces may be added in each release, so on 841 systems where libtool versioning is not fully checked by the loader an 842 auxiliary mechanism may be needed to express that a dynamic linked 843 application depends on a new enough GMP. 844 845 An auxiliary mechanism may also be needed to express that 846 `libgmpxx.la' (from `--enable-cxx', *note Build Options::) requires 847 `libgmp.la' from the same GMP version, since this is not done by the 848 libtool versioning, nor otherwise. A mismatch will result in 849 unresolved symbols from the linker, or perhaps the loader. 850 851 When building a package for a CPU family, care should be taken to use 852 `--host' (or `--build') to choose the least common denominator among 853 the CPUs which might use the package. For example this might mean plain 854 `sparc' (meaning V7) for SPARCs. 855 856 For x86s, `--enable-fat' sets things up for a fat binary build, 857 making a runtime selection of optimized low level routines. This is a 858 good choice for packaging to run on a range of x86 chips. 859 860 Users who care about speed will want GMP built for their exact CPU 861 type, to make best use of the available optimizations. Providing a way 862 to suitably rebuild a package may be useful. This could be as simple 863 as making it possible for a user to omit `--build' (and `--host') so 864 `./config.guess' will detect the CPU. But a way to manually specify a 865 `--build' will be wanted for systems where `./config.guess' is inexact. 866 867 On systems with multiple ABIs, a packaged build will need to decide 868 which among the choices is to be provided, see *note ABI and ISA::. A 869 given run of `./configure' etc will only build one ABI. If a second 870 ABI is also required then a second run of `./configure' etc must be 871 made, starting from a clean directory tree (`make distclean'). 872 873 As noted under "ABI and ISA", currently no attempt is made to follow 874 system conventions for install locations that vary with ABI, such as 875 `/usr/lib/sparcv9' for `ABI=64' as opposed to `/usr/lib' for `ABI=32'. 876 A package build can override `libdir' and other standard variables as 877 necessary. 878 879 Note that `gmp.h' is a generated file, and will be architecture and 880 ABI dependent. When attempting to install two ABIs simultaneously it 881 will be important that an application compile gets the correct `gmp.h' 882 for its desired ABI. If compiler include paths don't vary with ABI 883 options then it might be necessary to create a `/usr/include/gmp.h' 884 which tests preprocessor symbols and chooses the correct actual `gmp.h'. 885 886 887 File: gmp.info, Node: Notes for Particular Systems, Next: Known Build Problems, Prev: Notes for Package Builds, Up: Installing GMP 888 889 2.4 Notes for Particular Systems 890 ================================ 891 892 AIX 3 and 4 893 On systems `*-*-aix[34]*' shared libraries are disabled by 894 default, since some versions of the native `ar' fail on the 895 convenience libraries used. A shared build can be attempted with 896 897 ./configure --enable-shared --disable-static 898 899 Note that the `--disable-static' is necessary because in a shared 900 build libtool makes `libgmp.a' a symlink to `libgmp.so', 901 apparently for the benefit of old versions of `ld' which only 902 recognise `.a', but unfortunately this is done even if a fully 903 functional `ld' is available. 904 905 ARM 906 On systems `arm*-*-*', versions of GCC up to and including 2.95.3 907 have a bug in unsigned division, giving wrong results for some 908 operands. GMP `./configure' will demand GCC 2.95.4 or later. 909 910 Compaq C++ 911 Compaq C++ on OSF 5.1 has two flavours of `iostream', a standard 912 one and an old pre-standard one (see `man iostream_intro'). GMP 913 can only use the standard one, which unfortunately is not the 914 default but must be selected by defining `__USE_STD_IOSTREAM'. 915 Configure with for instance 916 917 ./configure --enable-cxx CPPFLAGS=-D__USE_STD_IOSTREAM 918 919 Floating Point Mode 920 On some systems, the hardware floating point has a control mode 921 which can set all operations to be done in a particular precision, 922 for instance single, double or extended on x86 systems (x87 923 floating point). The GMP functions involving a `double' cannot be 924 expected to operate to their full precision when the hardware is 925 in single precision mode. Of course this affects all code, 926 including application code, not just GMP. 927 928 MS-DOS and MS Windows 929 On an MS-DOS system DJGPP can be used to build GMP, and on an MS 930 Windows system Cygwin, DJGPP and MINGW can be used. All three are 931 excellent ports of GCC and the various GNU tools. 932 933 `http://www.cygwin.com/' 934 `http://www.delorie.com/djgpp/' 935 `http://www.mingw.org/' 936 937 Microsoft also publishes an Interix "Services for Unix" which can 938 be used to build GMP on Windows (with a normal `./configure'), but 939 it's not free software. 940 941 MS Windows DLLs 942 On systems `*-*-cygwin*', `*-*-mingw*' and `*-*-pw32*' by default 943 GMP builds only a static library, but a DLL can be built instead 944 using 945 946 ./configure --disable-static --enable-shared 947 948 Static and DLL libraries can't both be built, since certain export 949 directives in `gmp.h' must be different. 950 951 A MINGW DLL build of GMP can be used with Microsoft C. Libtool 952 doesn't install a `.lib' format import library, but it can be 953 created with MS `lib' as follows, and copied to the install 954 directory. Similarly for `libmp' and `libgmpxx'. 955 956 cd .libs 957 lib /def:libgmp-3.dll.def /out:libgmp-3.lib 958 959 MINGW uses the C runtime library `msvcrt.dll' for I/O, so 960 applications wanting to use the GMP I/O routines must be compiled 961 with `cl /MD' to do the same. If one of the other C runtime 962 library choices provided by MS C is desired then the suggestion is 963 to use the GMP string functions and confine I/O to the application. 964 965 Motorola 68k CPU Types 966 `m68k' is taken to mean 68000. `m68020' or higher will give a 967 performance boost on applicable CPUs. `m68360' can be used for 968 CPU32 series chips. `m68302' can be used for "Dragonball" series 969 chips, though this is merely a synonym for `m68000'. 970 971 OpenBSD 2.6 972 `m4' in this release of OpenBSD has a bug in `eval' that makes it 973 unsuitable for `.asm' file processing. `./configure' will detect 974 the problem and either abort or choose another m4 in the `PATH'. 975 The bug is fixed in OpenBSD 2.7, so either upgrade or use GNU m4. 976 977 Power CPU Types 978 In GMP, CPU types `power*' and `powerpc*' will each use 979 instructions not available on the other, so it's important to 980 choose the right one for the CPU that will be used. Currently GMP 981 has no assembly code support for using just the common instruction 982 subset. To get executables that run on both, the current 983 suggestion is to use the generic C code (CPU `none'), possibly 984 with appropriate compiler options (like `-mcpu=common' for `gcc'). 985 CPU `rs6000' (which is not a CPU but a family of workstations) is 986 accepted by `config.sub', but is currently equivalent to `none'. 987 988 Sparc CPU Types 989 `sparcv8' or `supersparc' on relevant systems will give a 990 significant performance increase over the V7 code selected by plain 991 `sparc'. 992 993 Sparc App Regs 994 The GMP assembly code for both 32-bit and 64-bit Sparc clobbers the 995 "application registers" `g2', `g3' and `g4', the same way that the 996 GCC default `-mapp-regs' does (*note SPARC Options: (gcc)SPARC 997 Options.). 998 999 This makes that code unsuitable for use with the special V9 1000 `-mcmodel=embmedany' (which uses `g4' as a data segment pointer), 1001 and for applications wanting to use those registers for special 1002 purposes. In these cases the only suggestion currently is to 1003 build GMP with CPU `none' to avoid the assembly code. 1004 1005 SunOS 4 1006 `/usr/bin/m4' lacks various features needed to process `.asm' 1007 files, and instead `./configure' will automatically use 1008 `/usr/5bin/m4', which we believe is always available (if not then 1009 use GNU m4). 1010 1011 x86 CPU Types 1012 `i586', `pentium' or `pentiummmx' code is good for its intended P5 1013 Pentium chips, but quite slow when run on Intel P6 class chips 1014 (PPro, P-II, P-III). `i386' is a better choice when making 1015 binaries that must run on both. 1016 1017 x86 MMX and SSE2 Code 1018 If the CPU selected has MMX code but the assembler doesn't support 1019 it, a warning is given and non-MMX code is used instead. This 1020 will be an inferior build, since the MMX code that's present is 1021 there because it's faster than the corresponding plain integer 1022 code. The same applies to SSE2. 1023 1024 Old versions of `gas' don't support MMX instructions, in particular 1025 version 1.92.3 that comes with FreeBSD 2.2.8 or the more recent 1026 OpenBSD 3.1 doesn't. 1027 1028 Solaris 2.6 and 2.7 `as' generate incorrect object code for 1029 register to register `movq' instructions, and so can't be used for 1030 MMX code. Install a recent `gas' if MMX code is wanted on these 1031 systems. 1032 1033 1034 File: gmp.info, Node: Known Build Problems, Next: Performance optimization, Prev: Notes for Particular Systems, Up: Installing GMP 1035 1036 2.5 Known Build Problems 1037 ======================== 1038 1039 You might find more up-to-date information at `http://gmplib.org/'. 1040 1041 Compiler link options 1042 The version of libtool currently in use rather aggressively strips 1043 compiler options when linking a shared library. This will 1044 hopefully be relaxed in the future, but for now if this is a 1045 problem the suggestion is to create a little script to hide them, 1046 and for instance configure with 1047 1048 ./configure CC=gcc-with-my-options 1049 1050 DJGPP (`*-*-msdosdjgpp*') 1051 The DJGPP port of `bash' 2.03 is unable to run the `configure' 1052 script, it exits silently, having died writing a preamble to 1053 `config.log'. Use `bash' 2.04 or higher. 1054 1055 `make all' was found to run out of memory during the final 1056 `libgmp.la' link on one system tested, despite having 64Mb 1057 available. Running `make libgmp.la' directly helped, perhaps 1058 recursing into the various subdirectories uses up memory. 1059 1060 GNU binutils `strip' prior to 2.12 1061 `strip' from GNU binutils 2.11 and earlier should not be used on 1062 the static libraries `libgmp.a' and `libmp.a' since it will 1063 discard all but the last of multiple archive members with the same 1064 name, like the three versions of `init.o' in `libgmp.a'. Binutils 1065 2.12 or higher can be used successfully. 1066 1067 The shared libraries `libgmp.so' and `libmp.so' are not affected by 1068 this and any version of `strip' can be used on them. 1069 1070 `make' syntax error 1071 On certain versions of SCO OpenServer 5 and IRIX 6.5 the native 1072 `make' is unable to handle the long dependencies list for 1073 `libgmp.la'. The symptom is a "syntax error" on the following 1074 line of the top-level `Makefile'. 1075 1076 libgmp.la: $(libgmp_la_OBJECTS) $(libgmp_la_DEPENDENCIES) 1077 1078 Either use GNU Make, or as a workaround remove 1079 `$(libgmp_la_DEPENDENCIES)' from that line (which will make the 1080 initial build work, but if any recompiling is done `libgmp.la' 1081 might not be rebuilt). 1082 1083 MacOS X (`*-*-darwin*') 1084 Libtool currently only knows how to create shared libraries on 1085 MacOS X using the native `cc' (which is a modified GCC), not a 1086 plain GCC. A static-only build should work though 1087 (`--disable-shared'). 1088 1089 NeXT prior to 3.3 1090 The system compiler on old versions of NeXT was a massacred and 1091 old GCC, even if it called itself `cc'. This compiler cannot be 1092 used to build GMP, you need to get a real GCC, and install that. 1093 (NeXT may have fixed this in release 3.3 of their system.) 1094 1095 POWER and PowerPC 1096 Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP 1097 on POWER or PowerPC. If you want to use GCC for these machines, 1098 get GCC 2.7.2.1 (or later). 1099 1100 Sequent Symmetry 1101 Use the GNU assembler instead of the system assembler, since the 1102 latter has serious bugs. 1103 1104 Solaris 2.6 1105 The system `sed' prints an error "Output line too long" when 1106 libtool builds `libgmp.la'. This doesn't seem to cause any 1107 obvious ill effects, but GNU `sed' is recommended, to avoid any 1108 doubt. 1109 1110 Sparc Solaris 2.7 with gcc 2.95.2 in `ABI=32' 1111 A shared library build of GMP seems to fail in this combination, 1112 it builds but then fails the tests, apparently due to some 1113 incorrect data relocations within `gmp_randinit_lc_2exp_size'. 1114 The exact cause is unknown, `--disable-shared' is recommended. 1115 1116 1117 File: gmp.info, Node: Performance optimization, Prev: Known Build Problems, Up: Installing GMP 1118 1119 2.6 Performance optimization 1120 ============================ 1121 1122 For optimal performance, build GMP for the exact CPU type of the target 1123 computer, see *note Build Options::. 1124 1125 Unlike what is the case for most other programs, the compiler 1126 typically doesn't matter much, since GMP uses assembly language for the 1127 most critical operation. 1128 1129 In particular for long-running GMP applications, and applications 1130 demanding extremely large numbers, building and running the `tuneup' 1131 program in the `tune' subdirectory, can be important. For example, 1132 1133 cd tune 1134 make tuneup 1135 ./tuneup 1136 1137 will generate better contents for the `gmp-mparam.h' parameter file. 1138 1139 To use the results, put the output in the file indicated in the 1140 `Parameters for ...' header. Then recompile from scratch. 1141 1142 The `tuneup' program takes one useful parameter, `-f NNN', which 1143 instructs the program how long to check FFT multiply parameters. If 1144 you're going to use GMP for extremely large numbers, you may want to 1145 run `tuneup' with a large NNN value. 1146 1147 1148 File: gmp.info, Node: GMP Basics, Next: Reporting Bugs, Prev: Installing GMP, Up: Top 1149 1150 3 GMP Basics 1151 ************ 1152 1153 *Using functions, macros, data types, etc. not documented in this 1154 manual is strongly discouraged. If you do so your application is 1155 guaranteed to be incompatible with future versions of GMP.* 1156 1157 * Menu: 1158 1159 * Headers and Libraries:: 1160 * Nomenclature and Types:: 1161 * Function Classes:: 1162 * Variable Conventions:: 1163 * Parameter Conventions:: 1164 * Memory Management:: 1165 * Reentrancy:: 1166 * Useful Macros and Constants:: 1167 * Compatibility with older versions:: 1168 * Demonstration Programs:: 1169 * Efficiency:: 1170 * Debugging:: 1171 * Profiling:: 1172 * Autoconf:: 1173 * Emacs:: 1174 1175 1176 File: gmp.info, Node: Headers and Libraries, Next: Nomenclature and Types, Prev: GMP Basics, Up: GMP Basics 1177 1178 3.1 Headers and Libraries 1179 ========================= 1180 1181 All declarations needed to use GMP are collected in the include file 1182 `gmp.h'. It is designed to work with both C and C++ compilers. 1183 1184 #include <gmp.h> 1185 1186 Note however that prototypes for GMP functions with `FILE *' 1187 parameters are only provided if `<stdio.h>' is included too. 1188 1189 #include <stdio.h> 1190 #include <gmp.h> 1191 1192 Likewise `<stdarg.h>' (or `<varargs.h>') is required for prototypes 1193 with `va_list' parameters, such as `gmp_vprintf'. And `<obstack.h>' 1194 for prototypes with `struct obstack' parameters, such as 1195 `gmp_obstack_printf', when available. 1196 1197 All programs using GMP must link against the `libgmp' library. On a 1198 typical Unix-like system this can be done with `-lgmp', for example 1199 1200 gcc myprogram.c -lgmp 1201 1202 GMP C++ functions are in a separate `libgmpxx' library. This is 1203 built and installed if C++ support has been enabled (*note Build 1204 Options::). For example, 1205 1206 g++ mycxxprog.cc -lgmpxx -lgmp 1207 1208 GMP is built using Libtool and an application can use that to link 1209 if desired, *note GNU Libtool: (libtool)Top. 1210 1211 If GMP has been installed to a non-standard location then it may be 1212 necessary to use `-I' and `-L' compiler options to point to the right 1213 directories, and some sort of run-time path for a shared library. 1214 1215 1216 File: gmp.info, Node: Nomenclature and Types, Next: Function Classes, Prev: Headers and Libraries, Up: GMP Basics 1217 1218 3.2 Nomenclature and Types 1219 ========================== 1220 1221 In this manual, "integer" usually means a multiple precision integer, as 1222 defined by the GMP library. The C data type for such integers is 1223 `mpz_t'. Here are some examples of how to declare such integers: 1224 1225 mpz_t sum; 1226 1227 struct foo { mpz_t x, y; }; 1228 1229 mpz_t vec[20]; 1230 1231 "Rational number" means a multiple precision fraction. The C data 1232 type for these fractions is `mpq_t'. For example: 1233 1234 mpq_t quotient; 1235 1236 "Floating point number" or "Float" for short, is an arbitrary 1237 precision mantissa with a limited precision exponent. The C data type 1238 for such objects is `mpf_t'. For example: 1239 1240 mpf_t fp; 1241 1242 The floating point functions accept and return exponents in the C 1243 type `mp_exp_t'. Currently this is usually a `long', but on some 1244 systems it's an `int' for efficiency. 1245 1246 A "limb" means the part of a multi-precision number that fits in a 1247 single machine word. (We chose this word because a limb of the human 1248 body is analogous to a digit, only larger, and containing several 1249 digits.) Normally a limb is 32 or 64 bits. The C data type for a limb 1250 is `mp_limb_t'. 1251 1252 Counts of limbs of a multi-precision number represented in the C type 1253 `mp_size_t'. Currently this is normally a `long', but on some systems 1254 it's an `int' for efficiency, and on some systems it will be `long 1255 long' in the future. 1256 1257 Counts of bits of a multi-precision number are represented in the C 1258 type `mp_bitcnt_t'. Currently this is always an `unsigned long', but on 1259 some systems it will be an `unsigned long long' in the future. 1260 1261 "Random state" means an algorithm selection and current state data. 1262 The C data type for such objects is `gmp_randstate_t'. For example: 1263 1264 gmp_randstate_t rstate; 1265 1266 Also, in general `mp_bitcnt_t' is used for bit counts and ranges, and 1267 `size_t' is used for byte or character counts. 1268 1269 1270 File: gmp.info, Node: Function Classes, Next: Variable Conventions, Prev: Nomenclature and Types, Up: GMP Basics 1271 1272 3.3 Function Classes 1273 ==================== 1274 1275 There are six classes of functions in the GMP library: 1276 1277 1. Functions for signed integer arithmetic, with names beginning with 1278 `mpz_'. The associated type is `mpz_t'. There are about 150 1279 functions in this class. (*note Integer Functions::) 1280 1281 2. Functions for rational number arithmetic, with names beginning with 1282 `mpq_'. The associated type is `mpq_t'. There are about 40 1283 functions in this class, but the integer functions can be used for 1284 arithmetic on the numerator and denominator separately. (*note 1285 Rational Number Functions::) 1286 1287 3. Functions for floating-point arithmetic, with names beginning with 1288 `mpf_'. The associated type is `mpf_t'. There are about 60 1289 functions is this class. (*note Floating-point Functions::) 1290 1291 4. Functions compatible with Berkeley MP, such as `itom', `madd', and 1292 `mult'. The associated type is `MINT'. (*note BSD Compatible 1293 Functions::) 1294 1295 5. Fast low-level functions that operate on natural numbers. These 1296 are used by the functions in the preceding groups, and you can 1297 also call them directly from very time-critical user programs. 1298 These functions' names begin with `mpn_'. The associated type is 1299 array of `mp_limb_t'. There are about 30 (hard-to-use) functions 1300 in this class. (*note Low-level Functions::) 1301 1302 6. Miscellaneous functions. Functions for setting up custom 1303 allocation and functions for generating random numbers. (*note 1304 Custom Allocation::, and *note Random Number Functions::) 1305 1306 1307 File: gmp.info, Node: Variable Conventions, Next: Parameter Conventions, Prev: Function Classes, Up: GMP Basics 1308 1309 3.4 Variable Conventions 1310 ======================== 1311 1312 GMP functions generally have output arguments before input arguments. 1313 This notation is by analogy with the assignment operator. The BSD MP 1314 compatibility functions are exceptions, having the output arguments 1315 last. 1316 1317 GMP lets you use the same variable for both input and output in one 1318 call. For example, the main function for integer multiplication, 1319 `mpz_mul', can be used to square `x' and put the result back in `x' with 1320 1321 mpz_mul (x, x, x); 1322 1323 Before you can assign to a GMP variable, you need to initialize it 1324 by calling one of the special initialization functions. When you're 1325 done with a variable, you need to clear it out, using one of the 1326 functions for that purpose. Which function to use depends on the type 1327 of variable. See the chapters on integer functions, rational number 1328 functions, and floating-point functions for details. 1329 1330 A variable should only be initialized once, or at least cleared 1331 between each initialization. After a variable has been initialized, it 1332 may be assigned to any number of times. 1333 1334 For efficiency reasons, avoid excessive initializing and clearing. 1335 In general, initialize near the start of a function and clear near the 1336 end. For example, 1337 1338 void 1339 foo (void) 1340 { 1341 mpz_t n; 1342 int i; 1343 mpz_init (n); 1344 for (i = 1; i < 100; i++) 1345 { 1346 mpz_mul (n, ...); 1347 mpz_fdiv_q (n, ...); 1348 ... 1349 } 1350 mpz_clear (n); 1351 } 1352 1353 1354 File: gmp.info, Node: Parameter Conventions, Next: Memory Management, Prev: Variable Conventions, Up: GMP Basics 1355 1356 3.5 Parameter Conventions 1357 ========================= 1358 1359 When a GMP variable is used as a function parameter, it's effectively a 1360 call-by-reference, meaning if the function stores a value there it will 1361 change the original in the caller. Parameters which are input-only can 1362 be designated `const' to provoke a compiler error or warning on 1363 attempting to modify them. 1364 1365 When a function is going to return a GMP result, it should designate 1366 a parameter that it sets, like the library functions do. More than one 1367 value can be returned by having more than one output parameter, again 1368 like the library functions. A `return' of an `mpz_t' etc doesn't 1369 return the object, only a pointer, and this is almost certainly not 1370 what's wanted. 1371 1372 Here's an example accepting an `mpz_t' parameter, doing a 1373 calculation, and storing the result to the indicated parameter. 1374 1375 void 1376 foo (mpz_t result, const mpz_t param, unsigned long n) 1377 { 1378 unsigned long i; 1379 mpz_mul_ui (result, param, n); 1380 for (i = 1; i < n; i++) 1381 mpz_add_ui (result, result, i*7); 1382 } 1383 1384 int 1385 main (void) 1386 { 1387 mpz_t r, n; 1388 mpz_init (r); 1389 mpz_init_set_str (n, "123456", 0); 1390 foo (r, n, 20L); 1391 gmp_printf ("%Zd\n", r); 1392 return 0; 1393 } 1394 1395 `foo' works even if the mainline passes the same variable for 1396 `param' and `result', just like the library functions. But sometimes 1397 it's tricky to make that work, and an application might not want to 1398 bother supporting that sort of thing. 1399 1400 For interest, the GMP types `mpz_t' etc are implemented as 1401 one-element arrays of certain structures. This is why declaring a 1402 variable creates an object with the fields GMP needs, but then using it 1403 as a parameter passes a pointer to the object. Note that the actual 1404 fields in each `mpz_t' etc are for internal use only and should not be 1405 accessed directly by code that expects to be compatible with future GMP 1406 releases. 1407 1408 1409 File: gmp.info, Node: Memory Management, Next: Reentrancy, Prev: Parameter Conventions, Up: GMP Basics 1410 1411 3.6 Memory Management 1412 ===================== 1413 1414 The GMP types like `mpz_t' are small, containing only a couple of sizes, 1415 and pointers to allocated data. Once a variable is initialized, GMP 1416 takes care of all space allocation. Additional space is allocated 1417 whenever a variable doesn't have enough. 1418 1419 `mpz_t' and `mpq_t' variables never reduce their allocated space. 1420 Normally this is the best policy, since it avoids frequent reallocation. 1421 Applications that need to return memory to the heap at some particular 1422 point can use `mpz_realloc2', or clear variables no longer needed. 1423 1424 `mpf_t' variables, in the current implementation, use a fixed amount 1425 of space, determined by the chosen precision and allocated at 1426 initialization, so their size doesn't change. 1427 1428 All memory is allocated using `malloc' and friends by default, but 1429 this can be changed, see *note Custom Allocation::. Temporary memory 1430 on the stack is also used (via `alloca'), but this can be changed at 1431 build-time if desired, see *note Build Options::. 1432 1433 1434 File: gmp.info, Node: Reentrancy, Next: Useful Macros and Constants, Prev: Memory Management, Up: GMP Basics 1435 1436 3.7 Reentrancy 1437 ============== 1438 1439 GMP is reentrant and thread-safe, with some exceptions: 1440 1441 * If configured with `--enable-alloca=malloc-notreentrant' (or with 1442 `--enable-alloca=notreentrant' when `alloca' is not available), 1443 then naturally GMP is not reentrant. 1444 1445 * `mpf_set_default_prec' and `mpf_init' use a global variable for the 1446 selected precision. `mpf_init2' can be used instead, and in the 1447 C++ interface an explicit precision to the `mpf_class' constructor. 1448 1449 * `mpz_random' and the other old random number functions use a global 1450 random state and are hence not reentrant. The newer random number 1451 functions that accept a `gmp_randstate_t' parameter can be used 1452 instead. 1453 1454 * `gmp_randinit' (obsolete) returns an error indication through a 1455 global variable, which is not thread safe. Applications are 1456 advised to use `gmp_randinit_default' or `gmp_randinit_lc_2exp' 1457 instead. 1458 1459 * `mp_set_memory_functions' uses global variables to store the 1460 selected memory allocation functions. 1461 1462 * If the memory allocation functions set by a call to 1463 `mp_set_memory_functions' (or `malloc' and friends by default) are 1464 not reentrant, then GMP will not be reentrant either. 1465 1466 * If the standard I/O functions such as `fwrite' are not reentrant 1467 then the GMP I/O functions using them will not be reentrant either. 1468 1469 * It's safe for two threads to read from the same GMP variable 1470 simultaneously, but it's not safe for one to read while the 1471 another might be writing, nor for two threads to write 1472 simultaneously. It's not safe for two threads to generate a 1473 random number from the same `gmp_randstate_t' simultaneously, 1474 since this involves an update of that variable. 1475 1476 1477 File: gmp.info, Node: Useful Macros and Constants, Next: Compatibility with older versions, Prev: Reentrancy, Up: GMP Basics 1478 1479 3.8 Useful Macros and Constants 1480 =============================== 1481 1482 -- Global Constant: const int mp_bits_per_limb 1483 The number of bits per limb. 1484 1485 -- Macro: __GNU_MP_VERSION 1486 -- Macro: __GNU_MP_VERSION_MINOR 1487 -- Macro: __GNU_MP_VERSION_PATCHLEVEL 1488 The major and minor GMP version, and patch level, respectively, as 1489 integers. For GMP i.j, these numbers will be i, j, and 0, 1490 respectively. For GMP i.j.k, these numbers will be i, j, and k, 1491 respectively. 1492 1493 -- Global Constant: const char * const gmp_version 1494 The GMP version number, as a null-terminated string, in the form 1495 "i.j.k". This release is "5.0.5". Note that the format "i.j" was 1496 used when k was zero was used before version 4.3.0. 1497 1498 -- Macro: __GMP_CC 1499 -- Macro: __GMP_CFLAGS 1500 The compiler and compiler flags, respectively, used when compiling 1501 GMP, as strings. 1502 1503 1504 File: gmp.info, Node: Compatibility with older versions, Next: Demonstration Programs, Prev: Useful Macros and Constants, Up: GMP Basics 1505 1506 3.9 Compatibility with older versions 1507 ===================================== 1508 1509 This version of GMP is upwardly binary compatible with all 4.x and 3.x 1510 versions, and upwardly compatible at the source level with all 2.x 1511 versions, with the following exceptions. 1512 1513 * `mpn_gcd' had its source arguments swapped as of GMP 3.0, for 1514 consistency with other `mpn' functions. 1515 1516 * `mpf_get_prec' counted precision slightly differently in GMP 3.0 1517 and 3.0.1, but in 3.1 reverted to the 2.x style. 1518 1519 There are a number of compatibility issues between GMP 1 and GMP 2 1520 that of course also apply when porting applications from GMP 1 to GMP 1521 4. Please see the GMP 2 manual for details. 1522 1523 The Berkeley MP compatibility library (*note BSD Compatible 1524 Functions::) is source and binary compatible with the standard `libmp'. 1525 1526 1527 File: gmp.info, Node: Demonstration Programs, Next: Efficiency, Prev: Compatibility with older versions, Up: GMP Basics 1528 1529 3.10 Demonstration programs 1530 =========================== 1531 1532 The `demos' subdirectory has some sample programs using GMP. These 1533 aren't built or installed, but there's a `Makefile' with rules for them. 1534 For instance, 1535 1536 make pexpr 1537 ./pexpr 68^975+10 1538 1539 The following programs are provided 1540 1541 * `pexpr' is an expression evaluator, the program used on the GMP 1542 web page. 1543 1544 * The `calc' subdirectory has a similar but simpler evaluator using 1545 `lex' and `yacc'. 1546 1547 * The `expr' subdirectory is yet another expression evaluator, a 1548 library designed for ease of use within a C program. See 1549 `demos/expr/README' for more information. 1550 1551 * `factorize' is a Pollard-Rho factorization program. 1552 1553 * `isprime' is a command-line interface to the `mpz_probab_prime_p' 1554 function. 1555 1556 * `primes' counts or lists primes in an interval, using a sieve. 1557 1558 * `qcn' is an example use of `mpz_kronecker_ui' to estimate quadratic 1559 class numbers. 1560 1561 * The `perl' subdirectory is a comprehensive perl interface to GMP. 1562 See `demos/perl/INSTALL' for more information. Documentation is 1563 in POD format in `demos/perl/GMP.pm'. 1564 1565 As an aside, consideration has been given at various times to some 1566 sort of expression evaluation within the main GMP library. Going 1567 beyond something minimal quickly leads to matters like user-defined 1568 functions, looping, fixnums for control variables, etc, which are 1569 considered outside the scope of GMP (much closer to language 1570 interpreters or compilers, *Note Language Bindings::.) Something 1571 simple for program input convenience may yet be a possibility, a 1572 combination of the `expr' demo and the `pexpr' tree back-end perhaps. 1573 But for now the above evaluators are offered as illustrations. 1574 1575 1576 File: gmp.info, Node: Efficiency, Next: Debugging, Prev: Demonstration Programs, Up: GMP Basics 1577 1578 3.11 Efficiency 1579 =============== 1580 1581 Small Operands 1582 On small operands, the time for function call overheads and memory 1583 allocation can be significant in comparison to actual calculation. 1584 This is unavoidable in a general purpose variable precision 1585 library, although GMP attempts to be as efficient as it can on 1586 both large and small operands. 1587 1588 Static Linking 1589 On some CPUs, in particular the x86s, the static `libgmp.a' should 1590 be used for maximum speed, since the PIC code in the shared 1591 `libgmp.so' will have a small overhead on each function call and 1592 global data address. For many programs this will be 1593 insignificant, but for long calculations there's a gain to be had. 1594 1595 Initializing and Clearing 1596 Avoid excessive initializing and clearing of variables, since this 1597 can be quite time consuming, especially in comparison to otherwise 1598 fast operations like addition. 1599 1600 A language interpreter might want to keep a free list or stack of 1601 initialized variables ready for use. It should be possible to 1602 integrate something like that with a garbage collector too. 1603 1604 Reallocations 1605 An `mpz_t' or `mpq_t' variable used to hold successively increasing 1606 values will have its memory repeatedly `realloc'ed, which could be 1607 quite slow or could fragment memory, depending on the C library. 1608 If an application can estimate the final size then `mpz_init2' or 1609 `mpz_realloc2' can be called to allocate the necessary space from 1610 the beginning (*note Initializing Integers::). 1611 1612 It doesn't matter if a size set with `mpz_init2' or `mpz_realloc2' 1613 is too small, since all functions will do a further reallocation 1614 if necessary. Badly overestimating memory required will waste 1615 space though. 1616 1617 `2exp' Functions 1618 It's up to an application to call functions like `mpz_mul_2exp' 1619 when appropriate. General purpose functions like `mpz_mul' make 1620 no attempt to identify powers of two or other special forms, 1621 because such inputs will usually be very rare and testing every 1622 time would be wasteful. 1623 1624 `ui' and `si' Functions 1625 The `ui' functions and the small number of `si' functions exist for 1626 convenience and should be used where applicable. But if for 1627 example an `mpz_t' contains a value that fits in an `unsigned 1628 long' there's no need extract it and call a `ui' function, just 1629 use the regular `mpz' function. 1630 1631 In-Place Operations 1632 `mpz_abs', `mpq_abs', `mpf_abs', `mpz_neg', `mpq_neg' and 1633 `mpf_neg' are fast when used for in-place operations like 1634 `mpz_abs(x,x)', since in the current implementation only a single 1635 field of `x' needs changing. On suitable compilers (GCC for 1636 instance) this is inlined too. 1637 1638 `mpz_add_ui', `mpz_sub_ui', `mpf_add_ui' and `mpf_sub_ui' benefit 1639 from an in-place operation like `mpz_add_ui(x,x,y)', since usually 1640 only one or two limbs of `x' will need to be changed. The same 1641 applies to the full precision `mpz_add' etc if `y' is small. If 1642 `y' is big then cache locality may be helped, but that's all. 1643 1644 `mpz_mul' is currently the opposite, a separate destination is 1645 slightly better. A call like `mpz_mul(x,x,y)' will, unless `y' is 1646 only one limb, make a temporary copy of `x' before forming the 1647 result. Normally that copying will only be a tiny fraction of the 1648 time for the multiply, so this is not a particularly important 1649 consideration. 1650 1651 `mpz_set', `mpq_set', `mpq_set_num', `mpf_set', etc, make no 1652 attempt to recognise a copy of something to itself, so a call like 1653 `mpz_set(x,x)' will be wasteful. Naturally that would never be 1654 written deliberately, but if it might arise from two pointers to 1655 the same object then a test to avoid it might be desirable. 1656 1657 if (x != y) 1658 mpz_set (x, y); 1659 1660 Note that it's never worth introducing extra `mpz_set' calls just 1661 to get in-place operations. If a result should go to a particular 1662 variable then just direct it there and let GMP take care of data 1663 movement. 1664 1665 Divisibility Testing (Small Integers) 1666 `mpz_divisible_ui_p' and `mpz_congruent_ui_p' are the best 1667 functions for testing whether an `mpz_t' is divisible by an 1668 individual small integer. They use an algorithm which is faster 1669 than `mpz_tdiv_ui', but which gives no useful information about 1670 the actual remainder, only whether it's zero (or a particular 1671 value). 1672 1673 However when testing divisibility by several small integers, it's 1674 best to take a remainder modulo their product, to save 1675 multi-precision operations. For instance to test whether a number 1676 is divisible by any of 23, 29 or 31 take a remainder modulo 1677 23*29*31 = 20677 and then test that. 1678 1679 The division functions like `mpz_tdiv_q_ui' which give a quotient 1680 as well as a remainder are generally a little slower than the 1681 remainder-only functions like `mpz_tdiv_ui'. If the quotient is 1682 only rarely wanted then it's probably best to just take a 1683 remainder and then go back and calculate the quotient if and when 1684 it's wanted (`mpz_divexact_ui' can be used if the remainder is 1685 zero). 1686 1687 Rational Arithmetic 1688 The `mpq' functions operate on `mpq_t' values with no common 1689 factors in the numerator and denominator. Common factors are 1690 checked-for and cast out as necessary. In general, cancelling 1691 factors every time is the best approach since it minimizes the 1692 sizes for subsequent operations. 1693 1694 However, applications that know something about the factorization 1695 of the values they're working with might be able to avoid some of 1696 the GCDs used for canonicalization, or swap them for divisions. 1697 For example when multiplying by a prime it's enough to check for 1698 factors of it in the denominator instead of doing a full GCD. Or 1699 when forming a big product it might be known that very little 1700 cancellation will be possible, and so canonicalization can be left 1701 to the end. 1702 1703 The `mpq_numref' and `mpq_denref' macros give access to the 1704 numerator and denominator to do things outside the scope of the 1705 supplied `mpq' functions. *Note Applying Integer Functions::. 1706 1707 The canonical form for rationals allows mixed-type `mpq_t' and 1708 integer additions or subtractions to be done directly with 1709 multiples of the denominator. This will be somewhat faster than 1710 `mpq_add'. For example, 1711 1712 /* mpq increment */ 1713 mpz_add (mpq_numref(q), mpq_numref(q), mpq_denref(q)); 1714 1715 /* mpq += unsigned long */ 1716 mpz_addmul_ui (mpq_numref(q), mpq_denref(q), 123UL); 1717 1718 /* mpq -= mpz */ 1719 mpz_submul (mpq_numref(q), mpq_denref(q), z); 1720 1721 Number Sequences 1722 Functions like `mpz_fac_ui', `mpz_fib_ui' and `mpz_bin_uiui' are 1723 designed for calculating isolated values. If a range of values is 1724 wanted it's probably best to call to get a starting point and 1725 iterate from there. 1726 1727 Text Input/Output 1728 Hexadecimal or octal are suggested for input or output in text 1729 form. Power-of-2 bases like these can be converted much more 1730 efficiently than other bases, like decimal. For big numbers 1731 there's usually nothing of particular interest to be seen in the 1732 digits, so the base doesn't matter much. 1733 1734 Maybe we can hope octal will one day become the normal base for 1735 everyday use, as proposed by King Charles XII of Sweden and later 1736 reformers. 1737 1738 1739 File: gmp.info, Node: Debugging, Next: Profiling, Prev: Efficiency, Up: GMP Basics 1740 1741 3.12 Debugging 1742 ============== 1743 1744 Stack Overflow 1745 Depending on the system, a segmentation violation or bus error 1746 might be the only indication of stack overflow. See 1747 `--enable-alloca' choices in *note Build Options::, for how to 1748 address this. 1749 1750 In new enough versions of GCC, `-fstack-check' may be able to 1751 ensure an overflow is recognised by the system before too much 1752 damage is done, or `-fstack-limit-symbol' or 1753 `-fstack-limit-register' may be able to add checking if the system 1754 itself doesn't do any (*note Options for Code Generation: 1755 (gcc)Code Gen Options.). These options must be added to the 1756 `CFLAGS' used in the GMP build (*note Build Options::), adding 1757 them just to an application will have no effect. Note also 1758 they're a slowdown, adding overhead to each function call and each 1759 stack allocation. 1760 1761 Heap Problems 1762 The most likely cause of application problems with GMP is heap 1763 corruption. Failing to `init' GMP variables will have 1764 unpredictable effects, and corruption arising elsewhere in a 1765 program may well affect GMP. Initializing GMP variables more than 1766 once or failing to clear them will cause memory leaks. 1767 1768 In all such cases a `malloc' debugger is recommended. On a GNU or 1769 BSD system the standard C library `malloc' has some diagnostic 1770 facilities, see *note Allocation Debugging: (libc)Allocation 1771 Debugging, or `man 3 malloc'. Other possibilities, in no 1772 particular order, include 1773 1774 `http://www.inf.ethz.ch/personal/biere/projects/ccmalloc/' 1775 `http://dmalloc.com/' 1776 `http://www.perens.com/FreeSoftware/' (electric fence) 1777 `http://packages.debian.org/stable/devel/fda' 1778 `http://www.gnupdate.org/components/leakbug/' 1779 `http://people.redhat.com/~otaylor/memprof/' 1780 `http://www.cbmamiga.demon.co.uk/mpatrol/' 1781 1782 The GMP default allocation routines in `memory.c' also have a 1783 simple sentinel scheme which can be enabled with `#define DEBUG' 1784 in that file. This is mainly designed for detecting buffer 1785 overruns during GMP development, but might find other uses. 1786 1787 Stack Backtraces 1788 On some systems the compiler options GMP uses by default can 1789 interfere with debugging. In particular on x86 and 68k systems 1790 `-fomit-frame-pointer' is used and this generally inhibits stack 1791 backtracing. Recompiling without such options may help while 1792 debugging, though the usual caveats about it potentially moving a 1793 memory problem or hiding a compiler bug will apply. 1794 1795 GDB, the GNU Debugger 1796 A sample `.gdbinit' is included in the distribution, showing how 1797 to call some undocumented dump functions to print GMP variables 1798 from within GDB. Note that these functions shouldn't be used in 1799 final application code since they're undocumented and may be 1800 subject to incompatible changes in future versions of GMP. 1801 1802 Source File Paths 1803 GMP has multiple source files with the same name, in different 1804 directories. For example `mpz', `mpq' and `mpf' each have an 1805 `init.c'. If the debugger can't already determine the right one 1806 it may help to build with absolute paths on each C file. One way 1807 to do that is to use a separate object directory with an absolute 1808 path to the source directory. 1809 1810 cd /my/build/dir 1811 /my/source/dir/gmp-5.0.5/configure 1812 1813 This works via `VPATH', and might require GNU `make'. Alternately 1814 it might be possible to change the `.c.lo' rules appropriately. 1815 1816 Assertion Checking 1817 The build option `--enable-assert' is available to add some 1818 consistency checks to the library (see *note Build Options::). 1819 These are likely to be of limited value to most applications. 1820 Assertion failures are just as likely to indicate memory 1821 corruption as a library or compiler bug. 1822 1823 Applications using the low-level `mpn' functions, however, will 1824 benefit from `--enable-assert' since it adds checks on the 1825 parameters of most such functions, many of which have subtle 1826 restrictions on their usage. Note however that only the generic C 1827 code has checks, not the assembly code, so CPU `none' should be 1828 used for maximum checking. 1829 1830 Temporary Memory Checking 1831 The build option `--enable-alloca=debug' arranges that each block 1832 of temporary memory in GMP is allocated with a separate call to 1833 `malloc' (or the allocation function set with 1834 `mp_set_memory_functions'). 1835 1836 This can help a malloc debugger detect accesses outside the 1837 intended bounds, or detect memory not released. In a normal 1838 build, on the other hand, temporary memory is allocated in blocks 1839 which GMP divides up for its own use, or may be allocated with a 1840 compiler builtin `alloca' which will go nowhere near any malloc 1841 debugger hooks. 1842 1843 Maximum Debuggability 1844 To summarize the above, a GMP build for maximum debuggability 1845 would be 1846 1847 ./configure --disable-shared --enable-assert \ 1848 --enable-alloca=debug --host=none CFLAGS=-g 1849 1850 For C++, add `--enable-cxx CXXFLAGS=-g'. 1851 1852 Checker 1853 The GCC checker (`http://savannah.nongnu.org/projects/checker/') 1854 can be used with GMP. It contains a stub library which means GMP 1855 applications compiled with checker can use a normal GMP build. 1856 1857 A build of GMP with checking within GMP itself can be made. This 1858 will run very very slowly. On GNU/Linux for example, 1859 1860 ./configure --host=none-pc-linux-gnu CC=checkergcc 1861 1862 `--host=none' must be used, since the GMP assembly code doesn't 1863 support the checking scheme. The GMP C++ features cannot be used, 1864 since current versions of checker (0.9.9.1) don't yet support the 1865 standard C++ library. 1866 1867 Valgrind 1868 The valgrind program (`http://valgrind.org/') is a memory checker 1869 for x86s. It translates and emulates machine instructions to do 1870 strong checks for uninitialized data (at the level of individual 1871 bits), memory accesses through bad pointers, and memory leaks. 1872 1873 Recent versions of Valgrind are getting support for MMX and 1874 SSE/SSE2 instructions, for past versions GMP will need to be 1875 configured not to use those, i.e. for an x86 without them (for 1876 instance plain `i486'). 1877 1878 GMP's assembly code sometimes promotes a read of the limbs to some 1879 larger size, for efficiency. GMP will do this even at the start 1880 and end of a multilimb operand, using naturaly aligned operations 1881 on the larger type. This may lead to benign reads outside of 1882 allocated areas, triggering complants from Valgrind. 1883 1884 Other Problems 1885 Any suspected bug in GMP itself should be isolated to make sure 1886 it's not an application problem, see *note Reporting Bugs::. 1887 1888 1889 File: gmp.info, Node: Profiling, Next: Autoconf, Prev: Debugging, Up: GMP Basics 1890 1891 3.13 Profiling 1892 ============== 1893 1894 Running a program under a profiler is a good way to find where it's 1895 spending most time and where improvements can be best sought. The 1896 profiling choices for a GMP build are as follows. 1897 1898 `--disable-profiling' 1899 The default is to add nothing special for profiling. 1900 1901 It should be possible to just compile the mainline of a program 1902 with `-p' and use `prof' to get a profile consisting of 1903 timer-based sampling of the program counter. Most of the GMP 1904 assembly code has the necessary symbol information. 1905 1906 This approach has the advantage of minimizing interference with 1907 normal program operation, but on most systems the resolution of 1908 the sampling is quite low (10 milliseconds for instance), 1909 requiring long runs to get accurate information. 1910 1911 `--enable-profiling=prof' 1912 Build with support for the system `prof', which means `-p' added 1913 to the `CFLAGS'. 1914 1915 This provides call counting in addition to program counter 1916 sampling, which allows the most frequently called routines to be 1917 identified, and an average time spent in each routine to be 1918 determined. 1919 1920 The x86 assembly code has support for this option, but on other 1921 processors the assembly routines will be as if compiled without 1922 `-p' and therefore won't appear in the call counts. 1923 1924 On some systems, such as GNU/Linux, `-p' in fact means `-pg' and in 1925 this case `--enable-profiling=gprof' described below should be used 1926 instead. 1927 1928 `--enable-profiling=gprof' 1929 Build with support for `gprof', which means `-pg' added to the 1930 `CFLAGS'. 1931 1932 This provides call graph construction in addition to call counting 1933 and program counter sampling, which makes it possible to count 1934 calls coming from different locations. For example the number of 1935 calls to `mpn_mul' from `mpz_mul' versus the number from 1936 `mpf_mul'. The program counter sampling is still flat though, so 1937 only a total time in `mpn_mul' would be accumulated, not a 1938 separate amount for each call site. 1939 1940 The x86 assembly code has support for this option, but on other 1941 processors the assembly routines will be as if compiled without 1942 `-pg' and therefore not be included in the call counts. 1943 1944 On x86 and m68k systems `-pg' and `-fomit-frame-pointer' are 1945 incompatible, so the latter is omitted from the default flags in 1946 that case, which might result in poorer code generation. 1947 1948 Incidentally, it should be possible to use the `gprof' program 1949 with a plain `--enable-profiling=prof' build. But in that case 1950 only the `gprof -p' flat profile and call counts can be expected 1951 to be valid, not the `gprof -q' call graph. 1952 1953 `--enable-profiling=instrument' 1954 Build with the GCC option `-finstrument-functions' added to the 1955 `CFLAGS' (*note Options for Code Generation: (gcc)Code Gen 1956 Options.). 1957 1958 This inserts special instrumenting calls at the start and end of 1959 each function, allowing exact timing and full call graph 1960 construction. 1961 1962 This instrumenting is not normally a standard system feature and 1963 will require support from an external library, such as 1964 1965 `http://sourceforge.net/projects/fnccheck/' 1966 1967 This should be included in `LIBS' during the GMP configure so that 1968 test programs will link. For example, 1969 1970 ./configure --enable-profiling=instrument LIBS=-lfc 1971 1972 On a GNU system the C library provides dummy instrumenting 1973 functions, so programs compiled with this option will link. In 1974 this case it's only necessary to ensure the correct library is 1975 added when linking an application. 1976 1977 The x86 assembly code supports this option, but on other 1978 processors the assembly routines will be as if compiled without 1979 `-finstrument-functions' meaning time spent in them will 1980 effectively be attributed to their caller. 1981 1982 1983 File: gmp.info, Node: Autoconf, Next: Emacs, Prev: Profiling, Up: GMP Basics 1984 1985 3.14 Autoconf 1986 ============= 1987 1988 Autoconf based applications can easily check whether GMP is installed. 1989 The only thing to be noted is that GMP library symbols from version 3 1990 onwards have prefixes like `__gmpz'. The following therefore would be 1991 a simple test, 1992 1993 AC_CHECK_LIB(gmp, __gmpz_init) 1994 1995 This just uses the default `AC_CHECK_LIB' actions for found or not 1996 found, but an application that must have GMP would want to generate an 1997 error if not found. For example, 1998 1999 AC_CHECK_LIB(gmp, __gmpz_init, , 2000 [AC_MSG_ERROR([GNU MP not found, see http://gmplib.org/])]) 2001 2002 If functions added in some particular version of GMP are required, 2003 then one of those can be used when checking. For example `mpz_mul_si' 2004 was added in GMP 3.1, 2005 2006 AC_CHECK_LIB(gmp, __gmpz_mul_si, , 2007 [AC_MSG_ERROR( 2008 [GNU MP not found, or not 3.1 or up, see http://gmplib.org/])]) 2009 2010 An alternative would be to test the version number in `gmp.h' using 2011 say `AC_EGREP_CPP'. That would make it possible to test the exact 2012 version, if some particular sub-minor release is known to be necessary. 2013 2014 In general it's recommended that applications should simply demand a 2015 new enough GMP rather than trying to provide supplements for features 2016 not available in past versions. 2017 2018 Occasionally an application will need or want to know the size of a 2019 type at configuration or preprocessing time, not just with `sizeof' in 2020 the code. This can be done in the normal way with `mp_limb_t' etc, but 2021 GMP 4.0 or up is best for this, since prior versions needed certain 2022 `-D' defines on systems using a `long long' limb. The following would 2023 suit Autoconf 2.50 or up, 2024 2025 AC_CHECK_SIZEOF(mp_limb_t, , [#include <gmp.h>]) 2026 2027 2028 File: gmp.info, Node: Emacs, Prev: Autoconf, Up: GMP Basics 2029 2030 3.15 Emacs 2031 ========== 2032 2033 <C-h C-i> (`info-lookup-symbol') is a good way to find documentation on 2034 C functions while editing (*note Info Documentation Lookup: (emacs)Info 2035 Lookup.). 2036 2037 The GMP manual can be included in such lookups by putting the 2038 following in your `.emacs', 2039 2040 (eval-after-load "info-look" 2041 '(let ((mode-value (assoc 'c-mode (assoc 'symbol info-lookup-alist)))) 2042 (setcar (nthcdr 3 mode-value) 2043 (cons '("(gmp)Function Index" nil "^ -.* " "\\>") 2044 (nth 3 mode-value))))) 2045 2046 2047 File: gmp.info, Node: Reporting Bugs, Next: Integer Functions, Prev: GMP Basics, Up: Top 2048 2049 4 Reporting Bugs 2050 **************** 2051 2052 If you think you have found a bug in the GMP library, please 2053 investigate it and report it. We have made this library available to 2054 you, and it is not too much to ask you to report the bugs you find. 2055 2056 Before you report a bug, check it's not already addressed in *note 2057 Known Build Problems::, or perhaps *note Notes for Particular 2058 Systems::. You may also want to check `http://gmplib.org/' for patches 2059 for this release. 2060 2061 Please include the following in any report, 2062 2063 * The GMP version number, and if pre-packaged or patched then say so. 2064 2065 * A test program that makes it possible for us to reproduce the bug. 2066 Include instructions on how to run the program. 2067 2068 * A description of what is wrong. If the results are incorrect, in 2069 what way. If you get a crash, say so. 2070 2071 * If you get a crash, include a stack backtrace from the debugger if 2072 it's informative (`where' in `gdb', or `$C' in `adb'). 2073 2074 * Please do not send core dumps, executables or `strace's. 2075 2076 * The configuration options you used when building GMP, if any. 2077 2078 * The name of the compiler and its version. For `gcc', get the 2079 version with `gcc -v', otherwise perhaps `what `which cc`', or 2080 similar. 2081 2082 * The output from running `uname -a'. 2083 2084 * The output from running `./config.guess', and from running 2085 `./configfsf.guess' (might be the same). 2086 2087 * If the bug is related to `configure', then the compressed contents 2088 of `config.log'. 2089 2090 * If the bug is related to an `asm' file not assembling, then the 2091 contents of `config.m4' and the offending line or lines from the 2092 temporary `mpn/tmp-<file>.s'. 2093 2094 Please make an effort to produce a self-contained report, with 2095 something definite that can be tested or debugged. Vague queries or 2096 piecemeal messages are difficult to act on and don't help the 2097 development effort. 2098 2099 It is not uncommon that an observed problem is actually due to a bug 2100 in the compiler; the GMP code tends to explore interesting corners in 2101 compilers. 2102 2103 If your bug report is good, we will do our best to help you get a 2104 corrected version of the library; if the bug report is poor, we won't 2105 do anything about it (except maybe ask you to send a better report). 2106 2107 Send your report to: <gmp-bugs (a] gmplib.org>. 2108 2109 If you think something in this manual is unclear, or downright 2110 incorrect, or if the language needs to be improved, please send a note 2111 to the same address. 2112 2113 2114 File: gmp.info, Node: Integer Functions, Next: Rational Number Functions, Prev: Reporting Bugs, Up: Top 2115 2116 5 Integer Functions 2117 ******************* 2118 2119 This chapter describes the GMP functions for performing integer 2120 arithmetic. These functions start with the prefix `mpz_'. 2121 2122 GMP integers are stored in objects of type `mpz_t'. 2123 2124 * Menu: 2125 2126 * Initializing Integers:: 2127 * Assigning Integers:: 2128 * Simultaneous Integer Init & Assign:: 2129 * Converting Integers:: 2130 * Integer Arithmetic:: 2131 * Integer Division:: 2132 * Integer Exponentiation:: 2133 * Integer Roots:: 2134 * Number Theoretic Functions:: 2135 * Integer Comparisons:: 2136 * Integer Logic and Bit Fiddling:: 2137 * I/O of Integers:: 2138 * Integer Random Numbers:: 2139 * Integer Import and Export:: 2140 * Miscellaneous Integer Functions:: 2141 * Integer Special Functions:: 2142 2143 2144 File: gmp.info, Node: Initializing Integers, Next: Assigning Integers, Prev: Integer Functions, Up: Integer Functions 2145 2146 5.1 Initialization Functions 2147 ============================ 2148 2149 The functions for integer arithmetic assume that all integer objects are 2150 initialized. You do that by calling the function `mpz_init'. For 2151 example, 2152 2153 { 2154 mpz_t integ; 2155 mpz_init (integ); 2156 ... 2157 mpz_add (integ, ...); 2158 ... 2159 mpz_sub (integ, ...); 2160 2161 /* Unless the program is about to exit, do ... */ 2162 mpz_clear (integ); 2163 } 2164 2165 As you can see, you can store new values any number of times, once an 2166 object is initialized. 2167 2168 -- Function: void mpz_init (mpz_t X) 2169 Initialize X, and set its value to 0. 2170 2171 -- Function: void mpz_inits (mpz_t X, ...) 2172 Initialize a NULL-terminated list of `mpz_t' variables, and set 2173 their values to 0. 2174 2175 -- Function: void mpz_init2 (mpz_t X, mp_bitcnt_t N) 2176 Initialize X, with space for N-bit numbers, and set its value to 0. 2177 Calling this function instead of `mpz_init' or `mpz_inits' is never 2178 necessary; reallocation is handled automatically by GMP when 2179 needed. 2180 2181 N is only the initial space, X will grow automatically in the 2182 normal way, if necessary, for subsequent values stored. 2183 `mpz_init2' makes it possible to avoid such reallocations if a 2184 maximum size is known in advance. 2185 2186 -- Function: void mpz_clear (mpz_t X) 2187 Free the space occupied by X. Call this function for all `mpz_t' 2188 variables when you are done with them. 2189 2190 -- Function: void mpz_clears (mpz_t X, ...) 2191 Free the space occupied by a NULL-terminated list of `mpz_t' 2192 variables. 2193 2194 -- Function: void mpz_realloc2 (mpz_t X, mp_bitcnt_t N) 2195 Change the space allocated for X to N bits. The value in X is 2196 preserved if it fits, or is set to 0 if not. 2197 2198 Calling this function is never necessary; reallocation is handled 2199 automatically by GMP when needed. But this function can be used 2200 to increase the space for a variable in order to avoid repeated 2201 automatic reallocations, or to decrease it to give memory back to 2202 the heap. 2203 2204 2205 File: gmp.info, Node: Assigning Integers, Next: Simultaneous Integer Init & Assign, Prev: Initializing Integers, Up: Integer Functions 2206 2207 5.2 Assignment Functions 2208 ======================== 2209 2210 These functions assign new values to already initialized integers 2211 (*note Initializing Integers::). 2212 2213 -- Function: void mpz_set (mpz_t ROP, mpz_t OP) 2214 -- Function: void mpz_set_ui (mpz_t ROP, unsigned long int OP) 2215 -- Function: void mpz_set_si (mpz_t ROP, signed long int OP) 2216 -- Function: void mpz_set_d (mpz_t ROP, double OP) 2217 -- Function: void mpz_set_q (mpz_t ROP, mpq_t OP) 2218 -- Function: void mpz_set_f (mpz_t ROP, mpf_t OP) 2219 Set the value of ROP from OP. 2220 2221 `mpz_set_d', `mpz_set_q' and `mpz_set_f' truncate OP to make it an 2222 integer. 2223 2224 -- Function: int mpz_set_str (mpz_t ROP, char *STR, int BASE) 2225 Set the value of ROP from STR, a null-terminated C string in base 2226 BASE. White space is allowed in the string, and is simply ignored. 2227 2228 The BASE may vary from 2 to 62, or if BASE is 0, then the leading 2229 characters are used: `0x' and `0X' for hexadecimal, `0b' and `0B' 2230 for binary, `0' for octal, or decimal otherwise. 2231 2232 For bases up to 36, case is ignored; upper-case and lower-case 2233 letters have the same value. For bases 37 to 62, upper-case 2234 letter represent the usual 10..35 while lower-case letter 2235 represent 36..61. 2236 2237 This function returns 0 if the entire string is a valid number in 2238 base BASE. Otherwise it returns -1. 2239 2240 -- Function: void mpz_swap (mpz_t ROP1, mpz_t ROP2) 2241 Swap the values ROP1 and ROP2 efficiently. 2242 2243 2244 File: gmp.info, Node: Simultaneous Integer Init & Assign, Next: Converting Integers, Prev: Assigning Integers, Up: Integer Functions 2245 2246 5.3 Combined Initialization and Assignment Functions 2247 ==================================================== 2248 2249 For convenience, GMP provides a parallel series of initialize-and-set 2250 functions which initialize the output and then store the value there. 2251 These functions' names have the form `mpz_init_set...' 2252 2253 Here is an example of using one: 2254 2255 { 2256 mpz_t pie; 2257 mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10); 2258 ... 2259 mpz_sub (pie, ...); 2260 ... 2261 mpz_clear (pie); 2262 } 2263 2264 Once the integer has been initialized by any of the `mpz_init_set...' 2265 functions, it can be used as the source or destination operand for the 2266 ordinary integer functions. Don't use an initialize-and-set function 2267 on a variable already initialized! 2268 2269 -- Function: void mpz_init_set (mpz_t ROP, mpz_t OP) 2270 -- Function: void mpz_init_set_ui (mpz_t ROP, unsigned long int OP) 2271 -- Function: void mpz_init_set_si (mpz_t ROP, signed long int OP) 2272 -- Function: void mpz_init_set_d (mpz_t ROP, double OP) 2273 Initialize ROP with limb space and set the initial numeric value 2274 from OP. 2275 2276 -- Function: int mpz_init_set_str (mpz_t ROP, char *STR, int BASE) 2277 Initialize ROP and set its value like `mpz_set_str' (see its 2278 documentation above for details). 2279 2280 If the string is a correct base BASE number, the function returns 2281 0; if an error occurs it returns -1. ROP is initialized even if 2282 an error occurs. (I.e., you have to call `mpz_clear' for it.) 2283 2284 2285 File: gmp.info, Node: Converting Integers, Next: Integer Arithmetic, Prev: Simultaneous Integer Init & Assign, Up: Integer Functions 2286 2287 5.4 Conversion Functions 2288 ======================== 2289 2290 This section describes functions for converting GMP integers to 2291 standard C types. Functions for converting _to_ GMP integers are 2292 described in *note Assigning Integers:: and *note I/O of Integers::. 2293 2294 -- Function: unsigned long int mpz_get_ui (mpz_t OP) 2295 Return the value of OP as an `unsigned long'. 2296 2297 If OP is too big to fit an `unsigned long' then just the least 2298 significant bits that do fit are returned. The sign of OP is 2299 ignored, only the absolute value is used. 2300 2301 -- Function: signed long int mpz_get_si (mpz_t OP) 2302 If OP fits into a `signed long int' return the value of OP. 2303 Otherwise return the least significant part of OP, with the same 2304 sign as OP. 2305 2306 If OP is too big to fit in a `signed long int', the returned 2307 result is probably not very useful. To find out if the value will 2308 fit, use the function `mpz_fits_slong_p'. 2309 2310 -- Function: double mpz_get_d (mpz_t OP) 2311 Convert OP to a `double', truncating if necessary (i.e. rounding 2312 towards zero). 2313 2314 If the exponent from the conversion is too big, the result is 2315 system dependent. An infinity is returned where available. A 2316 hardware overflow trap may or may not occur. 2317 2318 -- Function: double mpz_get_d_2exp (signed long int *EXP, mpz_t OP) 2319 Convert OP to a `double', truncating if necessary (i.e. rounding 2320 towards zero), and returning the exponent separately. 2321 2322 The return value is in the range 0.5<=abs(D)<1 and the exponent is 2323 stored to `*EXP'. D * 2^EXP is the (truncated) OP value. If OP 2324 is zero, the return is 0.0 and 0 is stored to `*EXP'. 2325 2326 This is similar to the standard C `frexp' function (*note 2327 Normalization Functions: (libc)Normalization Functions.). 2328 2329 -- Function: char * mpz_get_str (char *STR, int BASE, mpz_t OP) 2330 Convert OP to a string of digits in base BASE. The base argument 2331 may vary from 2 to 62 or from -2 to -36. 2332 2333 For BASE in the range 2..36, digits and lower-case letters are 2334 used; for -2..-36, digits and upper-case letters are used; for 2335 37..62, digits, upper-case letters, and lower-case letters (in 2336 that significance order) are used. 2337 2338 If STR is `NULL', the result string is allocated using the current 2339 allocation function (*note Custom Allocation::). The block will be 2340 `strlen(str)+1' bytes, that being exactly enough for the string and 2341 null-terminator. 2342 2343 If STR is not `NULL', it should point to a block of storage large 2344 enough for the result, that being `mpz_sizeinbase (OP, BASE) + 2'. 2345 The two extra bytes are for a possible minus sign, and the 2346 null-terminator. 2347 2348 A pointer to the result string is returned, being either the 2349 allocated block, or the given STR. 2350 2351 2352 File: gmp.info, Node: Integer Arithmetic, Next: Integer Division, Prev: Converting Integers, Up: Integer Functions 2353 2354 5.5 Arithmetic Functions 2355 ======================== 2356 2357 -- Function: void mpz_add (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2358 -- Function: void mpz_add_ui (mpz_t ROP, mpz_t OP1, unsigned long int 2359 OP2) 2360 Set ROP to OP1 + OP2. 2361 2362 -- Function: void mpz_sub (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2363 -- Function: void mpz_sub_ui (mpz_t ROP, mpz_t OP1, unsigned long int 2364 OP2) 2365 -- Function: void mpz_ui_sub (mpz_t ROP, unsigned long int OP1, mpz_t 2366 OP2) 2367 Set ROP to OP1 - OP2. 2368 2369 -- Function: void mpz_mul (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2370 -- Function: void mpz_mul_si (mpz_t ROP, mpz_t OP1, long int OP2) 2371 -- Function: void mpz_mul_ui (mpz_t ROP, mpz_t OP1, unsigned long int 2372 OP2) 2373 Set ROP to OP1 times OP2. 2374 2375 -- Function: void mpz_addmul (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2376 -- Function: void mpz_addmul_ui (mpz_t ROP, mpz_t OP1, unsigned long 2377 int OP2) 2378 Set ROP to ROP + OP1 times OP2. 2379 2380 -- Function: void mpz_submul (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2381 -- Function: void mpz_submul_ui (mpz_t ROP, mpz_t OP1, unsigned long 2382 int OP2) 2383 Set ROP to ROP - OP1 times OP2. 2384 2385 -- Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, mp_bitcnt_t OP2) 2386 Set ROP to OP1 times 2 raised to OP2. This operation can also be 2387 defined as a left shift by OP2 bits. 2388 2389 -- Function: void mpz_neg (mpz_t ROP, mpz_t OP) 2390 Set ROP to -OP. 2391 2392 -- Function: void mpz_abs (mpz_t ROP, mpz_t OP) 2393 Set ROP to the absolute value of OP. 2394 2395 2396 File: gmp.info, Node: Integer Division, Next: Integer Exponentiation, Prev: Integer Arithmetic, Up: Integer Functions 2397 2398 5.6 Division Functions 2399 ====================== 2400 2401 Division is undefined if the divisor is zero. Passing a zero divisor 2402 to the division or modulo functions (including the modular powering 2403 functions `mpz_powm' and `mpz_powm_ui'), will cause an intentional 2404 division by zero. This lets a program handle arithmetic exceptions in 2405 these functions the same way as for normal C `int' arithmetic. 2406 2407 -- Function: void mpz_cdiv_q (mpz_t Q, mpz_t N, mpz_t D) 2408 -- Function: void mpz_cdiv_r (mpz_t R, mpz_t N, mpz_t D) 2409 -- Function: void mpz_cdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D) 2410 -- Function: unsigned long int mpz_cdiv_q_ui (mpz_t Q, mpz_t N, 2411 unsigned long int D) 2412 -- Function: unsigned long int mpz_cdiv_r_ui (mpz_t R, mpz_t N, 2413 unsigned long int D) 2414 -- Function: unsigned long int mpz_cdiv_qr_ui (mpz_t Q, mpz_t R, 2415 mpz_t N, unsigned long int D) 2416 -- Function: unsigned long int mpz_cdiv_ui (mpz_t N, 2417 unsigned long int D) 2418 -- Function: void mpz_cdiv_q_2exp (mpz_t Q, mpz_t N, mp_bitcnt_t B) 2419 -- Function: void mpz_cdiv_r_2exp (mpz_t R, mpz_t N, mp_bitcnt_t B) 2420 2421 -- Function: void mpz_fdiv_q (mpz_t Q, mpz_t N, mpz_t D) 2422 -- Function: void mpz_fdiv_r (mpz_t R, mpz_t N, mpz_t D) 2423 -- Function: void mpz_fdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D) 2424 -- Function: unsigned long int mpz_fdiv_q_ui (mpz_t Q, mpz_t N, 2425 unsigned long int D) 2426 -- Function: unsigned long int mpz_fdiv_r_ui (mpz_t R, mpz_t N, 2427 unsigned long int D) 2428 -- Function: unsigned long int mpz_fdiv_qr_ui (mpz_t Q, mpz_t R, 2429 mpz_t N, unsigned long int D) 2430 -- Function: unsigned long int mpz_fdiv_ui (mpz_t N, 2431 unsigned long int D) 2432 -- Function: void mpz_fdiv_q_2exp (mpz_t Q, mpz_t N, mp_bitcnt_t B) 2433 -- Function: void mpz_fdiv_r_2exp (mpz_t R, mpz_t N, mp_bitcnt_t B) 2434 2435 -- Function: void mpz_tdiv_q (mpz_t Q, mpz_t N, mpz_t D) 2436 -- Function: void mpz_tdiv_r (mpz_t R, mpz_t N, mpz_t D) 2437 -- Function: void mpz_tdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D) 2438 -- Function: unsigned long int mpz_tdiv_q_ui (mpz_t Q, mpz_t N, 2439 unsigned long int D) 2440 -- Function: unsigned long int mpz_tdiv_r_ui (mpz_t R, mpz_t N, 2441 unsigned long int D) 2442 -- Function: unsigned long int mpz_tdiv_qr_ui (mpz_t Q, mpz_t R, 2443 mpz_t N, unsigned long int D) 2444 -- Function: unsigned long int mpz_tdiv_ui (mpz_t N, 2445 unsigned long int D) 2446 -- Function: void mpz_tdiv_q_2exp (mpz_t Q, mpz_t N, mp_bitcnt_t B) 2447 -- Function: void mpz_tdiv_r_2exp (mpz_t R, mpz_t N, mp_bitcnt_t B) 2448 2449 Divide N by D, forming a quotient Q and/or remainder R. For the 2450 `2exp' functions, D=2^B. The rounding is in three styles, each 2451 suiting different applications. 2452 2453 * `cdiv' rounds Q up towards +infinity, and R will have the 2454 opposite sign to D. The `c' stands for "ceil". 2455 2456 * `fdiv' rounds Q down towards -infinity, and R will have the 2457 same sign as D. The `f' stands for "floor". 2458 2459 * `tdiv' rounds Q towards zero, and R will have the same sign 2460 as N. The `t' stands for "truncate". 2461 2462 In all cases Q and R will satisfy N=Q*D+R, and R will satisfy 2463 0<=abs(R)<abs(D). 2464 2465 The `q' functions calculate only the quotient, the `r' functions 2466 only the remainder, and the `qr' functions calculate both. Note 2467 that for `qr' the same variable cannot be passed for both Q and R, 2468 or results will be unpredictable. 2469 2470 For the `ui' variants the return value is the remainder, and in 2471 fact returning the remainder is all the `div_ui' functions do. For 2472 `tdiv' and `cdiv' the remainder can be negative, so for those the 2473 return value is the absolute value of the remainder. 2474 2475 For the `2exp' variants the divisor is 2^B. These functions are 2476 implemented as right shifts and bit masks, but of course they 2477 round the same as the other functions. 2478 2479 For positive N both `mpz_fdiv_q_2exp' and `mpz_tdiv_q_2exp' are 2480 simple bitwise right shifts. For negative N, `mpz_fdiv_q_2exp' is 2481 effectively an arithmetic right shift treating N as twos complement 2482 the same as the bitwise logical functions do, whereas 2483 `mpz_tdiv_q_2exp' effectively treats N as sign and magnitude. 2484 2485 -- Function: void mpz_mod (mpz_t R, mpz_t N, mpz_t D) 2486 -- Function: unsigned long int mpz_mod_ui (mpz_t R, mpz_t N, 2487 unsigned long int D) 2488 Set R to N `mod' D. The sign of the divisor is ignored; the 2489 result is always non-negative. 2490 2491 `mpz_mod_ui' is identical to `mpz_fdiv_r_ui' above, returning the 2492 remainder as well as setting R. See `mpz_fdiv_ui' above if only 2493 the return value is wanted. 2494 2495 -- Function: void mpz_divexact (mpz_t Q, mpz_t N, mpz_t D) 2496 -- Function: void mpz_divexact_ui (mpz_t Q, mpz_t N, unsigned long D) 2497 Set Q to N/D. These functions produce correct results only when 2498 it is known in advance that D divides N. 2499 2500 These routines are much faster than the other division functions, 2501 and are the best choice when exact division is known to occur, for 2502 example reducing a rational to lowest terms. 2503 2504 -- Function: int mpz_divisible_p (mpz_t N, mpz_t D) 2505 -- Function: int mpz_divisible_ui_p (mpz_t N, unsigned long int D) 2506 -- Function: int mpz_divisible_2exp_p (mpz_t N, mp_bitcnt_t B) 2507 Return non-zero if N is exactly divisible by D, or in the case of 2508 `mpz_divisible_2exp_p' by 2^B. 2509 2510 N is divisible by D if there exists an integer Q satisfying N = 2511 Q*D. Unlike the other division functions, D=0 is accepted and 2512 following the rule it can be seen that only 0 is considered 2513 divisible by 0. 2514 2515 -- Function: int mpz_congruent_p (mpz_t N, mpz_t C, mpz_t D) 2516 -- Function: int mpz_congruent_ui_p (mpz_t N, unsigned long int C, 2517 unsigned long int D) 2518 -- Function: int mpz_congruent_2exp_p (mpz_t N, mpz_t C, mp_bitcnt_t B) 2519 Return non-zero if N is congruent to C modulo D, or in the case of 2520 `mpz_congruent_2exp_p' modulo 2^B. 2521 2522 N is congruent to C mod D if there exists an integer Q satisfying 2523 N = C + Q*D. Unlike the other division functions, D=0 is accepted 2524 and following the rule it can be seen that N and C are considered 2525 congruent mod 0 only when exactly equal. 2526 2527 2528 File: gmp.info, Node: Integer Exponentiation, Next: Integer Roots, Prev: Integer Division, Up: Integer Functions 2529 2530 5.7 Exponentiation Functions 2531 ============================ 2532 2533 -- Function: void mpz_powm (mpz_t ROP, mpz_t BASE, mpz_t EXP, mpz_t 2534 MOD) 2535 -- Function: void mpz_powm_ui (mpz_t ROP, mpz_t BASE, unsigned long 2536 int EXP, mpz_t MOD) 2537 Set ROP to (BASE raised to EXP) modulo MOD. 2538 2539 Negative EXP is supported if an inverse BASE^-1 mod MOD exists 2540 (see `mpz_invert' in *note Number Theoretic Functions::). If an 2541 inverse doesn't exist then a divide by zero is raised. 2542 2543 -- Function: void mpz_powm_sec (mpz_t ROP, mpz_t BASE, mpz_t EXP, 2544 mpz_t MOD) 2545 Set ROP to (BASE raised to EXP) modulo MOD. 2546 2547 It is required that EXP > 0 and that MOD is odd. 2548 2549 This function is designed to take the same time and have the same 2550 cache access patterns for any two same-size arguments, assuming 2551 that function arguments are placed at the same position and that 2552 the machine state is identical upon function entry. This function 2553 is intended for cryptographic purposes, where resilience to 2554 side-channel attacks is desired. 2555 2556 -- Function: void mpz_pow_ui (mpz_t ROP, mpz_t BASE, unsigned long int 2557 EXP) 2558 -- Function: void mpz_ui_pow_ui (mpz_t ROP, unsigned long int BASE, 2559 unsigned long int EXP) 2560 Set ROP to BASE raised to EXP. The case 0^0 yields 1. 2561 2562 2563 File: gmp.info, Node: Integer Roots, Next: Number Theoretic Functions, Prev: Integer Exponentiation, Up: Integer Functions 2564 2565 5.8 Root Extraction Functions 2566 ============================= 2567 2568 -- Function: int mpz_root (mpz_t ROP, mpz_t OP, unsigned long int N) 2569 Set ROP to the truncated integer part of the Nth root of OP. 2570 Return non-zero if the computation was exact, i.e., if OP is ROP 2571 to the Nth power. 2572 2573 -- Function: void mpz_rootrem (mpz_t ROOT, mpz_t REM, mpz_t U, 2574 unsigned long int N) 2575 Set ROOT to the truncated integer part of the Nth root of U. Set 2576 REM to the remainder, U-ROOT**N. 2577 2578 -- Function: void mpz_sqrt (mpz_t ROP, mpz_t OP) 2579 Set ROP to the truncated integer part of the square root of OP. 2580 2581 -- Function: void mpz_sqrtrem (mpz_t ROP1, mpz_t ROP2, mpz_t OP) 2582 Set ROP1 to the truncated integer part of the square root of OP, 2583 like `mpz_sqrt'. Set ROP2 to the remainder OP-ROP1*ROP1, which 2584 will be zero if OP is a perfect square. 2585 2586 If ROP1 and ROP2 are the same variable, the results are undefined. 2587 2588 -- Function: int mpz_perfect_power_p (mpz_t OP) 2589 Return non-zero if OP is a perfect power, i.e., if there exist 2590 integers A and B, with B>1, such that OP equals A raised to the 2591 power B. 2592 2593 Under this definition both 0 and 1 are considered to be perfect 2594 powers. Negative values of OP are accepted, but of course can 2595 only be odd perfect powers. 2596 2597 -- Function: int mpz_perfect_square_p (mpz_t OP) 2598 Return non-zero if OP is a perfect square, i.e., if the square 2599 root of OP is an integer. Under this definition both 0 and 1 are 2600 considered to be perfect squares. 2601 2602 2603 File: gmp.info, Node: Number Theoretic Functions, Next: Integer Comparisons, Prev: Integer Roots, Up: Integer Functions 2604 2605 5.9 Number Theoretic Functions 2606 ============================== 2607 2608 -- Function: int mpz_probab_prime_p (mpz_t N, int REPS) 2609 Determine whether N is prime. Return 2 if N is definitely prime, 2610 return 1 if N is probably prime (without being certain), or return 2611 0 if N is definitely composite. 2612 2613 This function does some trial divisions, then some Miller-Rabin 2614 probabilistic primality tests. REPS controls how many such tests 2615 are done, 5 to 10 is a reasonable number, more will reduce the 2616 chances of a composite being returned as "probably prime". 2617 2618 Miller-Rabin and similar tests can be more properly called 2619 compositeness tests. Numbers which fail are known to be composite 2620 but those which pass might be prime or might be composite. Only a 2621 few composites pass, hence those which pass are considered 2622 probably prime. 2623 2624 -- Function: void mpz_nextprime (mpz_t ROP, mpz_t OP) 2625 Set ROP to the next prime greater than OP. 2626 2627 This function uses a probabilistic algorithm to identify primes. 2628 For practical purposes it's adequate, the chance of a composite 2629 passing will be extremely small. 2630 2631 -- Function: void mpz_gcd (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2632 Set ROP to the greatest common divisor of OP1 and OP2. The result 2633 is always positive even if one or both input operands are negative. 2634 Except if both inputs are zero; then this function defines 2635 gcd(0,0) = 0. 2636 2637 -- Function: unsigned long int mpz_gcd_ui (mpz_t ROP, mpz_t OP1, 2638 unsigned long int OP2) 2639 Compute the greatest common divisor of OP1 and OP2. If ROP is not 2640 `NULL', store the result there. 2641 2642 If the result is small enough to fit in an `unsigned long int', it 2643 is returned. If the result does not fit, 0 is returned, and the 2644 result is equal to the argument OP1. Note that the result will 2645 always fit if OP2 is non-zero. 2646 2647 -- Function: void mpz_gcdext (mpz_t G, mpz_t S, mpz_t T, mpz_t A, 2648 mpz_t B) 2649 Set G to the greatest common divisor of A and B, and in addition 2650 set S and T to coefficients satisfying A*S + B*T = G. The value 2651 in G is always positive, even if one or both of A and B are 2652 negative (or zero if both inputs are zero). The values in S and T 2653 are chosen such that normally, abs(S) < abs(B) / (2 G) and abs(T) 2654 < abs(A) / (2 G), and these relations define S and T uniquely. 2655 There are a few exceptional cases: 2656 2657 If abs(A) = abs(B), then S = 0, T = sgn(B). 2658 2659 Otherwise, S = sgn(A) if B = 0 or abs(B) = 2 G, and T = sgn(B) if 2660 A = 0 or abs(A) = 2 G. 2661 2662 In all cases, S = 0 if and only if G = abs(B), i.e., if B divides 2663 A or A = B = 0. 2664 2665 If T is `NULL' then that value is not computed. 2666 2667 -- Function: void mpz_lcm (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2668 -- Function: void mpz_lcm_ui (mpz_t ROP, mpz_t OP1, unsigned long OP2) 2669 Set ROP to the least common multiple of OP1 and OP2. ROP is 2670 always positive, irrespective of the signs of OP1 and OP2. ROP 2671 will be zero if either OP1 or OP2 is zero. 2672 2673 -- Function: int mpz_invert (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2674 Compute the inverse of OP1 modulo OP2 and put the result in ROP. 2675 If the inverse exists, the return value is non-zero and ROP will 2676 satisfy 0 < ROP < abs(OP2). If an inverse doesn't exist the 2677 return value is zero and ROP is undefined. The behaviour of this 2678 function is undefined when OP2 is zero. 2679 2680 -- Function: int mpz_jacobi (mpz_t A, mpz_t B) 2681 Calculate the Jacobi symbol (A/B). This is defined only for B odd. 2682 2683 -- Function: int mpz_legendre (mpz_t A, mpz_t P) 2684 Calculate the Legendre symbol (A/P). This is defined only for P 2685 an odd positive prime, and for such P it's identical to the Jacobi 2686 symbol. 2687 2688 -- Function: int mpz_kronecker (mpz_t A, mpz_t B) 2689 -- Function: int mpz_kronecker_si (mpz_t A, long B) 2690 -- Function: int mpz_kronecker_ui (mpz_t A, unsigned long B) 2691 -- Function: int mpz_si_kronecker (long A, mpz_t B) 2692 -- Function: int mpz_ui_kronecker (unsigned long A, mpz_t B) 2693 Calculate the Jacobi symbol (A/B) with the Kronecker extension 2694 (a/2)=(2/a) when a odd, or (a/2)=0 when a even. 2695 2696 When B is odd the Jacobi symbol and Kronecker symbol are 2697 identical, so `mpz_kronecker_ui' etc can be used for mixed 2698 precision Jacobi symbols too. 2699 2700 For more information see Henri Cohen section 1.4.2 (*note 2701 References::), or any number theory textbook. See also the 2702 example program `demos/qcn.c' which uses `mpz_kronecker_ui'. 2703 2704 -- Function: mp_bitcnt_t mpz_remove (mpz_t ROP, mpz_t OP, mpz_t F) 2705 Remove all occurrences of the factor F from OP and store the 2706 result in ROP. The return value is how many such occurrences were 2707 removed. 2708 2709 -- Function: void mpz_fac_ui (mpz_t ROP, unsigned long int OP) 2710 Set ROP to OP!, the factorial of OP. 2711 2712 -- Function: void mpz_bin_ui (mpz_t ROP, mpz_t N, unsigned long int K) 2713 -- Function: void mpz_bin_uiui (mpz_t ROP, unsigned long int N, 2714 unsigned long int K) 2715 Compute the binomial coefficient N over K and store the result in 2716 ROP. Negative values of N are supported by `mpz_bin_ui', using 2717 the identity bin(-n,k) = (-1)^k * bin(n+k-1,k), see Knuth volume 1 2718 section 1.2.6 part G. 2719 2720 -- Function: void mpz_fib_ui (mpz_t FN, unsigned long int N) 2721 -- Function: void mpz_fib2_ui (mpz_t FN, mpz_t FNSUB1, unsigned long 2722 int N) 2723 `mpz_fib_ui' sets FN to to F[n], the N'th Fibonacci number. 2724 `mpz_fib2_ui' sets FN to F[n], and FNSUB1 to F[n-1]. 2725 2726 These functions are designed for calculating isolated Fibonacci 2727 numbers. When a sequence of values is wanted it's best to start 2728 with `mpz_fib2_ui' and iterate the defining F[n+1]=F[n]+F[n-1] or 2729 similar. 2730 2731 -- Function: void mpz_lucnum_ui (mpz_t LN, unsigned long int N) 2732 -- Function: void mpz_lucnum2_ui (mpz_t LN, mpz_t LNSUB1, unsigned 2733 long int N) 2734 `mpz_lucnum_ui' sets LN to to L[n], the N'th Lucas number. 2735 `mpz_lucnum2_ui' sets LN to L[n], and LNSUB1 to L[n-1]. 2736 2737 These functions are designed for calculating isolated Lucas 2738 numbers. When a sequence of values is wanted it's best to start 2739 with `mpz_lucnum2_ui' and iterate the defining L[n+1]=L[n]+L[n-1] 2740 or similar. 2741 2742 The Fibonacci numbers and Lucas numbers are related sequences, so 2743 it's never necessary to call both `mpz_fib2_ui' and 2744 `mpz_lucnum2_ui'. The formulas for going from Fibonacci to Lucas 2745 can be found in *note Lucas Numbers Algorithm::, the reverse is 2746 straightforward too. 2747 2748 2749 File: gmp.info, Node: Integer Comparisons, Next: Integer Logic and Bit Fiddling, Prev: Number Theoretic Functions, Up: Integer Functions 2750 2751 5.10 Comparison Functions 2752 ========================= 2753 2754 -- Function: int mpz_cmp (mpz_t OP1, mpz_t OP2) 2755 -- Function: int mpz_cmp_d (mpz_t OP1, double OP2) 2756 -- Macro: int mpz_cmp_si (mpz_t OP1, signed long int OP2) 2757 -- Macro: int mpz_cmp_ui (mpz_t OP1, unsigned long int OP2) 2758 Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero 2759 if OP1 = OP2, or a negative value if OP1 < OP2. 2760 2761 `mpz_cmp_ui' and `mpz_cmp_si' are macros and will evaluate their 2762 arguments more than once. `mpz_cmp_d' can be called with an 2763 infinity, but results are undefined for a NaN. 2764 2765 -- Function: int mpz_cmpabs (mpz_t OP1, mpz_t OP2) 2766 -- Function: int mpz_cmpabs_d (mpz_t OP1, double OP2) 2767 -- Function: int mpz_cmpabs_ui (mpz_t OP1, unsigned long int OP2) 2768 Compare the absolute values of OP1 and OP2. Return a positive 2769 value if abs(OP1) > abs(OP2), zero if abs(OP1) = abs(OP2), or a 2770 negative value if abs(OP1) < abs(OP2). 2771 2772 `mpz_cmpabs_d' can be called with an infinity, but results are 2773 undefined for a NaN. 2774 2775 -- Macro: int mpz_sgn (mpz_t OP) 2776 Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. 2777 2778 This function is actually implemented as a macro. It evaluates 2779 its argument multiple times. 2780 2781 2782 File: gmp.info, Node: Integer Logic and Bit Fiddling, Next: I/O of Integers, Prev: Integer Comparisons, Up: Integer Functions 2783 2784 5.11 Logical and Bit Manipulation Functions 2785 =========================================== 2786 2787 These functions behave as if twos complement arithmetic were used 2788 (although sign-magnitude is the actual implementation). The least 2789 significant bit is number 0. 2790 2791 -- Function: void mpz_and (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2792 Set ROP to OP1 bitwise-and OP2. 2793 2794 -- Function: void mpz_ior (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2795 Set ROP to OP1 bitwise inclusive-or OP2. 2796 2797 -- Function: void mpz_xor (mpz_t ROP, mpz_t OP1, mpz_t OP2) 2798 Set ROP to OP1 bitwise exclusive-or OP2. 2799 2800 -- Function: void mpz_com (mpz_t ROP, mpz_t OP) 2801 Set ROP to the one's complement of OP. 2802 2803 -- Function: mp_bitcnt_t mpz_popcount (mpz_t OP) 2804 If OP>=0, return the population count of OP, which is the number 2805 of 1 bits in the binary representation. If OP<0, the number of 1s 2806 is infinite, and the return value is the largest possible 2807 `mp_bitcnt_t'. 2808 2809 -- Function: mp_bitcnt_t mpz_hamdist (mpz_t OP1, mpz_t OP2) 2810 If OP1 and OP2 are both >=0 or both <0, return the hamming 2811 distance between the two operands, which is the number of bit 2812 positions where OP1 and OP2 have different bit values. If one 2813 operand is >=0 and the other <0 then the number of bits different 2814 is infinite, and the return value is the largest possible 2815 `mp_bitcnt_t'. 2816 2817 -- Function: mp_bitcnt_t mpz_scan0 (mpz_t OP, mp_bitcnt_t STARTING_BIT) 2818 -- Function: mp_bitcnt_t mpz_scan1 (mpz_t OP, mp_bitcnt_t STARTING_BIT) 2819 Scan OP, starting from bit STARTING_BIT, towards more significant 2820 bits, until the first 0 or 1 bit (respectively) is found. Return 2821 the index of the found bit. 2822 2823 If the bit at STARTING_BIT is already what's sought, then 2824 STARTING_BIT is returned. 2825 2826 If there's no bit found, then the largest possible `mp_bitcnt_t' is 2827 returned. This will happen in `mpz_scan0' past the end of a 2828 negative number, or `mpz_scan1' past the end of a nonnegative 2829 number. 2830 2831 -- Function: void mpz_setbit (mpz_t ROP, mp_bitcnt_t BIT_INDEX) 2832 Set bit BIT_INDEX in ROP. 2833 2834 -- Function: void mpz_clrbit (mpz_t ROP, mp_bitcnt_t BIT_INDEX) 2835 Clear bit BIT_INDEX in ROP. 2836 2837 -- Function: void mpz_combit (mpz_t ROP, mp_bitcnt_t BIT_INDEX) 2838 Complement bit BIT_INDEX in ROP. 2839 2840 -- Function: int mpz_tstbit (mpz_t OP, mp_bitcnt_t BIT_INDEX) 2841 Test bit BIT_INDEX in OP and return 0 or 1 accordingly. 2842 2843 2844 File: gmp.info, Node: I/O of Integers, Next: Integer Random Numbers, Prev: Integer Logic and Bit Fiddling, Up: Integer Functions 2845 2846 5.12 Input and Output Functions 2847 =============================== 2848 2849 Functions that perform input from a stdio stream, and functions that 2850 output to a stdio stream, of `mpz' numbers. Passing a `NULL' pointer 2851 for a STREAM argument to any of these functions will make them read from 2852 `stdin' and write to `stdout', respectively. 2853 2854 When using any of these functions, it is a good idea to include 2855 `stdio.h' before `gmp.h', since that will allow `gmp.h' to define 2856 prototypes for these functions. 2857 2858 See also *note Formatted Output:: and *note Formatted Input::. 2859 2860 -- Function: size_t mpz_out_str (FILE *STREAM, int BASE, mpz_t OP) 2861 Output OP on stdio stream STREAM, as a string of digits in base 2862 BASE. The base argument may vary from 2 to 62 or from -2 to -36. 2863 2864 For BASE in the range 2..36, digits and lower-case letters are 2865 used; for -2..-36, digits and upper-case letters are used; for 2866 37..62, digits, upper-case letters, and lower-case letters (in 2867 that significance order) are used. 2868 2869 Return the number of bytes written, or if an error occurred, 2870 return 0. 2871 2872 -- Function: size_t mpz_inp_str (mpz_t ROP, FILE *STREAM, int BASE) 2873 Input a possibly white-space preceded string in base BASE from 2874 stdio stream STREAM, and put the read integer in ROP. 2875 2876 The BASE may vary from 2 to 62, or if BASE is 0, then the leading 2877 characters are used: `0x' and `0X' for hexadecimal, `0b' and `0B' 2878 for binary, `0' for octal, or decimal otherwise. 2879 2880 For bases up to 36, case is ignored; upper-case and lower-case 2881 letters have the same value. For bases 37 to 62, upper-case 2882 letter represent the usual 10..35 while lower-case letter 2883 represent 36..61. 2884 2885 Return the number of bytes read, or if an error occurred, return 0. 2886 2887 -- Function: size_t mpz_out_raw (FILE *STREAM, mpz_t OP) 2888 Output OP on stdio stream STREAM, in raw binary format. The 2889 integer is written in a portable format, with 4 bytes of size 2890 information, and that many bytes of limbs. Both the size and the 2891 limbs are written in decreasing significance order (i.e., in 2892 big-endian). 2893 2894 The output can be read with `mpz_inp_raw'. 2895 2896 Return the number of bytes written, or if an error occurred, 2897 return 0. 2898 2899 The output of this can not be read by `mpz_inp_raw' from GMP 1, 2900 because of changes necessary for compatibility between 32-bit and 2901 64-bit machines. 2902 2903 -- Function: size_t mpz_inp_raw (mpz_t ROP, FILE *STREAM) 2904 Input from stdio stream STREAM in the format written by 2905 `mpz_out_raw', and put the result in ROP. Return the number of 2906 bytes read, or if an error occurred, return 0. 2907 2908 This routine can read the output from `mpz_out_raw' also from GMP 2909 1, in spite of changes necessary for compatibility between 32-bit 2910 and 64-bit machines. 2911 2912 2913 File: gmp.info, Node: Integer Random Numbers, Next: Integer Import and Export, Prev: I/O of Integers, Up: Integer Functions 2914 2915 5.13 Random Number Functions 2916 ============================ 2917 2918 The random number functions of GMP come in two groups; older function 2919 that rely on a global state, and newer functions that accept a state 2920 parameter that is read and modified. Please see the *note Random 2921 Number Functions:: for more information on how to use and not to use 2922 random number functions. 2923 2924 -- Function: void mpz_urandomb (mpz_t ROP, gmp_randstate_t STATE, 2925 mp_bitcnt_t N) 2926 Generate a uniformly distributed random integer in the range 0 to 2927 2^N-1, inclusive. 2928 2929 The variable STATE must be initialized by calling one of the 2930 `gmp_randinit' functions (*note Random State Initialization::) 2931 before invoking this function. 2932 2933 -- Function: void mpz_urandomm (mpz_t ROP, gmp_randstate_t STATE, 2934 mpz_t N) 2935 Generate a uniform random integer in the range 0 to N-1, inclusive. 2936 2937 The variable STATE must be initialized by calling one of the 2938 `gmp_randinit' functions (*note Random State Initialization::) 2939 before invoking this function. 2940 2941 -- Function: void mpz_rrandomb (mpz_t ROP, gmp_randstate_t STATE, 2942 mp_bitcnt_t N) 2943 Generate a random integer with long strings of zeros and ones in 2944 the binary representation. Useful for testing functions and 2945 algorithms, since this kind of random numbers have proven to be 2946 more likely to trigger corner-case bugs. The random number will 2947 be in the range 0 to 2^N-1, inclusive. 2948 2949 The variable STATE must be initialized by calling one of the 2950 `gmp_randinit' functions (*note Random State Initialization::) 2951 before invoking this function. 2952 2953 -- Function: void mpz_random (mpz_t ROP, mp_size_t MAX_SIZE) 2954 Generate a random integer of at most MAX_SIZE limbs. The generated 2955 random number doesn't satisfy any particular requirements of 2956 randomness. Negative random numbers are generated when MAX_SIZE 2957 is negative. 2958 2959 This function is obsolete. Use `mpz_urandomb' or `mpz_urandomm' 2960 instead. 2961 2962 -- Function: void mpz_random2 (mpz_t ROP, mp_size_t MAX_SIZE) 2963 Generate a random integer of at most MAX_SIZE limbs, with long 2964 strings of zeros and ones in the binary representation. Useful 2965 for testing functions and algorithms, since this kind of random 2966 numbers have proven to be more likely to trigger corner-case bugs. 2967 Negative random numbers are generated when MAX_SIZE is negative. 2968 2969 This function is obsolete. Use `mpz_rrandomb' instead. 2970 2971 2972 File: gmp.info, Node: Integer Import and Export, Next: Miscellaneous Integer Functions, Prev: Integer Random Numbers, Up: Integer Functions 2973 2974 5.14 Integer Import and Export 2975 ============================== 2976 2977 `mpz_t' variables can be converted to and from arbitrary words of binary 2978 data with the following functions. 2979 2980 -- Function: void mpz_import (mpz_t ROP, size_t COUNT, int ORDER, 2981 size_t SIZE, int ENDIAN, size_t NAILS, const void *OP) 2982 Set ROP from an array of word data at OP. 2983 2984 The parameters specify the format of the data. COUNT many words 2985 are read, each SIZE bytes. ORDER can be 1 for most significant 2986 word first or -1 for least significant first. Within each word 2987 ENDIAN can be 1 for most significant byte first, -1 for least 2988 significant first, or 0 for the native endianness of the host CPU. 2989 The most significant NAILS bits of each word are skipped, this can 2990 be 0 to use the full words. 2991 2992 There is no sign taken from the data, ROP will simply be a positive 2993 integer. An application can handle any sign itself, and apply it 2994 for instance with `mpz_neg'. 2995 2996 There are no data alignment restrictions on OP, any address is 2997 allowed. 2998 2999 Here's an example converting an array of `unsigned long' data, most 3000 significant element first, and host byte order within each value. 3001 3002 unsigned long a[20]; 3003 /* Initialize Z and A */ 3004 mpz_import (z, 20, 1, sizeof(a[0]), 0, 0, a); 3005 3006 This example assumes the full `sizeof' bytes are used for data in 3007 the given type, which is usually true, and certainly true for 3008 `unsigned long' everywhere we know of. However on Cray vector 3009 systems it may be noted that `short' and `int' are always stored 3010 in 8 bytes (and with `sizeof' indicating that) but use only 32 or 3011 46 bits. The NAILS feature can account for this, by passing for 3012 instance `8*sizeof(int)-INT_BIT'. 3013 3014 -- Function: void * mpz_export (void *ROP, size_t *COUNTP, int ORDER, 3015 size_t SIZE, int ENDIAN, size_t NAILS, mpz_t OP) 3016 Fill ROP with word data from OP. 3017 3018 The parameters specify the format of the data produced. Each word 3019 will be SIZE bytes and ORDER can be 1 for most significant word 3020 first or -1 for least significant first. Within each word ENDIAN 3021 can be 1 for most significant byte first, -1 for least significant 3022 first, or 0 for the native endianness of the host CPU. The most 3023 significant NAILS bits of each word are unused and set to zero, 3024 this can be 0 to produce full words. 3025 3026 The number of words produced is written to `*COUNTP', or COUNTP 3027 can be `NULL' to discard the count. ROP must have enough space 3028 for the data, or if ROP is `NULL' then a result array of the 3029 necessary size is allocated using the current GMP allocation 3030 function (*note Custom Allocation::). In either case the return 3031 value is the destination used, either ROP or the allocated block. 3032 3033 If OP is non-zero then the most significant word produced will be 3034 non-zero. If OP is zero then the count returned will be zero and 3035 nothing written to ROP. If ROP is `NULL' in this case, no block 3036 is allocated, just `NULL' is returned. 3037 3038 The sign of OP is ignored, just the absolute value is exported. An 3039 application can use `mpz_sgn' to get the sign and handle it as 3040 desired. (*note Integer Comparisons::) 3041 3042 There are no data alignment restrictions on ROP, any address is 3043 allowed. 3044 3045 When an application is allocating space itself the required size 3046 can be determined with a calculation like the following. Since 3047 `mpz_sizeinbase' always returns at least 1, `count' here will be 3048 at least one, which avoids any portability problems with 3049 `malloc(0)', though if `z' is zero no space at all is actually 3050 needed (or written). 3051 3052 numb = 8*size - nail; 3053 count = (mpz_sizeinbase (z, 2) + numb-1) / numb; 3054 p = malloc (count * size); 3055 3056 3057 File: gmp.info, Node: Miscellaneous Integer Functions, Next: Integer Special Functions, Prev: Integer Import and Export, Up: Integer Functions 3058 3059 5.15 Miscellaneous Functions 3060 ============================ 3061 3062 -- Function: int mpz_fits_ulong_p (mpz_t OP) 3063 -- Function: int mpz_fits_slong_p (mpz_t OP) 3064 -- Function: int mpz_fits_uint_p (mpz_t OP) 3065 -- Function: int mpz_fits_sint_p (mpz_t OP) 3066 -- Function: int mpz_fits_ushort_p (mpz_t OP) 3067 -- Function: int mpz_fits_sshort_p (mpz_t OP) 3068 Return non-zero iff the value of OP fits in an `unsigned long int', 3069 `signed long int', `unsigned int', `signed int', `unsigned short 3070 int', or `signed short int', respectively. Otherwise, return zero. 3071 3072 -- Macro: int mpz_odd_p (mpz_t OP) 3073 -- Macro: int mpz_even_p (mpz_t OP) 3074 Determine whether OP is odd or even, respectively. Return 3075 non-zero if yes, zero if no. These macros evaluate their argument 3076 more than once. 3077 3078 -- Function: size_t mpz_sizeinbase (mpz_t OP, int BASE) 3079 Return the size of OP measured in number of digits in the given 3080 BASE. BASE can vary from 2 to 62. The sign of OP is ignored, 3081 just the absolute value is used. The result will be either exact 3082 or 1 too big. If BASE is a power of 2, the result is always 3083 exact. If OP is zero the return value is always 1. 3084 3085 This function can be used to determine the space required when 3086 converting OP to a string. The right amount of allocation is 3087 normally two more than the value returned by `mpz_sizeinbase', one 3088 extra for a minus sign and one for the null-terminator. 3089 3090 It will be noted that `mpz_sizeinbase(OP,2)' can be used to locate 3091 the most significant 1 bit in OP, counting from 1. (Unlike the 3092 bitwise functions which start from 0, *Note Logical and Bit 3093 Manipulation Functions: Integer Logic and Bit Fiddling.) 3094 3095 3096 File: gmp.info, Node: Integer Special Functions, Prev: Miscellaneous Integer Functions, Up: Integer Functions 3097 3098 5.16 Special Functions 3099 ====================== 3100 3101 The functions in this section are for various special purposes. Most 3102 applications will not need them. 3103 3104 -- Function: void mpz_array_init (mpz_t INTEGER_ARRAY, mp_size_t 3105 ARRAY_SIZE, mp_size_t FIXED_NUM_BITS) 3106 This is a special type of initialization. *Fixed* space of 3107 FIXED_NUM_BITS is allocated to each of the ARRAY_SIZE integers in 3108 INTEGER_ARRAY. There is no way to free the storage allocated by 3109 this function. Don't call `mpz_clear'! 3110 3111 The INTEGER_ARRAY parameter is the first `mpz_t' in the array. For 3112 example, 3113 3114 mpz_t arr[20000]; 3115 mpz_array_init (arr[0], 20000, 512); 3116 3117 This function is only intended for programs that create a large 3118 number of integers and need to reduce memory usage by avoiding the 3119 overheads of allocating and reallocating lots of small blocks. In 3120 normal programs this function is not recommended. 3121 3122 The space allocated to each integer by this function will not be 3123 automatically increased, unlike the normal `mpz_init', so an 3124 application must ensure it is sufficient for any value stored. 3125 The following space requirements apply to various routines, 3126 3127 * `mpz_abs', `mpz_neg', `mpz_set', `mpz_set_si' and 3128 `mpz_set_ui' need room for the value they store. 3129 3130 * `mpz_add', `mpz_add_ui', `mpz_sub' and `mpz_sub_ui' need room 3131 for the larger of the two operands, plus an extra 3132 `mp_bits_per_limb'. 3133 3134 * `mpz_mul', `mpz_mul_ui' and `mpz_mul_si' need room for the sum 3135 of the number of bits in their operands, but each rounded up 3136 to a multiple of `mp_bits_per_limb'. 3137 3138 * `mpz_swap' can be used between two array variables, but not 3139 between an array and a normal variable. 3140 3141 For other functions, or if in doubt, the suggestion is to 3142 calculate in a regular `mpz_init' variable and copy the result to 3143 an array variable with `mpz_set'. 3144 3145 -- Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC) 3146 Change the space for INTEGER to NEW_ALLOC limbs. The value in 3147 INTEGER is preserved if it fits, or is set to 0 if not. The return 3148 value is not useful to applications and should be ignored. 3149 3150 `mpz_realloc2' is the preferred way to accomplish allocation 3151 changes like this. `mpz_realloc2' and `_mpz_realloc' are the same 3152 except that `_mpz_realloc' takes its size in limbs. 3153 3154 -- Function: mp_limb_t mpz_getlimbn (mpz_t OP, mp_size_t N) 3155 Return limb number N from OP. The sign of OP is ignored, just the 3156 absolute value is used. The least significant limb is number 0. 3157 3158 `mpz_size' can be used to find how many limbs make up OP. 3159 `mpz_getlimbn' returns zero if N is outside the range 0 to 3160 `mpz_size(OP)-1'. 3161 3162 -- Function: size_t mpz_size (mpz_t OP) 3163 Return the size of OP measured in number of limbs. If OP is zero, 3164 the returned value will be zero. 3165 3166 3167 File: gmp.info, Node: Rational Number Functions, Next: Floating-point Functions, Prev: Integer Functions, Up: Top 3168 3169 6 Rational Number Functions 3170 *************************** 3171 3172 This chapter describes the GMP functions for performing arithmetic on 3173 rational numbers. These functions start with the prefix `mpq_'. 3174 3175 Rational numbers are stored in objects of type `mpq_t'. 3176 3177 All rational arithmetic functions assume operands have a canonical 3178 form, and canonicalize their result. The canonical from means that the 3179 denominator and the numerator have no common factors, and that the 3180 denominator is positive. Zero has the unique representation 0/1. 3181 3182 Pure assignment functions do not canonicalize the assigned variable. 3183 It is the responsibility of the user to canonicalize the assigned 3184 variable before any arithmetic operations are performed on that 3185 variable. 3186 3187 -- Function: void mpq_canonicalize (mpq_t OP) 3188 Remove any factors that are common to the numerator and 3189 denominator of OP, and make the denominator positive. 3190 3191 * Menu: 3192 3193 * Initializing Rationals:: 3194 * Rational Conversions:: 3195 * Rational Arithmetic:: 3196 * Comparing Rationals:: 3197 * Applying Integer Functions:: 3198 * I/O of Rationals:: 3199 3200 3201 File: gmp.info, Node: Initializing Rationals, Next: Rational Conversions, Prev: Rational Number Functions, Up: Rational Number Functions 3202 3203 6.1 Initialization and Assignment Functions 3204 =========================================== 3205 3206 -- Function: void mpq_init (mpq_t X) 3207 Initialize X and set it to 0/1. Each variable should normally 3208 only be initialized once, or at least cleared out (using the 3209 function `mpq_clear') between each initialization. 3210 3211 -- Function: void mpq_inits (mpq_t X, ...) 3212 Initialize a NULL-terminated list of `mpq_t' variables, and set 3213 their values to 0/1. 3214 3215 -- Function: void mpq_clear (mpq_t X) 3216 Free the space occupied by X. Make sure to call this function for 3217 all `mpq_t' variables when you are done with them. 3218 3219 -- Function: void mpq_clears (mpq_t X, ...) 3220 Free the space occupied by a NULL-terminated list of `mpq_t' 3221 variables. 3222 3223 -- Function: void mpq_set (mpq_t ROP, mpq_t OP) 3224 -- Function: void mpq_set_z (mpq_t ROP, mpz_t OP) 3225 Assign ROP from OP. 3226 3227 -- Function: void mpq_set_ui (mpq_t ROP, unsigned long int OP1, 3228 unsigned long int OP2) 3229 -- Function: void mpq_set_si (mpq_t ROP, signed long int OP1, unsigned 3230 long int OP2) 3231 Set the value of ROP to OP1/OP2. Note that if OP1 and OP2 have 3232 common factors, ROP has to be passed to `mpq_canonicalize' before 3233 any operations are performed on ROP. 3234 3235 -- Function: int mpq_set_str (mpq_t ROP, char *STR, int BASE) 3236 Set ROP from a null-terminated string STR in the given BASE. 3237 3238 The string can be an integer like "41" or a fraction like 3239 "41/152". The fraction must be in canonical form (*note Rational 3240 Number Functions::), or if not then `mpq_canonicalize' must be 3241 called. 3242 3243 The numerator and optional denominator are parsed the same as in 3244 `mpz_set_str' (*note Assigning Integers::). White space is 3245 allowed in the string, and is simply ignored. The BASE can vary 3246 from 2 to 62, or if BASE is 0 then the leading characters are 3247 used: `0x' or `0X' for hex, `0b' or `0B' for binary, `0' for 3248 octal, or decimal otherwise. Note that this is done separately 3249 for the numerator and denominator, so for instance `0xEF/100' is 3250 239/100, whereas `0xEF/0x100' is 239/256. 3251 3252 The return value is 0 if the entire string is a valid number, or 3253 -1 if not. 3254 3255 -- Function: void mpq_swap (mpq_t ROP1, mpq_t ROP2) 3256 Swap the values ROP1 and ROP2 efficiently. 3257 3258 3259 File: gmp.info, Node: Rational Conversions, Next: Rational Arithmetic, Prev: Initializing Rationals, Up: Rational Number Functions 3260 3261 6.2 Conversion Functions 3262 ======================== 3263 3264 -- Function: double mpq_get_d (mpq_t OP) 3265 Convert OP to a `double', truncating if necessary (i.e. rounding 3266 towards zero). 3267 3268 If the exponent from the conversion is too big or too small to fit 3269 a `double' then the result is system dependent. For too big an 3270 infinity is returned when available. For too small 0.0 is 3271 normally returned. Hardware overflow, underflow and denorm traps 3272 may or may not occur. 3273 3274 -- Function: void mpq_set_d (mpq_t ROP, double OP) 3275 -- Function: void mpq_set_f (mpq_t ROP, mpf_t OP) 3276 Set ROP to the value of OP. There is no rounding, this conversion 3277 is exact. 3278 3279 -- Function: char * mpq_get_str (char *STR, int BASE, mpq_t OP) 3280 Convert OP to a string of digits in base BASE. The base may vary 3281 from 2 to 36. The string will be of the form `num/den', or if the 3282 denominator is 1 then just `num'. 3283 3284 If STR is `NULL', the result string is allocated using the current 3285 allocation function (*note Custom Allocation::). The block will be 3286 `strlen(str)+1' bytes, that being exactly enough for the string and 3287 null-terminator. 3288 3289 If STR is not `NULL', it should point to a block of storage large 3290 enough for the result, that being 3291 3292 mpz_sizeinbase (mpq_numref(OP), BASE) 3293 + mpz_sizeinbase (mpq_denref(OP), BASE) + 3 3294 3295 The three extra bytes are for a possible minus sign, possible 3296 slash, and the null-terminator. 3297 3298 A pointer to the result string is returned, being either the 3299 allocated block, or the given STR. 3300 3301 3302 File: gmp.info, Node: Rational Arithmetic, Next: Comparing Rationals, Prev: Rational Conversions, Up: Rational Number Functions 3303 3304 6.3 Arithmetic Functions 3305 ======================== 3306 3307 -- Function: void mpq_add (mpq_t SUM, mpq_t ADDEND1, mpq_t ADDEND2) 3308 Set SUM to ADDEND1 + ADDEND2. 3309 3310 -- Function: void mpq_sub (mpq_t DIFFERENCE, mpq_t MINUEND, mpq_t 3311 SUBTRAHEND) 3312 Set DIFFERENCE to MINUEND - SUBTRAHEND. 3313 3314 -- Function: void mpq_mul (mpq_t PRODUCT, mpq_t MULTIPLIER, mpq_t 3315 MULTIPLICAND) 3316 Set PRODUCT to MULTIPLIER times MULTIPLICAND. 3317 3318 -- Function: void mpq_mul_2exp (mpq_t ROP, mpq_t OP1, mp_bitcnt_t OP2) 3319 Set ROP to OP1 times 2 raised to OP2. 3320 3321 -- Function: void mpq_div (mpq_t QUOTIENT, mpq_t DIVIDEND, mpq_t 3322 DIVISOR) 3323 Set QUOTIENT to DIVIDEND/DIVISOR. 3324 3325 -- Function: void mpq_div_2exp (mpq_t ROP, mpq_t OP1, mp_bitcnt_t OP2) 3326 Set ROP to OP1 divided by 2 raised to OP2. 3327 3328 -- Function: void mpq_neg (mpq_t NEGATED_OPERAND, mpq_t OPERAND) 3329 Set NEGATED_OPERAND to -OPERAND. 3330 3331 -- Function: void mpq_abs (mpq_t ROP, mpq_t OP) 3332 Set ROP to the absolute value of OP. 3333 3334 -- Function: void mpq_inv (mpq_t INVERTED_NUMBER, mpq_t NUMBER) 3335 Set INVERTED_NUMBER to 1/NUMBER. If the new denominator is zero, 3336 this routine will divide by zero. 3337 3338 3339 File: gmp.info, Node: Comparing Rationals, Next: Applying Integer Functions, Prev: Rational Arithmetic, Up: Rational Number Functions 3340 3341 6.4 Comparison Functions 3342 ======================== 3343 3344 -- Function: int mpq_cmp (mpq_t OP1, mpq_t OP2) 3345 Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero 3346 if OP1 = OP2, and a negative value if OP1 < OP2. 3347 3348 To determine if two rationals are equal, `mpq_equal' is faster than 3349 `mpq_cmp'. 3350 3351 -- Macro: int mpq_cmp_ui (mpq_t OP1, unsigned long int NUM2, unsigned 3352 long int DEN2) 3353 -- Macro: int mpq_cmp_si (mpq_t OP1, long int NUM2, unsigned long int 3354 DEN2) 3355 Compare OP1 and NUM2/DEN2. Return a positive value if OP1 > 3356 NUM2/DEN2, zero if OP1 = NUM2/DEN2, and a negative value if OP1 < 3357 NUM2/DEN2. 3358 3359 NUM2 and DEN2 are allowed to have common factors. 3360 3361 These functions are implemented as a macros and evaluate their 3362 arguments multiple times. 3363 3364 -- Macro: int mpq_sgn (mpq_t OP) 3365 Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. 3366 3367 This function is actually implemented as a macro. It evaluates its 3368 arguments multiple times. 3369 3370 -- Function: int mpq_equal (mpq_t OP1, mpq_t OP2) 3371 Return non-zero if OP1 and OP2 are equal, zero if they are 3372 non-equal. Although `mpq_cmp' can be used for the same purpose, 3373 this function is much faster. 3374 3375 3376 File: gmp.info, Node: Applying Integer Functions, Next: I/O of Rationals, Prev: Comparing Rationals, Up: Rational Number Functions 3377 3378 6.5 Applying Integer Functions to Rationals 3379 =========================================== 3380 3381 The set of `mpq' functions is quite small. In particular, there are few 3382 functions for either input or output. The following functions give 3383 direct access to the numerator and denominator of an `mpq_t'. 3384 3385 Note that if an assignment to the numerator and/or denominator could 3386 take an `mpq_t' out of the canonical form described at the start of 3387 this chapter (*note Rational Number Functions::) then 3388 `mpq_canonicalize' must be called before any other `mpq' functions are 3389 applied to that `mpq_t'. 3390 3391 -- Macro: mpz_t mpq_numref (mpq_t OP) 3392 -- Macro: mpz_t mpq_denref (mpq_t OP) 3393 Return a reference to the numerator and denominator of OP, 3394 respectively. The `mpz' functions can be used on the result of 3395 these macros. 3396 3397 -- Function: void mpq_get_num (mpz_t NUMERATOR, mpq_t RATIONAL) 3398 -- Function: void mpq_get_den (mpz_t DENOMINATOR, mpq_t RATIONAL) 3399 -- Function: void mpq_set_num (mpq_t RATIONAL, mpz_t NUMERATOR) 3400 -- Function: void mpq_set_den (mpq_t RATIONAL, mpz_t DENOMINATOR) 3401 Get or set the numerator or denominator of a rational. These 3402 functions are equivalent to calling `mpz_set' with an appropriate 3403 `mpq_numref' or `mpq_denref'. Direct use of `mpq_numref' or 3404 `mpq_denref' is recommended instead of these functions. 3405 3406 3407 File: gmp.info, Node: I/O of Rationals, Prev: Applying Integer Functions, Up: Rational Number Functions 3408 3409 6.6 Input and Output Functions 3410 ============================== 3411 3412 Functions that perform input from a stdio stream, and functions that 3413 output to a stdio stream, of `mpq' numbers. Passing a `NULL' pointer 3414 for a STREAM argument to any of these functions will make them read from 3415 `stdin' and write to `stdout', respectively. 3416 3417 When using any of these functions, it is a good idea to include 3418 `stdio.h' before `gmp.h', since that will allow `gmp.h' to define 3419 prototypes for these functions. 3420 3421 See also *note Formatted Output:: and *note Formatted Input::. 3422 3423 -- Function: size_t mpq_out_str (FILE *STREAM, int BASE, mpq_t OP) 3424 Output OP on stdio stream STREAM, as a string of digits in base 3425 BASE. The base may vary from 2 to 36. Output is in the form 3426 `num/den' or if the denominator is 1 then just `num'. 3427 3428 Return the number of bytes written, or if an error occurred, 3429 return 0. 3430 3431 -- Function: size_t mpq_inp_str (mpq_t ROP, FILE *STREAM, int BASE) 3432 Read a string of digits from STREAM and convert them to a rational 3433 in ROP. Any initial white-space characters are read and 3434 discarded. Return the number of characters read (including white 3435 space), or 0 if a rational could not be read. 3436 3437 The input can be a fraction like `17/63' or just an integer like 3438 `123'. Reading stops at the first character not in this form, and 3439 white space is not permitted within the string. If the input 3440 might not be in canonical form, then `mpq_canonicalize' must be 3441 called (*note Rational Number Functions::). 3442 3443 The BASE can be between 2 and 36, or can be 0 in which case the 3444 leading characters of the string determine the base, `0x' or `0X' 3445 for hexadecimal, `0' for octal, or decimal otherwise. The leading 3446 characters are examined separately for the numerator and 3447 denominator of a fraction, so for instance `0x10/11' is 16/11, 3448 whereas `0x10/0x11' is 16/17. 3449 3450 3451 File: gmp.info, Node: Floating-point Functions, Next: Low-level Functions, Prev: Rational Number Functions, Up: Top 3452 3453 7 Floating-point Functions 3454 ************************** 3455 3456 GMP floating point numbers are stored in objects of type `mpf_t' and 3457 functions operating on them have an `mpf_' prefix. 3458 3459 The mantissa of each float has a user-selectable precision, limited 3460 only by available memory. Each variable has its own precision, and 3461 that can be increased or decreased at any time. 3462 3463 The exponent of each float is a fixed precision, one machine word on 3464 most systems. In the current implementation the exponent is a count of 3465 limbs, so for example on a 32-bit system this means a range of roughly 3466 2^-68719476768 to 2^68719476736, or on a 64-bit system this will be 3467 greater. Note however `mpf_get_str' can only return an exponent which 3468 fits an `mp_exp_t' and currently `mpf_set_str' doesn't accept exponents 3469 bigger than a `long'. 3470 3471 Each variable keeps a size for the mantissa data actually in use. 3472 This means that if a float is exactly represented in only a few bits 3473 then only those bits will be used in a calculation, even if the 3474 selected precision is high. 3475 3476 All calculations are performed to the precision of the destination 3477 variable. Each function is defined to calculate with "infinite 3478 precision" followed by a truncation to the destination precision, but 3479 of course the work done is only what's needed to determine a result 3480 under that definition. 3481 3482 The precision selected for a variable is a minimum value, GMP may 3483 increase it a little to facilitate efficient calculation. Currently 3484 this means rounding up to a whole limb, and then sometimes having a 3485 further partial limb, depending on the high limb of the mantissa. But 3486 applications shouldn't be concerned by such details. 3487 3488 The mantissa in stored in binary, as might be imagined from the fact 3489 precisions are expressed in bits. One consequence of this is that 3490 decimal fractions like 0.1 cannot be represented exactly. The same is 3491 true of plain IEEE `double' floats. This makes both highly unsuitable 3492 for calculations involving money or other values that should be exact 3493 decimal fractions. (Suitably scaled integers, or perhaps rationals, 3494 are better choices.) 3495 3496 `mpf' functions and variables have no special notion of infinity or 3497 not-a-number, and applications must take care not to overflow the 3498 exponent or results will be unpredictable. This might change in a 3499 future release. 3500 3501 Note that the `mpf' functions are _not_ intended as a smooth 3502 extension to IEEE P754 arithmetic. In particular results obtained on 3503 one computer often differ from the results on a computer with a 3504 different word size. 3505 3506 * Menu: 3507 3508 * Initializing Floats:: 3509 * Assigning Floats:: 3510 * Simultaneous Float Init & Assign:: 3511 * Converting Floats:: 3512 * Float Arithmetic:: 3513 * Float Comparison:: 3514 * I/O of Floats:: 3515 * Miscellaneous Float Functions:: 3516 3517 3518 File: gmp.info, Node: Initializing Floats, Next: Assigning Floats, Prev: Floating-point Functions, Up: Floating-point Functions 3519 3520 7.1 Initialization Functions 3521 ============================ 3522 3523 -- Function: void mpf_set_default_prec (mp_bitcnt_t PREC) 3524 Set the default precision to be *at least* PREC bits. All 3525 subsequent calls to `mpf_init' will use this precision, but 3526 previously initialized variables are unaffected. 3527 3528 -- Function: mp_bitcnt_t mpf_get_default_prec (void) 3529 Return the default precision actually used. 3530 3531 An `mpf_t' object must be initialized before storing the first value 3532 in it. The functions `mpf_init' and `mpf_init2' are used for that 3533 purpose. 3534 3535 -- Function: void mpf_init (mpf_t X) 3536 Initialize X to 0. Normally, a variable should be initialized 3537 once only or at least be cleared, using `mpf_clear', between 3538 initializations. The precision of X is undefined unless a default 3539 precision has already been established by a call to 3540 `mpf_set_default_prec'. 3541 3542 -- Function: void mpf_init2 (mpf_t X, mp_bitcnt_t PREC) 3543 Initialize X to 0 and set its precision to be *at least* PREC 3544 bits. Normally, a variable should be initialized once only or at 3545 least be cleared, using `mpf_clear', between initializations. 3546 3547 -- Function: void mpf_inits (mpf_t X, ...) 3548 Initialize a NULL-terminated list of `mpf_t' variables, and set 3549 their values to 0. The precision of the initialized variables is 3550 undefined unless a default precision has already been established 3551 by a call to `mpf_set_default_prec'. 3552 3553 -- Function: void mpf_clear (mpf_t X) 3554 Free the space occupied by X. Make sure to call this function for 3555 all `mpf_t' variables when you are done with them. 3556 3557 -- Function: void mpf_clears (mpf_t X, ...) 3558 Free the space occupied by a NULL-terminated list of `mpf_t' 3559 variables. 3560 3561 Here is an example on how to initialize floating-point variables: 3562 { 3563 mpf_t x, y; 3564 mpf_init (x); /* use default precision */ 3565 mpf_init2 (y, 256); /* precision _at least_ 256 bits */ 3566 ... 3567 /* Unless the program is about to exit, do ... */ 3568 mpf_clear (x); 3569 mpf_clear (y); 3570 } 3571 3572 The following three functions are useful for changing the precision 3573 during a calculation. A typical use would be for adjusting the 3574 precision gradually in iterative algorithms like Newton-Raphson, making 3575 the computation precision closely match the actual accurate part of the 3576 numbers. 3577 3578 -- Function: mp_bitcnt_t mpf_get_prec (mpf_t OP) 3579 Return the current precision of OP, in bits. 3580 3581 -- Function: void mpf_set_prec (mpf_t ROP, mp_bitcnt_t PREC) 3582 Set the precision of ROP to be *at least* PREC bits. The value in 3583 ROP will be truncated to the new precision. 3584 3585 This function requires a call to `realloc', and so should not be 3586 used in a tight loop. 3587 3588 -- Function: void mpf_set_prec_raw (mpf_t ROP, mp_bitcnt_t PREC) 3589 Set the precision of ROP to be *at least* PREC bits, without 3590 changing the memory allocated. 3591 3592 PREC must be no more than the allocated precision for ROP, that 3593 being the precision when ROP was initialized, or in the most recent 3594 `mpf_set_prec'. 3595 3596 The value in ROP is unchanged, and in particular if it had a higher 3597 precision than PREC it will retain that higher precision. New 3598 values written to ROP will use the new PREC. 3599 3600 Before calling `mpf_clear' or the full `mpf_set_prec', another 3601 `mpf_set_prec_raw' call must be made to restore ROP to its original 3602 allocated precision. Failing to do so will have unpredictable 3603 results. 3604 3605 `mpf_get_prec' can be used before `mpf_set_prec_raw' to get the 3606 original allocated precision. After `mpf_set_prec_raw' it 3607 reflects the PREC value set. 3608 3609 `mpf_set_prec_raw' is an efficient way to use an `mpf_t' variable 3610 at different precisions during a calculation, perhaps to gradually 3611 increase precision in an iteration, or just to use various 3612 different precisions for different purposes during a calculation. 3613 3614 3615 File: gmp.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions 3616 3617 7.2 Assignment Functions 3618 ======================== 3619 3620 These functions assign new values to already initialized floats (*note 3621 Initializing Floats::). 3622 3623 -- Function: void mpf_set (mpf_t ROP, mpf_t OP) 3624 -- Function: void mpf_set_ui (mpf_t ROP, unsigned long int OP) 3625 -- Function: void mpf_set_si (mpf_t ROP, signed long int OP) 3626 -- Function: void mpf_set_d (mpf_t ROP, double OP) 3627 -- Function: void mpf_set_z (mpf_t ROP, mpz_t OP) 3628 -- Function: void mpf_set_q (mpf_t ROP, mpq_t OP) 3629 Set the value of ROP from OP. 3630 3631 -- Function: int mpf_set_str (mpf_t ROP, char *STR, int BASE) 3632 Set the value of ROP from the string in STR. The string is of the 3633 form `M@N' or, if the base is 10 or less, alternatively `MeN'. 3634 `M' is the mantissa and `N' is the exponent. The mantissa is 3635 always in the specified base. The exponent is either in the 3636 specified base or, if BASE is negative, in decimal. The decimal 3637 point expected is taken from the current locale, on systems 3638 providing `localeconv'. 3639 3640 The argument BASE may be in the ranges 2 to 62, or -62 to -2. 3641 Negative values are used to specify that the exponent is in 3642 decimal. 3643 3644 For bases up to 36, case is ignored; upper-case and lower-case 3645 letters have the same value; for bases 37 to 62, upper-case letter 3646 represent the usual 10..35 while lower-case letter represent 3647 36..61. 3648 3649 Unlike the corresponding `mpz' function, the base will not be 3650 determined from the leading characters of the string if BASE is 0. 3651 This is so that numbers like `0.23' are not interpreted as octal. 3652 3653 White space is allowed in the string, and is simply ignored. 3654 [This is not really true; white-space is ignored in the beginning 3655 of the string and within the mantissa, but not in other places, 3656 such as after a minus sign or in the exponent. We are considering 3657 changing the definition of this function, making it fail when 3658 there is any white-space in the input, since that makes a lot of 3659 sense. Please tell us your opinion about this change. Do you 3660 really want it to accept "3 14" as meaning 314 as it does now?] 3661 3662 This function returns 0 if the entire string is a valid number in 3663 base BASE. Otherwise it returns -1. 3664 3665 -- Function: void mpf_swap (mpf_t ROP1, mpf_t ROP2) 3666 Swap ROP1 and ROP2 efficiently. Both the values and the 3667 precisions of the two variables are swapped. 3668 3669 3670 File: gmp.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions 3671 3672 7.3 Combined Initialization and Assignment Functions 3673 ==================================================== 3674 3675 For convenience, GMP provides a parallel series of initialize-and-set 3676 functions which initialize the output and then store the value there. 3677 These functions' names have the form `mpf_init_set...' 3678 3679 Once the float has been initialized by any of the `mpf_init_set...' 3680 functions, it can be used as the source or destination operand for the 3681 ordinary float functions. Don't use an initialize-and-set function on 3682 a variable already initialized! 3683 3684 -- Function: void mpf_init_set (mpf_t ROP, mpf_t OP) 3685 -- Function: void mpf_init_set_ui (mpf_t ROP, unsigned long int OP) 3686 -- Function: void mpf_init_set_si (mpf_t ROP, signed long int OP) 3687 -- Function: void mpf_init_set_d (mpf_t ROP, double OP) 3688 Initialize ROP and set its value from OP. 3689 3690 The precision of ROP will be taken from the active default 3691 precision, as set by `mpf_set_default_prec'. 3692 3693 -- Function: int mpf_init_set_str (mpf_t ROP, char *STR, int BASE) 3694 Initialize ROP and set its value from the string in STR. See 3695 `mpf_set_str' above for details on the assignment operation. 3696 3697 Note that ROP is initialized even if an error occurs. (I.e., you 3698 have to call `mpf_clear' for it.) 3699 3700 The precision of ROP will be taken from the active default 3701 precision, as set by `mpf_set_default_prec'. 3702 3703 3704 File: gmp.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions 3705 3706 7.4 Conversion Functions 3707 ======================== 3708 3709 -- Function: double mpf_get_d (mpf_t OP) 3710 Convert OP to a `double', truncating if necessary (i.e. rounding 3711 towards zero). 3712 3713 If the exponent in OP is too big or too small to fit a `double' 3714 then the result is system dependent. For too big an infinity is 3715 returned when available. For too small 0.0 is normally returned. 3716 Hardware overflow, underflow and denorm traps may or may not occur. 3717 3718 -- Function: double mpf_get_d_2exp (signed long int *EXP, mpf_t OP) 3719 Convert OP to a `double', truncating if necessary (i.e. rounding 3720 towards zero), and with an exponent returned separately. 3721 3722 The return value is in the range 0.5<=abs(D)<1 and the exponent is 3723 stored to `*EXP'. D * 2^EXP is the (truncated) OP value. If OP 3724 is zero, the return is 0.0 and 0 is stored to `*EXP'. 3725 3726 This is similar to the standard C `frexp' function (*note 3727 Normalization Functions: (libc)Normalization Functions.). 3728 3729 -- Function: long mpf_get_si (mpf_t OP) 3730 -- Function: unsigned long mpf_get_ui (mpf_t OP) 3731 Convert OP to a `long' or `unsigned long', truncating any fraction 3732 part. If OP is too big for the return type, the result is 3733 undefined. 3734 3735 See also `mpf_fits_slong_p' and `mpf_fits_ulong_p' (*note 3736 Miscellaneous Float Functions::). 3737 3738 -- Function: char * mpf_get_str (char *STR, mp_exp_t *EXPPTR, int 3739 BASE, size_t N_DIGITS, mpf_t OP) 3740 Convert OP to a string of digits in base BASE. The base argument 3741 may vary from 2 to 62 or from -2 to -36. Up to N_DIGITS digits 3742 will be generated. Trailing zeros are not returned. No more 3743 digits than can be accurately represented by OP are ever 3744 generated. If N_DIGITS is 0 then that accurate maximum number of 3745 digits are generated. 3746 3747 For BASE in the range 2..36, digits and lower-case letters are 3748 used; for -2..-36, digits and upper-case letters are used; for 3749 37..62, digits, upper-case letters, and lower-case letters (in 3750 that significance order) are used. 3751 3752 If STR is `NULL', the result string is allocated using the current 3753 allocation function (*note Custom Allocation::). The block will be 3754 `strlen(str)+1' bytes, that being exactly enough for the string and 3755 null-terminator. 3756 3757 If STR is not `NULL', it should point to a block of N_DIGITS + 2 3758 bytes, that being enough for the mantissa, a possible minus sign, 3759 and a null-terminator. When N_DIGITS is 0 to get all significant 3760 digits, an application won't be able to know the space required, 3761 and STR should be `NULL' in that case. 3762 3763 The generated string is a fraction, with an implicit radix point 3764 immediately to the left of the first digit. The applicable 3765 exponent is written through the EXPPTR pointer. For example, the 3766 number 3.1416 would be returned as string "31416" and exponent 1. 3767 3768 When OP is zero, an empty string is produced and the exponent 3769 returned is 0. 3770 3771 A pointer to the result string is returned, being either the 3772 allocated block or the given STR. 3773 3774 3775 File: gmp.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions 3776 3777 7.5 Arithmetic Functions 3778 ======================== 3779 3780 -- Function: void mpf_add (mpf_t ROP, mpf_t OP1, mpf_t OP2) 3781 -- Function: void mpf_add_ui (mpf_t ROP, mpf_t OP1, unsigned long int 3782 OP2) 3783 Set ROP to OP1 + OP2. 3784 3785 -- Function: void mpf_sub (mpf_t ROP, mpf_t OP1, mpf_t OP2) 3786 -- Function: void mpf_ui_sub (mpf_t ROP, unsigned long int OP1, mpf_t 3787 OP2) 3788 -- Function: void mpf_sub_ui (mpf_t ROP, mpf_t OP1, unsigned long int 3789 OP2) 3790 Set ROP to OP1 - OP2. 3791 3792 -- Function: void mpf_mul (mpf_t ROP, mpf_t OP1, mpf_t OP2) 3793 -- Function: void mpf_mul_ui (mpf_t ROP, mpf_t OP1, unsigned long int 3794 OP2) 3795 Set ROP to OP1 times OP2. 3796 3797 Division is undefined if the divisor is zero, and passing a zero 3798 divisor to the divide functions will make these functions intentionally 3799 divide by zero. This lets the user handle arithmetic exceptions in 3800 these functions in the same manner as other arithmetic exceptions. 3801 3802 -- Function: void mpf_div (mpf_t ROP, mpf_t OP1, mpf_t OP2) 3803 -- Function: void mpf_ui_div (mpf_t ROP, unsigned long int OP1, mpf_t 3804 OP2) 3805 -- Function: void mpf_div_ui (mpf_t ROP, mpf_t OP1, unsigned long int 3806 OP2) 3807 Set ROP to OP1/OP2. 3808 3809 -- Function: void mpf_sqrt (mpf_t ROP, mpf_t OP) 3810 -- Function: void mpf_sqrt_ui (mpf_t ROP, unsigned long int OP) 3811 Set ROP to the square root of OP. 3812 3813 -- Function: void mpf_pow_ui (mpf_t ROP, mpf_t OP1, unsigned long int 3814 OP2) 3815 Set ROP to OP1 raised to the power OP2. 3816 3817 -- Function: void mpf_neg (mpf_t ROP, mpf_t OP) 3818 Set ROP to -OP. 3819 3820 -- Function: void mpf_abs (mpf_t ROP, mpf_t OP) 3821 Set ROP to the absolute value of OP. 3822 3823 -- Function: void mpf_mul_2exp (mpf_t ROP, mpf_t OP1, mp_bitcnt_t OP2) 3824 Set ROP to OP1 times 2 raised to OP2. 3825 3826 -- Function: void mpf_div_2exp (mpf_t ROP, mpf_t OP1, mp_bitcnt_t OP2) 3827 Set ROP to OP1 divided by 2 raised to OP2. 3828 3829 3830 File: gmp.info, Node: Float Comparison, Next: I/O of Floats, Prev: Float Arithmetic, Up: Floating-point Functions 3831 3832 7.6 Comparison Functions 3833 ======================== 3834 3835 -- Function: int mpf_cmp (mpf_t OP1, mpf_t OP2) 3836 -- Function: int mpf_cmp_d (mpf_t OP1, double OP2) 3837 -- Function: int mpf_cmp_ui (mpf_t OP1, unsigned long int OP2) 3838 -- Function: int mpf_cmp_si (mpf_t OP1, signed long int OP2) 3839 Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero 3840 if OP1 = OP2, and a negative value if OP1 < OP2. 3841 3842 `mpf_cmp_d' can be called with an infinity, but results are 3843 undefined for a NaN. 3844 3845 -- Function: int mpf_eq (mpf_t OP1, mpf_t OP2, mp_bitcnt_t op3) 3846 Return non-zero if the first OP3 bits of OP1 and OP2 are equal, 3847 zero otherwise. I.e., test if OP1 and OP2 are approximately equal. 3848 3849 Caution 1: All version of GMP up to version 4.2.4 compared just 3850 whole limbs, meaning sometimes more than OP3 bits, sometimes fewer. 3851 3852 Caution 2: This function will consider XXX11...111 and XX100...000 3853 different, even if ... is replaced by a semi-infinite number of 3854 bits. Such numbers are really just one ulp off, and should be 3855 considered equal. 3856 3857 -- Function: void mpf_reldiff (mpf_t ROP, mpf_t OP1, mpf_t OP2) 3858 Compute the relative difference between OP1 and OP2 and store the 3859 result in ROP. This is abs(OP1-OP2)/OP1. 3860 3861 -- Macro: int mpf_sgn (mpf_t OP) 3862 Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. 3863 3864 This function is actually implemented as a macro. It evaluates 3865 its arguments multiple times. 3866 3867 3868 File: gmp.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions 3869 3870 7.7 Input and Output Functions 3871 ============================== 3872 3873 Functions that perform input from a stdio stream, and functions that 3874 output to a stdio stream, of `mpf' numbers. Passing a `NULL' pointer 3875 for a STREAM argument to any of these functions will make them read from 3876 `stdin' and write to `stdout', respectively. 3877 3878 When using any of these functions, it is a good idea to include 3879 `stdio.h' before `gmp.h', since that will allow `gmp.h' to define 3880 prototypes for these functions. 3881 3882 See also *note Formatted Output:: and *note Formatted Input::. 3883 3884 -- Function: size_t mpf_out_str (FILE *STREAM, int BASE, size_t 3885 N_DIGITS, mpf_t OP) 3886 Print OP to STREAM, as a string of digits. Return the number of 3887 bytes written, or if an error occurred, return 0. 3888 3889 The mantissa is prefixed with an `0.' and is in the given BASE, 3890 which may vary from 2 to 62 or from -2 to -36. An exponent is 3891 then printed, separated by an `e', or if the base is greater than 3892 10 then by an `@'. The exponent is always in decimal. The 3893 decimal point follows the current locale, on systems providing 3894 `localeconv'. 3895 3896 For BASE in the range 2..36, digits and lower-case letters are 3897 used; for -2..-36, digits and upper-case letters are used; for 3898 37..62, digits, upper-case letters, and lower-case letters (in 3899 that significance order) are used. 3900 3901 Up to N_DIGITS will be printed from the mantissa, except that no 3902 more digits than are accurately representable by OP will be 3903 printed. N_DIGITS can be 0 to select that accurate maximum. 3904 3905 -- Function: size_t mpf_inp_str (mpf_t ROP, FILE *STREAM, int BASE) 3906 Read a string in base BASE from STREAM, and put the read float in 3907 ROP. The string is of the form `M@N' or, if the base is 10 or 3908 less, alternatively `MeN'. `M' is the mantissa and `N' is the 3909 exponent. The mantissa is always in the specified base. The 3910 exponent is either in the specified base or, if BASE is negative, 3911 in decimal. The decimal point expected is taken from the current 3912 locale, on systems providing `localeconv'. 3913 3914 The argument BASE may be in the ranges 2 to 36, or -36 to -2. 3915 Negative values are used to specify that the exponent is in 3916 decimal. 3917 3918 Unlike the corresponding `mpz' function, the base will not be 3919 determined from the leading characters of the string if BASE is 0. 3920 This is so that numbers like `0.23' are not interpreted as octal. 3921 3922 Return the number of bytes read, or if an error occurred, return 0. 3923 3924 3925 File: gmp.info, Node: Miscellaneous Float Functions, Prev: I/O of Floats, Up: Floating-point Functions 3926 3927 7.8 Miscellaneous Functions 3928 =========================== 3929 3930 -- Function: void mpf_ceil (mpf_t ROP, mpf_t OP) 3931 -- Function: void mpf_floor (mpf_t ROP, mpf_t OP) 3932 -- Function: void mpf_trunc (mpf_t ROP, mpf_t OP) 3933 Set ROP to OP rounded to an integer. `mpf_ceil' rounds to the 3934 next higher integer, `mpf_floor' to the next lower, and `mpf_trunc' 3935 to the integer towards zero. 3936 3937 -- Function: int mpf_integer_p (mpf_t OP) 3938 Return non-zero if OP is an integer. 3939 3940 -- Function: int mpf_fits_ulong_p (mpf_t OP) 3941 -- Function: int mpf_fits_slong_p (mpf_t OP) 3942 -- Function: int mpf_fits_uint_p (mpf_t OP) 3943 -- Function: int mpf_fits_sint_p (mpf_t OP) 3944 -- Function: int mpf_fits_ushort_p (mpf_t OP) 3945 -- Function: int mpf_fits_sshort_p (mpf_t OP) 3946 Return non-zero if OP would fit in the respective C data type, when 3947 truncated to an integer. 3948 3949 -- Function: void mpf_urandomb (mpf_t ROP, gmp_randstate_t STATE, 3950 mp_bitcnt_t NBITS) 3951 Generate a uniformly distributed random float in ROP, such that 0 3952 <= ROP < 1, with NBITS significant bits in the mantissa or less if 3953 the precision of ROP is smaller. 3954 3955 The variable STATE must be initialized by calling one of the 3956 `gmp_randinit' functions (*note Random State Initialization::) 3957 before invoking this function. 3958 3959 -- Function: void mpf_random2 (mpf_t ROP, mp_size_t MAX_SIZE, mp_exp_t 3960 EXP) 3961 Generate a random float of at most MAX_SIZE limbs, with long 3962 strings of zeros and ones in the binary representation. The 3963 exponent of the number is in the interval -EXP to EXP (in limbs). 3964 This function is useful for testing functions and algorithms, 3965 since these kind of random numbers have proven to be more likely 3966 to trigger corner-case bugs. Negative random numbers are 3967 generated when MAX_SIZE is negative. 3968 3969 3970 File: gmp.info, Node: Low-level Functions, Next: Random Number Functions, Prev: Floating-point Functions, Up: Top 3971 3972 8 Low-level Functions 3973 ********************* 3974 3975 This chapter describes low-level GMP functions, used to implement the 3976 high-level GMP functions, but also intended for time-critical user code. 3977 3978 These functions start with the prefix `mpn_'. 3979 3980 The `mpn' functions are designed to be as fast as possible, *not* to 3981 provide a coherent calling interface. The different functions have 3982 somewhat similar interfaces, but there are variations that make them 3983 hard to use. These functions do as little as possible apart from the 3984 real multiple precision computation, so that no time is spent on things 3985 that not all callers need. 3986 3987 A source operand is specified by a pointer to the least significant 3988 limb and a limb count. A destination operand is specified by just a 3989 pointer. It is the responsibility of the caller to ensure that the 3990 destination has enough space for storing the result. 3991 3992 With this way of specifying operands, it is possible to perform 3993 computations on subranges of an argument, and store the result into a 3994 subrange of a destination. 3995 3996 A common requirement for all functions is that each source area 3997 needs at least one limb. No size argument may be zero. Unless 3998 otherwise stated, in-place operations are allowed where source and 3999 destination are the same, but not where they only partly overlap. 4000 4001 The `mpn' functions are the base for the implementation of the 4002 `mpz_', `mpf_', and `mpq_' functions. 4003 4004 This example adds the number beginning at S1P and the number 4005 beginning at S2P and writes the sum at DESTP. All areas have N limbs. 4006 4007 cy = mpn_add_n (destp, s1p, s2p, n) 4008 4009 It should be noted that the `mpn' functions make no attempt to 4010 identify high or low zero limbs on their operands, or other special 4011 forms. On random data such cases will be unlikely and it'd be wasteful 4012 for every function to check every time. An application knowing 4013 something about its data can take steps to trim or perhaps split its 4014 calculations. 4015 4016 4017 In the notation used below, a source operand is identified by the 4018 pointer to the least significant limb, and the limb count in braces. 4019 For example, {S1P, S1N}. 4020 4021 -- Function: mp_limb_t mpn_add_n (mp_limb_t *RP, const mp_limb_t *S1P, 4022 const mp_limb_t *S2P, mp_size_t N) 4023 Add {S1P, N} and {S2P, N}, and write the N least significant limbs 4024 of the result to RP. Return carry, either 0 or 1. 4025 4026 This is the lowest-level function for addition. It is the 4027 preferred function for addition, since it is written in assembly 4028 for most CPUs. For addition of a variable to itself (i.e., S1P 4029 equals S2P) use `mpn_lshift' with a count of 1 for optimal speed. 4030 4031 -- Function: mp_limb_t mpn_add_1 (mp_limb_t *RP, const mp_limb_t *S1P, 4032 mp_size_t N, mp_limb_t S2LIMB) 4033 Add {S1P, N} and S2LIMB, and write the N least significant limbs 4034 of the result to RP. Return carry, either 0 or 1. 4035 4036 -- Function: mp_limb_t mpn_add (mp_limb_t *RP, const mp_limb_t *S1P, 4037 mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N) 4038 Add {S1P, S1N} and {S2P, S2N}, and write the S1N least significant 4039 limbs of the result to RP. Return carry, either 0 or 1. 4040 4041 This function requires that S1N is greater than or equal to S2N. 4042 4043 -- Function: mp_limb_t mpn_sub_n (mp_limb_t *RP, const mp_limb_t *S1P, 4044 const mp_limb_t *S2P, mp_size_t N) 4045 Subtract {S2P, N} from {S1P, N}, and write the N least significant 4046 limbs of the result to RP. Return borrow, either 0 or 1. 4047 4048 This is the lowest-level function for subtraction. It is the 4049 preferred function for subtraction, since it is written in 4050 assembly for most CPUs. 4051 4052 -- Function: mp_limb_t mpn_sub_1 (mp_limb_t *RP, const mp_limb_t *S1P, 4053 mp_size_t N, mp_limb_t S2LIMB) 4054 Subtract S2LIMB from {S1P, N}, and write the N least significant 4055 limbs of the result to RP. Return borrow, either 0 or 1. 4056 4057 -- Function: mp_limb_t mpn_sub (mp_limb_t *RP, const mp_limb_t *S1P, 4058 mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N) 4059 Subtract {S2P, S2N} from {S1P, S1N}, and write the S1N least 4060 significant limbs of the result to RP. Return borrow, either 0 or 4061 1. 4062 4063 This function requires that S1N is greater than or equal to S2N. 4064 4065 -- Function: void mpn_neg (mp_limb_t *RP, const mp_limb_t *SP, 4066 mp_size_t N) 4067 Perform the negation of {SP, N}, and write the result to {RP, N}. 4068 Return carry-out. 4069 4070 -- Function: void mpn_mul_n (mp_limb_t *RP, const mp_limb_t *S1P, 4071 const mp_limb_t *S2P, mp_size_t N) 4072 Multiply {S1P, N} and {S2P, N}, and write the 2*N-limb result to 4073 RP. 4074 4075 The destination has to have space for 2*N limbs, even if the 4076 product's most significant limb is zero. No overlap is permitted 4077 between the destination and either source. 4078 4079 If the two input operands are the same, use `mpn_sqr'. 4080 4081 -- Function: mp_limb_t mpn_mul (mp_limb_t *RP, const mp_limb_t *S1P, 4082 mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N) 4083 Multiply {S1P, S1N} and {S2P, S2N}, and write the (S1N+S2N)-limb 4084 result to RP. Return the most significant limb of the result. 4085 4086 The destination has to have space for S1N + S2N limbs, even if the 4087 product's most significant limb is zero. No overlap is permitted 4088 between the destination and either source. 4089 4090 This function requires that S1N is greater than or equal to S2N. 4091 4092 -- Function: void mpn_sqr (mp_limb_t *RP, const mp_limb_t *S1P, 4093 mp_size_t N) 4094 Compute the square of {S1P, N} and write the 2*N-limb result to RP. 4095 4096 The destination has to have space for 2*N limbs, even if the 4097 result's most significant limb is zero. No overlap is permitted 4098 between the destination and the source. 4099 4100 -- Function: mp_limb_t mpn_mul_1 (mp_limb_t *RP, const mp_limb_t *S1P, 4101 mp_size_t N, mp_limb_t S2LIMB) 4102 Multiply {S1P, N} by S2LIMB, and write the N least significant 4103 limbs of the product to RP. Return the most significant limb of 4104 the product. {S1P, N} and {RP, N} are allowed to overlap provided 4105 RP <= S1P. 4106 4107 This is a low-level function that is a building block for general 4108 multiplication as well as other operations in GMP. It is written 4109 in assembly for most CPUs. 4110 4111 Don't call this function if S2LIMB is a power of 2; use 4112 `mpn_lshift' with a count equal to the logarithm of S2LIMB 4113 instead, for optimal speed. 4114 4115 -- Function: mp_limb_t mpn_addmul_1 (mp_limb_t *RP, const mp_limb_t 4116 *S1P, mp_size_t N, mp_limb_t S2LIMB) 4117 Multiply {S1P, N} and S2LIMB, and add the N least significant 4118 limbs of the product to {RP, N} and write the result to RP. 4119 Return the most significant limb of the product, plus carry-out 4120 from the addition. 4121 4122 This is a low-level function that is a building block for general 4123 multiplication as well as other operations in GMP. It is written 4124 in assembly for most CPUs. 4125 4126 -- Function: mp_limb_t mpn_submul_1 (mp_limb_t *RP, const mp_limb_t 4127 *S1P, mp_size_t N, mp_limb_t S2LIMB) 4128 Multiply {S1P, N} and S2LIMB, and subtract the N least significant 4129 limbs of the product from {RP, N} and write the result to RP. 4130 Return the most significant limb of the product, plus borrow-out 4131 from the subtraction. 4132 4133 This is a low-level function that is a building block for general 4134 multiplication and division as well as other operations in GMP. 4135 It is written in assembly for most CPUs. 4136 4137 -- Function: void mpn_tdiv_qr (mp_limb_t *QP, mp_limb_t *RP, mp_size_t 4138 QXN, const mp_limb_t *NP, mp_size_t NN, const mp_limb_t *DP, 4139 mp_size_t DN) 4140 Divide {NP, NN} by {DP, DN} and put the quotient at {QP, NN-DN+1} 4141 and the remainder at {RP, DN}. The quotient is rounded towards 0. 4142 4143 No overlap is permitted between arguments, except that NP might 4144 equal RP. The dividend size NN must be greater than or equal to 4145 divisor size DN. The most significant limb of the divisor must be 4146 non-zero. The QXN operand must be zero. 4147 4148 -- Function: mp_limb_t mpn_divrem (mp_limb_t *R1P, mp_size_t QXN, 4149 mp_limb_t *RS2P, mp_size_t RS2N, const mp_limb_t *S3P, 4150 mp_size_t S3N) 4151 [This function is obsolete. Please call `mpn_tdiv_qr' instead for 4152 best performance.] 4153 4154 Divide {RS2P, RS2N} by {S3P, S3N}, and write the quotient at R1P, 4155 with the exception of the most significant limb, which is 4156 returned. The remainder replaces the dividend at RS2P; it will be 4157 S3N limbs long (i.e., as many limbs as the divisor). 4158 4159 In addition to an integer quotient, QXN fraction limbs are 4160 developed, and stored after the integral limbs. For most usages, 4161 QXN will be zero. 4162 4163 It is required that RS2N is greater than or equal to S3N. It is 4164 required that the most significant bit of the divisor is set. 4165 4166 If the quotient is not needed, pass RS2P + S3N as R1P. Aside from 4167 that special case, no overlap between arguments is permitted. 4168 4169 Return the most significant limb of the quotient, either 0 or 1. 4170 4171 The area at R1P needs to be RS2N - S3N + QXN limbs large. 4172 4173 -- Function: mp_limb_t mpn_divrem_1 (mp_limb_t *R1P, mp_size_t QXN, 4174 mp_limb_t *S2P, mp_size_t S2N, mp_limb_t S3LIMB) 4175 -- Macro: mp_limb_t mpn_divmod_1 (mp_limb_t *R1P, mp_limb_t *S2P, 4176 mp_size_t S2N, mp_limb_t S3LIMB) 4177 Divide {S2P, S2N} by S3LIMB, and write the quotient at R1P. 4178 Return the remainder. 4179 4180 The integer quotient is written to {R1P+QXN, S2N} and in addition 4181 QXN fraction limbs are developed and written to {R1P, QXN}. 4182 Either or both S2N and QXN can be zero. For most usages, QXN will 4183 be zero. 4184 4185 `mpn_divmod_1' exists for upward source compatibility and is 4186 simply a macro calling `mpn_divrem_1' with a QXN of 0. 4187 4188 The areas at R1P and S2P have to be identical or completely 4189 separate, not partially overlapping. 4190 4191 -- Function: mp_limb_t mpn_divmod (mp_limb_t *R1P, mp_limb_t *RS2P, 4192 mp_size_t RS2N, const mp_limb_t *S3P, mp_size_t S3N) 4193 [This function is obsolete. Please call `mpn_tdiv_qr' instead for 4194 best performance.] 4195 4196 -- Macro: mp_limb_t mpn_divexact_by3 (mp_limb_t *RP, mp_limb_t *SP, 4197 mp_size_t N) 4198 -- Function: mp_limb_t mpn_divexact_by3c (mp_limb_t *RP, mp_limb_t 4199 *SP, mp_size_t N, mp_limb_t CARRY) 4200 Divide {SP, N} by 3, expecting it to divide exactly, and writing 4201 the result to {RP, N}. If 3 divides exactly, the return value is 4202 zero and the result is the quotient. If not, the return value is 4203 non-zero and the result won't be anything useful. 4204 4205 `mpn_divexact_by3c' takes an initial carry parameter, which can be 4206 the return value from a previous call, so a large calculation can 4207 be done piece by piece from low to high. `mpn_divexact_by3' is 4208 simply a macro calling `mpn_divexact_by3c' with a 0 carry 4209 parameter. 4210 4211 These routines use a multiply-by-inverse and will be faster than 4212 `mpn_divrem_1' on CPUs with fast multiplication but slow division. 4213 4214 The source a, result q, size n, initial carry i, and return value 4215 c satisfy c*b^n + a-i = 3*q, where b=2^GMP_NUMB_BITS. The return 4216 c is always 0, 1 or 2, and the initial carry i must also be 0, 1 4217 or 2 (these are both borrows really). When c=0 clearly q=(a-i)/3. 4218 When c!=0, the remainder (a-i) mod 3 is given by 3-c, because b == 4219 1 mod 3 (when `mp_bits_per_limb' is even, which is always so 4220 currently). 4221 4222 -- Function: mp_limb_t mpn_mod_1 (const mp_limb_t *S1P, mp_size_t S1N, 4223 mp_limb_t S2LIMB) 4224 Divide {S1P, S1N} by S2LIMB, and return the remainder. S1N can be 4225 zero. 4226 4227 -- Function: mp_limb_t mpn_lshift (mp_limb_t *RP, const mp_limb_t *SP, 4228 mp_size_t N, unsigned int COUNT) 4229 Shift {SP, N} left by COUNT bits, and write the result to {RP, N}. 4230 The bits shifted out at the left are returned in the least 4231 significant COUNT bits of the return value (the rest of the return 4232 value is zero). 4233 4234 COUNT must be in the range 1 to mp_bits_per_limb-1. The regions 4235 {SP, N} and {RP, N} may overlap, provided RP >= SP. 4236 4237 This function is written in assembly for most CPUs. 4238 4239 -- Function: mp_limb_t mpn_rshift (mp_limb_t *RP, const mp_limb_t *SP, 4240 mp_size_t N, unsigned int COUNT) 4241 Shift {SP, N} right by COUNT bits, and write the result to {RP, 4242 N}. The bits shifted out at the right are returned in the most 4243 significant COUNT bits of the return value (the rest of the return 4244 value is zero). 4245 4246 COUNT must be in the range 1 to mp_bits_per_limb-1. The regions 4247 {SP, N} and {RP, N} may overlap, provided RP <= SP. 4248 4249 This function is written in assembly for most CPUs. 4250 4251 -- Function: int mpn_cmp (const mp_limb_t *S1P, const mp_limb_t *S2P, 4252 mp_size_t N) 4253 Compare {S1P, N} and {S2P, N} and return a positive value if S1 > 4254 S2, 0 if they are equal, or a negative value if S1 < S2. 4255 4256 -- Function: mp_size_t mpn_gcd (mp_limb_t *RP, mp_limb_t *XP, 4257 mp_size_t XN, mp_limb_t *YP, mp_size_t YN) 4258 Set {RP, RETVAL} to the greatest common divisor of {XP, XN} and 4259 {YP, YN}. The result can be up to YN limbs, the return value is 4260 the actual number produced. Both source operands are destroyed. 4261 4262 {XP, XN} must have at least as many bits as {YP, YN}. {YP, YN} 4263 must be odd. Both operands must have non-zero most significant 4264 limbs. No overlap is permitted between {XP, XN} and {YP, YN}. 4265 4266 -- Function: mp_limb_t mpn_gcd_1 (const mp_limb_t *XP, mp_size_t XN, 4267 mp_limb_t YLIMB) 4268 Return the greatest common divisor of {XP, XN} and YLIMB. Both 4269 operands must be non-zero. 4270 4271 -- Function: mp_size_t mpn_gcdext (mp_limb_t *GP, mp_limb_t *SP, 4272 mp_size_t *SN, mp_limb_t *UP, mp_size_t UN, mp_limb_t *VP, 4273 mp_size_t VN) 4274 Let U be defined by {UP, UN} and let V be defined by {VP, VN}. 4275 4276 Compute the greatest common divisor G of U and V. Compute a 4277 cofactor S such that G = US + VT. The second cofactor T is not 4278 computed but can easily be obtained from (G - U*S) / V (the 4279 division will be exact). It is required that UN >= VN > 0, and 4280 the most significant limb of {VP, VN} must be non-zero. 4281 4282 S satisfies S = 1 or abs(S) < V / (2 G). S = 0 if and only if V 4283 divides U (i.e., G = V). 4284 4285 Store G at GP and let the return value define its limb count. 4286 Store S at SP and let |*SN| define its limb count. S can be 4287 negative; when this happens *SN will be negative. The area at GP 4288 should have room for VN limbs and the area at SP should have room 4289 for VN+1 limbs. 4290 4291 Both source operands are destroyed. 4292 4293 Compatibility notes: GMP 4.3.0 and 4.3.1 defined S less strictly. 4294 Earlier as well as later GMP releases define S as described here. 4295 GMP releases before GMP 4.3.0 required additional space for both 4296 input and output areas. More precisely, the areas {UP, UN+1} and 4297 {VP, VN+1} were destroyed (i.e. the operands plus an extra limb 4298 past the end of each), and the areas pointed to by GP and SP 4299 should each have room for UN+1 limbs. 4300 4301 -- Function: mp_size_t mpn_sqrtrem (mp_limb_t *R1P, mp_limb_t *R2P, 4302 const mp_limb_t *SP, mp_size_t N) 4303 Compute the square root of {SP, N} and put the result at {R1P, 4304 ceil(N/2)} and the remainder at {R2P, RETVAL}. R2P needs space 4305 for N limbs, but the return value indicates how many are produced. 4306 4307 The most significant limb of {SP, N} must be non-zero. The areas 4308 {R1P, ceil(N/2)} and {SP, N} must be completely separate. The 4309 areas {R2P, N} and {SP, N} must be either identical or completely 4310 separate. 4311 4312 If the remainder is not wanted then R2P can be `NULL', and in this 4313 case the return value is zero or non-zero according to whether the 4314 remainder would have been zero or non-zero. 4315 4316 A return value of zero indicates a perfect square. See also 4317 `mpz_perfect_square_p'. 4318 4319 -- Function: mp_size_t mpn_get_str (unsigned char *STR, int BASE, 4320 mp_limb_t *S1P, mp_size_t S1N) 4321 Convert {S1P, S1N} to a raw unsigned char array at STR in base 4322 BASE, and return the number of characters produced. There may be 4323 leading zeros in the string. The string is not in ASCII; to 4324 convert it to printable format, add the ASCII codes for `0' or 4325 `A', depending on the base and range. BASE can vary from 2 to 256. 4326 4327 The most significant limb of the input {S1P, S1N} must be 4328 non-zero. The input {S1P, S1N} is clobbered, except when BASE is 4329 a power of 2, in which case it's unchanged. 4330 4331 The area at STR has to have space for the largest possible number 4332 represented by a S1N long limb array, plus one extra character. 4333 4334 -- Function: mp_size_t mpn_set_str (mp_limb_t *RP, const unsigned char 4335 *STR, size_t STRSIZE, int BASE) 4336 Convert bytes {STR,STRSIZE} in the given BASE to limbs at RP. 4337 4338 STR[0] is the most significant byte and STR[STRSIZE-1] is the 4339 least significant. Each byte should be a value in the range 0 to 4340 BASE-1, not an ASCII character. BASE can vary from 2 to 256. 4341 4342 The return value is the number of limbs written to RP. If the most 4343 significant input byte is non-zero then the high limb at RP will be 4344 non-zero, and only that exact number of limbs will be required 4345 there. 4346 4347 If the most significant input byte is zero then there may be high 4348 zero limbs written to RP and included in the return value. 4349 4350 STRSIZE must be at least 1, and no overlap is permitted between 4351 {STR,STRSIZE} and the result at RP. 4352 4353 -- Function: mp_bitcnt_t mpn_scan0 (const mp_limb_t *S1P, mp_bitcnt_t 4354 BIT) 4355 Scan S1P from bit position BIT for the next clear bit. 4356 4357 It is required that there be a clear bit within the area at S1P at 4358 or beyond bit position BIT, so that the function has something to 4359 return. 4360 4361 -- Function: mp_bitcnt_t mpn_scan1 (const mp_limb_t *S1P, mp_bitcnt_t 4362 BIT) 4363 Scan S1P from bit position BIT for the next set bit. 4364 4365 It is required that there be a set bit within the area at S1P at or 4366 beyond bit position BIT, so that the function has something to 4367 return. 4368 4369 -- Function: void mpn_random (mp_limb_t *R1P, mp_size_t R1N) 4370 -- Function: void mpn_random2 (mp_limb_t *R1P, mp_size_t R1N) 4371 Generate a random number of length R1N and store it at R1P. The 4372 most significant limb is always non-zero. `mpn_random' generates 4373 uniformly distributed limb data, `mpn_random2' generates long 4374 strings of zeros and ones in the binary representation. 4375 4376 `mpn_random2' is intended for testing the correctness of the `mpn' 4377 routines. 4378 4379 -- Function: mp_bitcnt_t mpn_popcount (const mp_limb_t *S1P, mp_size_t 4380 N) 4381 Count the number of set bits in {S1P, N}. 4382 4383 -- Function: mp_bitcnt_t mpn_hamdist (const mp_limb_t *S1P, const 4384 mp_limb_t *S2P, mp_size_t N) 4385 Compute the hamming distance between {S1P, N} and {S2P, N}, which 4386 is the number of bit positions where the two operands have 4387 different bit values. 4388 4389 -- Function: int mpn_perfect_square_p (const mp_limb_t *S1P, mp_size_t 4390 N) 4391 Return non-zero iff {S1P, N} is a perfect square. The most 4392 significant limb of the input {S1P, N} must be non-zero. 4393 4394 -- Function: void mpn_and_n (mp_limb_t *RP, const mp_limb_t *S1P, 4395 const mp_limb_t *S2P, mp_size_t N) 4396 Perform the bitwise logical and of {S1P, N} and {S2P, N}, and 4397 write the result to {RP, N}. 4398 4399 -- Function: void mpn_ior_n (mp_limb_t *RP, const mp_limb_t *S1P, 4400 const mp_limb_t *S2P, mp_size_t N) 4401 Perform the bitwise logical inclusive or of {S1P, N} and {S2P, N}, 4402 and write the result to {RP, N}. 4403 4404 -- Function: void mpn_xor_n (mp_limb_t *RP, const mp_limb_t *S1P, 4405 const mp_limb_t *S2P, mp_size_t N) 4406 Perform the bitwise logical exclusive or of {S1P, N} and {S2P, N}, 4407 and write the result to {RP, N}. 4408 4409 -- Function: void mpn_andn_n (mp_limb_t *RP, const mp_limb_t *S1P, 4410 const mp_limb_t *S2P, mp_size_t N) 4411 Perform the bitwise logical and of {S1P, N} and the bitwise 4412 complement of {S2P, N}, and write the result to {RP, N}. 4413 4414 -- Function: void mpn_iorn_n (mp_limb_t *RP, const mp_limb_t *S1P, 4415 const mp_limb_t *S2P, mp_size_t N) 4416 Perform the bitwise logical inclusive or of {S1P, N} and the 4417 bitwise complement of {S2P, N}, and write the result to {RP, N}. 4418 4419 -- Function: void mpn_nand_n (mp_limb_t *RP, const mp_limb_t *S1P, 4420 const mp_limb_t *S2P, mp_size_t N) 4421 Perform the bitwise logical and of {S1P, N} and {S2P, N}, and 4422 write the bitwise complement of the result to {RP, N}. 4423 4424 -- Function: void mpn_nior_n (mp_limb_t *RP, const mp_limb_t *S1P, 4425 const mp_limb_t *S2P, mp_size_t N) 4426 Perform the bitwise logical inclusive or of {S1P, N} and {S2P, N}, 4427 and write the bitwise complement of the result to {RP, N}. 4428 4429 -- Function: void mpn_xnor_n (mp_limb_t *RP, const mp_limb_t *S1P, 4430 const mp_limb_t *S2P, mp_size_t N) 4431 Perform the bitwise logical exclusive or of {S1P, N} and {S2P, N}, 4432 and write the bitwise complement of the result to {RP, N}. 4433 4434 -- Function: void mpn_com (mp_limb_t *RP, const mp_limb_t *SP, 4435 mp_size_t N) 4436 Perform the bitwise complement of {SP, N}, and write the result to 4437 {RP, N}. 4438 4439 -- Function: void mpn_copyi (mp_limb_t *RP, const mp_limb_t *S1P, 4440 mp_size_t N) 4441 Copy from {S1P, N} to {RP, N}, increasingly. 4442 4443 -- Function: void mpn_copyd (mp_limb_t *RP, const mp_limb_t *S1P, 4444 mp_size_t N) 4445 Copy from {S1P, N} to {RP, N}, decreasingly. 4446 4447 -- Function: void mpn_zero (mp_limb_t *RP, mp_size_t N) 4448 Zero {RP, N}. 4449 4450 4451 8.1 Nails 4452 ========= 4453 4454 *Everything in this section is highly experimental and may disappear or 4455 be subject to incompatible changes in a future version of GMP.* 4456 4457 Nails are an experimental feature whereby a few bits are left unused 4458 at the top of each `mp_limb_t'. This can significantly improve carry 4459 handling on some processors. 4460 4461 All the `mpn' functions accepting limb data will expect the nail 4462 bits to be zero on entry, and will return data with the nails similarly 4463 all zero. This applies both to limb vectors and to single limb 4464 arguments. 4465 4466 Nails can be enabled by configuring with `--enable-nails'. By 4467 default the number of bits will be chosen according to what suits the 4468 host processor, but a particular number can be selected with 4469 `--enable-nails=N'. 4470 4471 At the mpn level, a nail build is neither source nor binary 4472 compatible with a non-nail build, strictly speaking. But programs 4473 acting on limbs only through the mpn functions are likely to work 4474 equally well with either build, and judicious use of the definitions 4475 below should make any program compatible with either build, at the 4476 source level. 4477 4478 For the higher level routines, meaning `mpz' etc, a nail build 4479 should be fully source and binary compatible with a non-nail build. 4480 4481 -- Macro: GMP_NAIL_BITS 4482 -- Macro: GMP_NUMB_BITS 4483 -- Macro: GMP_LIMB_BITS 4484 `GMP_NAIL_BITS' is the number of nail bits, or 0 when nails are 4485 not in use. `GMP_NUMB_BITS' is the number of data bits in a limb. 4486 `GMP_LIMB_BITS' is the total number of bits in an `mp_limb_t'. In 4487 all cases 4488 4489 GMP_LIMB_BITS == GMP_NAIL_BITS + GMP_NUMB_BITS 4490 4491 -- Macro: GMP_NAIL_MASK 4492 -- Macro: GMP_NUMB_MASK 4493 Bit masks for the nail and number parts of a limb. 4494 `GMP_NAIL_MASK' is 0 when nails are not in use. 4495 4496 `GMP_NAIL_MASK' is not often needed, since the nail part can be 4497 obtained with `x >> GMP_NUMB_BITS', and that means one less large 4498 constant, which can help various RISC chips. 4499 4500 -- Macro: GMP_NUMB_MAX 4501 The maximum value that can be stored in the number part of a limb. 4502 This is the same as `GMP_NUMB_MASK', but can be used for clarity 4503 when doing comparisons rather than bit-wise operations. 4504 4505 The term "nails" comes from finger or toe nails, which are at the 4506 ends of a limb (arm or leg). "numb" is short for number, but is also 4507 how the developers felt after trying for a long time to come up with 4508 sensible names for these things. 4509 4510 In the future (the distant future most likely) a non-zero nail might 4511 be permitted, giving non-unique representations for numbers in a limb 4512 vector. This would help vector processors since carries would only 4513 ever need to propagate one or two limbs. 4514 4515 4516 File: gmp.info, Node: Random Number Functions, Next: Formatted Output, Prev: Low-level Functions, Up: Top 4517 4518 9 Random Number Functions 4519 ************************* 4520 4521 Sequences of pseudo-random numbers in GMP are generated using a 4522 variable of type `gmp_randstate_t', which holds an algorithm selection 4523 and a current state. Such a variable must be initialized by a call to 4524 one of the `gmp_randinit' functions, and can be seeded with one of the 4525 `gmp_randseed' functions. 4526 4527 The functions actually generating random numbers are described in 4528 *note Integer Random Numbers::, and *note Miscellaneous Float 4529 Functions::. 4530 4531 The older style random number functions don't accept a 4532 `gmp_randstate_t' parameter but instead share a global variable of that 4533 type. They use a default algorithm and are currently not seeded 4534 (though perhaps that will change in the future). The new functions 4535 accepting a `gmp_randstate_t' are recommended for applications that 4536 care about randomness. 4537 4538 * Menu: 4539 4540 * Random State Initialization:: 4541 * Random State Seeding:: 4542 * Random State Miscellaneous:: 4543 4544 4545 File: gmp.info, Node: Random State Initialization, Next: Random State Seeding, Prev: Random Number Functions, Up: Random Number Functions 4546 4547 9.1 Random State Initialization 4548 =============================== 4549 4550 -- Function: void gmp_randinit_default (gmp_randstate_t STATE) 4551 Initialize STATE with a default algorithm. This will be a 4552 compromise between speed and randomness, and is recommended for 4553 applications with no special requirements. Currently this is 4554 `gmp_randinit_mt'. 4555 4556 -- Function: void gmp_randinit_mt (gmp_randstate_t STATE) 4557 Initialize STATE for a Mersenne Twister algorithm. This algorithm 4558 is fast and has good randomness properties. 4559 4560 -- Function: void gmp_randinit_lc_2exp (gmp_randstate_t STATE, mpz_t 4561 A, unsigned long C, mp_bitcnt_t M2EXP) 4562 Initialize STATE with a linear congruential algorithm X = (A*X + 4563 C) mod 2^M2EXP. 4564 4565 The low bits of X in this algorithm are not very random. The least 4566 significant bit will have a period no more than 2, and the second 4567 bit no more than 4, etc. For this reason only the high half of 4568 each X is actually used. 4569 4570 When a random number of more than M2EXP/2 bits is to be generated, 4571 multiple iterations of the recurrence are used and the results 4572 concatenated. 4573 4574 -- Function: int gmp_randinit_lc_2exp_size (gmp_randstate_t STATE, 4575 mp_bitcnt_t SIZE) 4576 Initialize STATE for a linear congruential algorithm as per 4577 `gmp_randinit_lc_2exp'. A, C and M2EXP are selected from a table, 4578 chosen so that SIZE bits (or more) of each X will be used, i.e. 4579 M2EXP/2 >= SIZE. 4580 4581 If successful the return value is non-zero. If SIZE is bigger 4582 than the table data provides then the return value is zero. The 4583 maximum SIZE currently supported is 128. 4584 4585 -- Function: void gmp_randinit_set (gmp_randstate_t ROP, 4586 gmp_randstate_t OP) 4587 Initialize ROP with a copy of the algorithm and state from OP. 4588 4589 -- Function: void gmp_randinit (gmp_randstate_t STATE, 4590 gmp_randalg_t ALG, ...) 4591 *This function is obsolete.* 4592 4593 Initialize STATE with an algorithm selected by ALG. The only 4594 choice is `GMP_RAND_ALG_LC', which is `gmp_randinit_lc_2exp_size' 4595 described above. A third parameter of type `unsigned long' is 4596 required, this is the SIZE for that function. 4597 `GMP_RAND_ALG_DEFAULT' or 0 are the same as `GMP_RAND_ALG_LC'. 4598 4599 `gmp_randinit' sets bits in the global variable `gmp_errno' to 4600 indicate an error. `GMP_ERROR_UNSUPPORTED_ARGUMENT' if ALG is 4601 unsupported, or `GMP_ERROR_INVALID_ARGUMENT' if the SIZE parameter 4602 is too big. It may be noted this error reporting is not thread 4603 safe (a good reason to use `gmp_randinit_lc_2exp_size' instead). 4604 4605 -- Function: void gmp_randclear (gmp_randstate_t STATE) 4606 Free all memory occupied by STATE. 4607 4608 4609 File: gmp.info, Node: Random State Seeding, Next: Random State Miscellaneous, Prev: Random State Initialization, Up: Random Number Functions 4610 4611 9.2 Random State Seeding 4612 ======================== 4613 4614 -- Function: void gmp_randseed (gmp_randstate_t STATE, mpz_t SEED) 4615 -- Function: void gmp_randseed_ui (gmp_randstate_t STATE, 4616 unsigned long int SEED) 4617 Set an initial seed value into STATE. 4618 4619 The size of a seed determines how many different sequences of 4620 random numbers that it's possible to generate. The "quality" of 4621 the seed is the randomness of a given seed compared to the 4622 previous seed used, and this affects the randomness of separate 4623 number sequences. The method for choosing a seed is critical if 4624 the generated numbers are to be used for important applications, 4625 such as generating cryptographic keys. 4626 4627 Traditionally the system time has been used to seed, but care 4628 needs to be taken with this. If an application seeds often and 4629 the resolution of the system clock is low, then the same sequence 4630 of numbers might be repeated. Also, the system time is quite easy 4631 to guess, so if unpredictability is required then it should 4632 definitely not be the only source for the seed value. On some 4633 systems there's a special device `/dev/random' which provides 4634 random data better suited for use as a seed. 4635 4636 4637 File: gmp.info, Node: Random State Miscellaneous, Prev: Random State Seeding, Up: Random Number Functions 4638 4639 9.3 Random State Miscellaneous 4640 ============================== 4641 4642 -- Function: unsigned long gmp_urandomb_ui (gmp_randstate_t STATE, 4643 unsigned long N) 4644 Return a uniformly distributed random number of N bits, i.e. in the 4645 range 0 to 2^N-1 inclusive. N must be less than or equal to the 4646 number of bits in an `unsigned long'. 4647 4648 -- Function: unsigned long gmp_urandomm_ui (gmp_randstate_t STATE, 4649 unsigned long N) 4650 Return a uniformly distributed random number in the range 0 to 4651 N-1, inclusive. 4652 4653 4654 File: gmp.info, Node: Formatted Output, Next: Formatted Input, Prev: Random Number Functions, Up: Top 4655 4656 10 Formatted Output 4657 ******************* 4658 4659 * Menu: 4660 4661 * Formatted Output Strings:: 4662 * Formatted Output Functions:: 4663 * C++ Formatted Output:: 4664 4665 4666 File: gmp.info, Node: Formatted Output Strings, Next: Formatted Output Functions, Prev: Formatted Output, Up: Formatted Output 4667 4668 10.1 Format Strings 4669 =================== 4670 4671 `gmp_printf' and friends accept format strings similar to the standard C 4672 `printf' (*note Formatted Output: (libc)Formatted Output.). A format 4673 specification is of the form 4674 4675 % [flags] [width] [.[precision]] [type] conv 4676 4677 GMP adds types `Z', `Q' and `F' for `mpz_t', `mpq_t' and `mpf_t' 4678 respectively, `M' for `mp_limb_t', and `N' for an `mp_limb_t' array. 4679 `Z', `Q', `M' and `N' behave like integers. `Q' will print a `/' and a 4680 denominator, if needed. `F' behaves like a float. For example, 4681 4682 mpz_t z; 4683 gmp_printf ("%s is an mpz %Zd\n", "here", z); 4684 4685 mpq_t q; 4686 gmp_printf ("a hex rational: %#40Qx\n", q); 4687 4688 mpf_t f; 4689 int n; 4690 gmp_printf ("fixed point mpf %.*Ff with %d digits\n", n, f, n); 4691 4692 mp_limb_t l; 4693 gmp_printf ("limb %Mu\n", l); 4694 4695 const mp_limb_t *ptr; 4696 mp_size_t size; 4697 gmp_printf ("limb array %Nx\n", ptr, size); 4698 4699 For `N' the limbs are expected least significant first, as per the 4700 `mpn' functions (*note Low-level Functions::). A negative size can be 4701 given to print the value as a negative. 4702 4703 All the standard C `printf' types behave the same as the C library 4704 `printf', and can be freely intermixed with the GMP extensions. In the 4705 current implementation the standard parts of the format string are 4706 simply handed to `printf' and only the GMP extensions handled directly. 4707 4708 The flags accepted are as follows. GLIBC style ' is only for the 4709 standard C types (not the GMP types), and only if the C library 4710 supports it. 4711 4712 0 pad with zeros (rather than spaces) 4713 # show the base with `0x', `0X' or `0' 4714 + always show a sign 4715 (space) show a space or a `-' sign 4716 ' group digits, GLIBC style (not GMP types) 4717 4718 The optional width and precision can be given as a number within the 4719 format string, or as a `*' to take an extra parameter of type `int', the 4720 same as the standard `printf'. 4721 4722 The standard types accepted are as follows. `h' and `l' are 4723 portable, the rest will depend on the compiler (or include files) for 4724 the type and the C library for the output. 4725 4726 h short 4727 hh char 4728 j intmax_t or uintmax_t 4729 l long or wchar_t 4730 ll long long 4731 L long double 4732 q quad_t or u_quad_t 4733 t ptrdiff_t 4734 z size_t 4735 4736 The GMP types are 4737 4738 F mpf_t, float conversions 4739 Q mpq_t, integer conversions 4740 M mp_limb_t, integer conversions 4741 N mp_limb_t array, integer conversions 4742 Z mpz_t, integer conversions 4743 4744 The conversions accepted are as follows. `a' and `A' are always 4745 supported for `mpf_t' but depend on the C library for standard C float 4746 types. `m' and `p' depend on the C library. 4747 4748 a A hex floats, C99 style 4749 c character 4750 d decimal integer 4751 e E scientific format float 4752 f fixed point float 4753 i same as d 4754 g G fixed or scientific float 4755 m `strerror' string, GLIBC style 4756 n store characters written so far 4757 o octal integer 4758 p pointer 4759 s string 4760 u unsigned integer 4761 x X hex integer 4762 4763 `o', `x' and `X' are unsigned for the standard C types, but for 4764 types `Z', `Q' and `N' they are signed. `u' is not meaningful for `Z', 4765 `Q' and `N'. 4766 4767 `M' is a proxy for the C library `l' or `L', according to the size 4768 of `mp_limb_t'. Unsigned conversions will be usual, but a signed 4769 conversion can be used and will interpret the value as a twos complement 4770 negative. 4771 4772 `n' can be used with any type, even the GMP types. 4773 4774 Other types or conversions that might be accepted by the C library 4775 `printf' cannot be used through `gmp_printf', this includes for 4776 instance extensions registered with GLIBC `register_printf_function'. 4777 Also currently there's no support for POSIX `$' style numbered arguments 4778 (perhaps this will be added in the future). 4779 4780 The precision field has its usual meaning for integer `Z' and float 4781 `F' types, but is currently undefined for `Q' and should not be used 4782 with that. 4783 4784 `mpf_t' conversions only ever generate as many digits as can be 4785 accurately represented by the operand, the same as `mpf_get_str' does. 4786 Zeros will be used if necessary to pad to the requested precision. This 4787 happens even for an `f' conversion of an `mpf_t' which is an integer, 4788 for instance 2^1024 in an `mpf_t' of 128 bits precision will only 4789 produce about 40 digits, then pad with zeros to the decimal point. An 4790 empty precision field like `%.Fe' or `%.Ff' can be used to specifically 4791 request just the significant digits. Without any dot and thus no 4792 precision field, a precision value of 6 will be used. Note that these 4793 rules mean that `%Ff', `%.Ff', and `%.0Ff' will all be different. 4794 4795 The decimal point character (or string) is taken from the current 4796 locale settings on systems which provide `localeconv' (*note Locales 4797 and Internationalization: (libc)Locales.). The C library will normally 4798 do the same for standard float output. 4799 4800 The format string is only interpreted as plain `char's, multibyte 4801 characters are not recognised. Perhaps this will change in the future. 4802 4803 4804 File: gmp.info, Node: Formatted Output Functions, Next: C++ Formatted Output, Prev: Formatted Output Strings, Up: Formatted Output 4805 4806 10.2 Functions 4807 ============== 4808 4809 Each of the following functions is similar to the corresponding C 4810 library function. The basic `printf' forms take a variable argument 4811 list. The `vprintf' forms take an argument pointer, see *note Variadic 4812 Functions: (libc)Variadic Functions, or `man 3 va_start'. 4813 4814 It should be emphasised that if a format string is invalid, or the 4815 arguments don't match what the format specifies, then the behaviour of 4816 any of these functions will be unpredictable. GCC format string 4817 checking is not available, since it doesn't recognise the GMP 4818 extensions. 4819 4820 The file based functions `gmp_printf' and `gmp_fprintf' will return 4821 -1 to indicate a write error. Output is not "atomic", so partial 4822 output may be produced if a write error occurs. All the functions can 4823 return -1 if the C library `printf' variant in use returns -1, but this 4824 shouldn't normally occur. 4825 4826 -- Function: int gmp_printf (const char *FMT, ...) 4827 -- Function: int gmp_vprintf (const char *FMT, va_list AP) 4828 Print to the standard output `stdout'. Return the number of 4829 characters written, or -1 if an error occurred. 4830 4831 -- Function: int gmp_fprintf (FILE *FP, const char *FMT, ...) 4832 -- Function: int gmp_vfprintf (FILE *FP, const char *FMT, va_list AP) 4833 Print to the stream FP. Return the number of characters written, 4834 or -1 if an error occurred. 4835 4836 -- Function: int gmp_sprintf (char *BUF, const char *FMT, ...) 4837 -- Function: int gmp_vsprintf (char *BUF, const char *FMT, va_list AP) 4838 Form a null-terminated string in BUF. Return the number of 4839 characters written, excluding the terminating null. 4840 4841 No overlap is permitted between the space at BUF and the string 4842 FMT. 4843 4844 These functions are not recommended, since there's no protection 4845 against exceeding the space available at BUF. 4846 4847 -- Function: int gmp_snprintf (char *BUF, size_t SIZE, const char 4848 *FMT, ...) 4849 -- Function: int gmp_vsnprintf (char *BUF, size_t SIZE, const char 4850 *FMT, va_list AP) 4851 Form a null-terminated string in BUF. No more than SIZE bytes 4852 will be written. To get the full output, SIZE must be enough for 4853 the string and null-terminator. 4854 4855 The return value is the total number of characters which ought to 4856 have been produced, excluding the terminating null. If RETVAL >= 4857 SIZE then the actual output has been truncated to the first SIZE-1 4858 characters, and a null appended. 4859 4860 No overlap is permitted between the region {BUF,SIZE} and the FMT 4861 string. 4862 4863 Notice the return value is in ISO C99 `snprintf' style. This is 4864 so even if the C library `vsnprintf' is the older GLIBC 2.0.x 4865 style. 4866 4867 -- Function: int gmp_asprintf (char **PP, const char *FMT, ...) 4868 -- Function: int gmp_vasprintf (char **PP, const char *FMT, va_list AP) 4869 Form a null-terminated string in a block of memory obtained from 4870 the current memory allocation function (*note Custom 4871 Allocation::). The block will be the size of the string and 4872 null-terminator. The address of the block in stored to *PP. The 4873 return value is the number of characters produced, excluding the 4874 null-terminator. 4875 4876 Unlike the C library `asprintf', `gmp_asprintf' doesn't return -1 4877 if there's no more memory available, it lets the current allocation 4878 function handle that. 4879 4880 -- Function: int gmp_obstack_printf (struct obstack *OB, const char 4881 *FMT, ...) 4882 -- Function: int gmp_obstack_vprintf (struct obstack *OB, const char 4883 *FMT, va_list AP) 4884 Append to the current object in OB. The return value is the 4885 number of characters written. A null-terminator is not written. 4886 4887 FMT cannot be within the current object in OB, since that object 4888 might move as it grows. 4889 4890 These functions are available only when the C library provides the 4891 obstack feature, which probably means only on GNU systems, see 4892 *note Obstacks: (libc)Obstacks. 4893 4894 4895 File: gmp.info, Node: C++ Formatted Output, Prev: Formatted Output Functions, Up: Formatted Output 4896 4897 10.3 C++ Formatted Output 4898 ========================= 4899 4900 The following functions are provided in `libgmpxx' (*note Headers and 4901 Libraries::), which is built if C++ support is enabled (*note Build 4902 Options::). Prototypes are available from `<gmp.h>'. 4903 4904 -- Function: ostream& operator<< (ostream& STREAM, mpz_t OP) 4905 Print OP to STREAM, using its `ios' formatting settings. 4906 `ios::width' is reset to 0 after output, the same as the standard 4907 `ostream operator<<' routines do. 4908 4909 In hex or octal, OP is printed as a signed number, the same as for 4910 decimal. This is unlike the standard `operator<<' routines on 4911 `int' etc, which instead give twos complement. 4912 4913 -- Function: ostream& operator<< (ostream& STREAM, mpq_t OP) 4914 Print OP to STREAM, using its `ios' formatting settings. 4915 `ios::width' is reset to 0 after output, the same as the standard 4916 `ostream operator<<' routines do. 4917 4918 Output will be a fraction like `5/9', or if the denominator is 1 4919 then just a plain integer like `123'. 4920 4921 In hex or octal, OP is printed as a signed value, the same as for 4922 decimal. If `ios::showbase' is set then a base indicator is shown 4923 on both the numerator and denominator (if the denominator is 4924 required). 4925 4926 -- Function: ostream& operator<< (ostream& STREAM, mpf_t OP) 4927 Print OP to STREAM, using its `ios' formatting settings. 4928 `ios::width' is reset to 0 after output, the same as the standard 4929 `ostream operator<<' routines do. 4930 4931 The decimal point follows the standard library float `operator<<', 4932 which on recent systems means the `std::locale' imbued on STREAM. 4933 4934 Hex and octal are supported, unlike the standard `operator<<' on 4935 `double'. The mantissa will be in hex or octal, the exponent will 4936 be in decimal. For hex the exponent delimiter is an `@'. This is 4937 as per `mpf_out_str'. 4938 4939 `ios::showbase' is supported, and will put a base on the mantissa, 4940 for example hex `0x1.8' or `0x0.8', or octal `01.4' or `00.4'. 4941 This last form is slightly strange, but at least differentiates 4942 itself from decimal. 4943 4944 These operators mean that GMP types can be printed in the usual C++ 4945 way, for example, 4946 4947 mpz_t z; 4948 int n; 4949 ... 4950 cout << "iteration " << n << " value " << z << "\n"; 4951 4952 But note that `ostream' output (and `istream' input, *note C++ 4953 Formatted Input::) is the only overloading available for the GMP types 4954 and that for instance using `+' with an `mpz_t' will have unpredictable 4955 results. For classes with overloading, see *note C++ Class Interface::. 4956 4957 4958 File: gmp.info, Node: Formatted Input, Next: C++ Class Interface, Prev: Formatted Output, Up: Top 4959 4960 11 Formatted Input 4961 ****************** 4962 4963 * Menu: 4964 4965 * Formatted Input Strings:: 4966 * Formatted Input Functions:: 4967 * C++ Formatted Input:: 4968 4969 4970 File: gmp.info, Node: Formatted Input Strings, Next: Formatted Input Functions, Prev: Formatted Input, Up: Formatted Input 4971 4972 11.1 Formatted Input Strings 4973 ============================ 4974 4975 `gmp_scanf' and friends accept format strings similar to the standard C 4976 `scanf' (*note Formatted Input: (libc)Formatted Input.). A format 4977 specification is of the form 4978 4979 % [flags] [width] [type] conv 4980 4981 GMP adds types `Z', `Q' and `F' for `mpz_t', `mpq_t' and `mpf_t' 4982 respectively. `Z' and `Q' behave like integers. `Q' will read a `/' 4983 and a denominator, if present. `F' behaves like a float. 4984 4985 GMP variables don't require an `&' when passed to `gmp_scanf', since 4986 they're already "call-by-reference". For example, 4987 4988 /* to read say "a(5) = 1234" */ 4989 int n; 4990 mpz_t z; 4991 gmp_scanf ("a(%d) = %Zd\n", &n, z); 4992 4993 mpq_t q1, q2; 4994 gmp_sscanf ("0377 + 0x10/0x11", "%Qi + %Qi", q1, q2); 4995 4996 /* to read say "topleft (1.55,-2.66)" */ 4997 mpf_t x, y; 4998 char buf[32]; 4999 gmp_scanf ("%31s (%Ff,%Ff)", buf, x, y); 5000 5001 All the standard C `scanf' types behave the same as in the C library 5002 `scanf', and can be freely intermixed with the GMP extensions. In the 5003 current implementation the standard parts of the format string are 5004 simply handed to `scanf' and only the GMP extensions handled directly. 5005 5006 The flags accepted are as follows. `a' and `'' will depend on 5007 support from the C library, and `'' cannot be used with GMP types. 5008 5009 * read but don't store 5010 a allocate a buffer (string conversions) 5011 ' grouped digits, GLIBC style (not GMP 5012 types) 5013 5014 The standard types accepted are as follows. `h' and `l' are 5015 portable, the rest will depend on the compiler (or include files) for 5016 the type and the C library for the input. 5017 5018 h short 5019 hh char 5020 j intmax_t or uintmax_t 5021 l long int, double or wchar_t 5022 ll long long 5023 L long double 5024 q quad_t or u_quad_t 5025 t ptrdiff_t 5026 z size_t 5027 5028 The GMP types are 5029 5030 F mpf_t, float conversions 5031 Q mpq_t, integer conversions 5032 Z mpz_t, integer conversions 5033 5034 The conversions accepted are as follows. `p' and `[' will depend on 5035 support from the C library, the rest are standard. 5036 5037 c character or characters 5038 d decimal integer 5039 e E f g G float 5040 i integer with base indicator 5041 n characters read so far 5042 o octal integer 5043 p pointer 5044 s string of non-whitespace characters 5045 u decimal integer 5046 x X hex integer 5047 [ string of characters in a set 5048 5049 `e', `E', `f', `g' and `G' are identical, they all read either fixed 5050 point or scientific format, and either upper or lower case `e' for the 5051 exponent in scientific format. 5052 5053 C99 style hex float format (`printf %a', *note Formatted Output 5054 Strings::) is always accepted for `mpf_t', but for the standard float 5055 types it will depend on the C library. 5056 5057 `x' and `X' are identical, both accept both upper and lower case 5058 hexadecimal. 5059 5060 `o', `u', `x' and `X' all read positive or negative values. For the 5061 standard C types these are described as "unsigned" conversions, but 5062 that merely affects certain overflow handling, negatives are still 5063 allowed (per `strtoul', *note Parsing of Integers: (libc)Parsing of 5064 Integers.). For GMP types there are no overflows, so `d' and `u' are 5065 identical. 5066 5067 `Q' type reads the numerator and (optional) denominator as given. 5068 If the value might not be in canonical form then `mpq_canonicalize' 5069 must be called before using it in any calculations (*note Rational 5070 Number Functions::). 5071 5072 `Qi' will read a base specification separately for the numerator and 5073 denominator. For example `0x10/11' would be 16/11, whereas `0x10/0x11' 5074 would be 16/17. 5075 5076 `n' can be used with any of the types above, even the GMP types. 5077 `*' to suppress assignment is allowed, though in that case it would do 5078 nothing at all. 5079 5080 Other conversions or types that might be accepted by the C library 5081 `scanf' cannot be used through `gmp_scanf'. 5082 5083 Whitespace is read and discarded before a field, except for `c' and 5084 `[' conversions. 5085 5086 For float conversions, the decimal point character (or string) 5087 expected is taken from the current locale settings on systems which 5088 provide `localeconv' (*note Locales and Internationalization: 5089 (libc)Locales.). The C library will normally do the same for standard 5090 float input. 5091 5092 The format string is only interpreted as plain `char's, multibyte 5093 characters are not recognised. Perhaps this will change in the future. 5094 5095 5096 File: gmp.info, Node: Formatted Input Functions, Next: C++ Formatted Input, Prev: Formatted Input Strings, Up: Formatted Input 5097 5098 11.2 Formatted Input Functions 5099 ============================== 5100 5101 Each of the following functions is similar to the corresponding C 5102 library function. The plain `scanf' forms take a variable argument 5103 list. The `vscanf' forms take an argument pointer, see *note Variadic 5104 Functions: (libc)Variadic Functions, or `man 3 va_start'. 5105 5106 It should be emphasised that if a format string is invalid, or the 5107 arguments don't match what the format specifies, then the behaviour of 5108 any of these functions will be unpredictable. GCC format string 5109 checking is not available, since it doesn't recognise the GMP 5110 extensions. 5111 5112 No overlap is permitted between the FMT string and any of the results 5113 produced. 5114 5115 -- Function: int gmp_scanf (const char *FMT, ...) 5116 -- Function: int gmp_vscanf (const char *FMT, va_list AP) 5117 Read from the standard input `stdin'. 5118 5119 -- Function: int gmp_fscanf (FILE *FP, const char *FMT, ...) 5120 -- Function: int gmp_vfscanf (FILE *FP, const char *FMT, va_list AP) 5121 Read from the stream FP. 5122 5123 -- Function: int gmp_sscanf (const char *S, const char *FMT, ...) 5124 -- Function: int gmp_vsscanf (const char *S, const char *FMT, va_list 5125 AP) 5126 Read from a null-terminated string S. 5127 5128 The return value from each of these functions is the same as the 5129 standard C99 `scanf', namely the number of fields successfully parsed 5130 and stored. `%n' fields and fields read but suppressed by `*' don't 5131 count towards the return value. 5132 5133 If end of input (or a file error) is reached before a character for 5134 a field or a literal, and if no previous non-suppressed fields have 5135 matched, then the return value is `EOF' instead of 0. A whitespace 5136 character in the format string is only an optional match and doesn't 5137 induce an `EOF' in this fashion. Leading whitespace read and discarded 5138 for a field don't count as characters for that field. 5139 5140 For the GMP types, input parsing follows C99 rules, namely one 5141 character of lookahead is used and characters are read while they 5142 continue to meet the format requirements. If this doesn't provide a 5143 complete number then the function terminates, with that field not 5144 stored nor counted towards the return value. For instance with `mpf_t' 5145 an input `1.23e-XYZ' would be read up to the `X' and that character 5146 pushed back since it's not a digit. The string `1.23e-' would then be 5147 considered invalid since an `e' must be followed by at least one digit. 5148 5149 For the standard C types, in the current implementation GMP calls 5150 the C library `scanf' functions, which might have looser rules about 5151 what constitutes a valid input. 5152 5153 Note that `gmp_sscanf' is the same as `gmp_fscanf' and only does one 5154 character of lookahead when parsing. Although clearly it could look at 5155 its entire input, it is deliberately made identical to `gmp_fscanf', 5156 the same way C99 `sscanf' is the same as `fscanf'. 5157 5158 5159 File: gmp.info, Node: C++ Formatted Input, Prev: Formatted Input Functions, Up: Formatted Input 5160 5161 11.3 C++ Formatted Input 5162 ======================== 5163 5164 The following functions are provided in `libgmpxx' (*note Headers and 5165 Libraries::), which is built only if C++ support is enabled (*note 5166 Build Options::). Prototypes are available from `<gmp.h>'. 5167 5168 -- Function: istream& operator>> (istream& STREAM, mpz_t ROP) 5169 Read ROP from STREAM, using its `ios' formatting settings. 5170 5171 -- Function: istream& operator>> (istream& STREAM, mpq_t ROP) 5172 An integer like `123' will be read, or a fraction like `5/9'. No 5173 whitespace is allowed around the `/'. If the fraction is not in 5174 canonical form then `mpq_canonicalize' must be called (*note 5175 Rational Number Functions::) before operating on it. 5176 5177 As per integer input, an `0' or `0x' base indicator is read when 5178 none of `ios::dec', `ios::oct' or `ios::hex' are set. This is 5179 done separately for numerator and denominator, so that for instance 5180 `0x10/11' is 16/11 and `0x10/0x11' is 16/17. 5181 5182 -- Function: istream& operator>> (istream& STREAM, mpf_t ROP) 5183 Read ROP from STREAM, using its `ios' formatting settings. 5184 5185 Hex or octal floats are not supported, but might be in the future, 5186 or perhaps it's best to accept only what the standard float 5187 `operator>>' does. 5188 5189 Note that digit grouping specified by the `istream' locale is 5190 currently not accepted. Perhaps this will change in the future. 5191 5192 5193 These operators mean that GMP types can be read in the usual C++ 5194 way, for example, 5195 5196 mpz_t z; 5197 ... 5198 cin >> z; 5199 5200 But note that `istream' input (and `ostream' output, *note C++ 5201 Formatted Output::) is the only overloading available for the GMP types 5202 and that for instance using `+' with an `mpz_t' will have unpredictable 5203 results. For classes with overloading, see *note C++ Class Interface::. 5204 5205 5206 File: gmp.info, Node: C++ Class Interface, Next: BSD Compatible Functions, Prev: Formatted Input, Up: Top 5207 5208 12 C++ Class Interface 5209 ********************** 5210 5211 This chapter describes the C++ class based interface to GMP. 5212 5213 All GMP C language types and functions can be used in C++ programs, 5214 since `gmp.h' has `extern "C"' qualifiers, but the class interface 5215 offers overloaded functions and operators which may be more convenient. 5216 5217 Due to the implementation of this interface, a reasonably recent C++ 5218 compiler is required, one supporting namespaces, partial specialization 5219 of templates and member templates. For GCC this means version 2.91 or 5220 later. 5221 5222 *Everything described in this chapter is to be considered preliminary 5223 and might be subject to incompatible changes if some unforeseen 5224 difficulty reveals itself.* 5225 5226 * Menu: 5227 5228 * C++ Interface General:: 5229 * C++ Interface Integers:: 5230 * C++ Interface Rationals:: 5231 * C++ Interface Floats:: 5232 * C++ Interface Random Numbers:: 5233 * C++ Interface Limitations:: 5234 5235 5236 File: gmp.info, Node: C++ Interface General, Next: C++ Interface Integers, Prev: C++ Class Interface, Up: C++ Class Interface 5237 5238 12.1 C++ Interface General 5239 ========================== 5240 5241 All the C++ classes and functions are available with 5242 5243 #include <gmpxx.h> 5244 5245 Programs should be linked with the `libgmpxx' and `libgmp' 5246 libraries. For example, 5247 5248 g++ mycxxprog.cc -lgmpxx -lgmp 5249 5250 The classes defined are 5251 5252 -- Class: mpz_class 5253 -- Class: mpq_class 5254 -- Class: mpf_class 5255 5256 The standard operators and various standard functions are overloaded 5257 to allow arithmetic with these classes. For example, 5258 5259 int 5260 main (void) 5261 { 5262 mpz_class a, b, c; 5263 5264 a = 1234; 5265 b = "-5678"; 5266 c = a+b; 5267 cout << "sum is " << c << "\n"; 5268 cout << "absolute value is " << abs(c) << "\n"; 5269 5270 return 0; 5271 } 5272 5273 An important feature of the implementation is that an expression like 5274 `a=b+c' results in a single call to the corresponding `mpz_add', 5275 without using a temporary for the `b+c' part. Expressions which by 5276 their nature imply intermediate values, like `a=b*c+d*e', still use 5277 temporaries though. 5278 5279 The classes can be freely intermixed in expressions, as can the 5280 classes and the standard types `long', `unsigned long' and `double'. 5281 Smaller types like `int' or `float' can also be intermixed, since C++ 5282 will promote them. 5283 5284 Note that `bool' is not accepted directly, but must be explicitly 5285 cast to an `int' first. This is because C++ will automatically convert 5286 any pointer to a `bool', so if GMP accepted `bool' it would make all 5287 sorts of invalid class and pointer combinations compile but almost 5288 certainly not do anything sensible. 5289 5290 Conversions back from the classes to standard C++ types aren't done 5291 automatically, instead member functions like `get_si' are provided (see 5292 the following sections for details). 5293 5294 Also there are no automatic conversions from the classes to the 5295 corresponding GMP C types, instead a reference to the underlying C 5296 object can be obtained with the following functions, 5297 5298 -- Function: mpz_t mpz_class::get_mpz_t () 5299 -- Function: mpq_t mpq_class::get_mpq_t () 5300 -- Function: mpf_t mpf_class::get_mpf_t () 5301 5302 These can be used to call a C function which doesn't have a C++ class 5303 interface. For example to set `a' to the GCD of `b' and `c', 5304 5305 mpz_class a, b, c; 5306 ... 5307 mpz_gcd (a.get_mpz_t(), b.get_mpz_t(), c.get_mpz_t()); 5308 5309 In the other direction, a class can be initialized from the 5310 corresponding GMP C type, or assigned to if an explicit constructor is 5311 used. In both cases this makes a copy of the value, it doesn't create 5312 any sort of association. For example, 5313 5314 mpz_t z; 5315 // ... init and calculate z ... 5316 mpz_class x(z); 5317 mpz_class y; 5318 y = mpz_class (z); 5319 5320 There are no namespace setups in `gmpxx.h', all types and functions 5321 are simply put into the global namespace. This is what `gmp.h' has 5322 done in the past, and continues to do for compatibility. The extras 5323 provided by `gmpxx.h' follow GMP naming conventions and are unlikely to 5324 clash with anything. 5325 5326 5327 File: gmp.info, Node: C++ Interface Integers, Next: C++ Interface Rationals, Prev: C++ Interface General, Up: C++ Class Interface 5328 5329 12.2 C++ Interface Integers 5330 =========================== 5331 5332 -- Function: mpz_class::mpz_class (type N) 5333 Construct an `mpz_class'. All the standard C++ types may be used, 5334 except `long long' and `long double', and all the GMP C++ classes 5335 can be used. Any necessary conversion follows the corresponding C 5336 function, for example `double' follows `mpz_set_d' (*note 5337 Assigning Integers::). 5338 5339 -- Function: explicit mpz_class::mpz_class (mpz_t Z) 5340 Construct an `mpz_class' from an `mpz_t'. The value in Z is 5341 copied into the new `mpz_class', there won't be any permanent 5342 association between it and Z. 5343 5344 -- Function: explicit mpz_class::mpz_class (const char *S, int BASE = 5345 0) 5346 -- Function: explicit mpz_class::mpz_class (const string& S, int BASE 5347 = 0) 5348 Construct an `mpz_class' converted from a string using 5349 `mpz_set_str' (*note Assigning Integers::). 5350 5351 If the string is not a valid integer, an `std::invalid_argument' 5352 exception is thrown. The same applies to `operator='. 5353 5354 -- Function: mpz_class operator/ (mpz_class A, mpz_class D) 5355 -- Function: mpz_class operator% (mpz_class A, mpz_class D) 5356 Divisions involving `mpz_class' round towards zero, as per the 5357 `mpz_tdiv_q' and `mpz_tdiv_r' functions (*note Integer Division::). 5358 This is the same as the C99 `/' and `%' operators. 5359 5360 The `mpz_fdiv...' or `mpz_cdiv...' functions can always be called 5361 directly if desired. For example, 5362 5363 mpz_class q, a, d; 5364 ... 5365 mpz_fdiv_q (q.get_mpz_t(), a.get_mpz_t(), d.get_mpz_t()); 5366 5367 -- Function: mpz_class abs (mpz_class OP1) 5368 -- Function: int cmp (mpz_class OP1, type OP2) 5369 -- Function: int cmp (type OP1, mpz_class OP2) 5370 -- Function: bool mpz_class::fits_sint_p (void) 5371 -- Function: bool mpz_class::fits_slong_p (void) 5372 -- Function: bool mpz_class::fits_sshort_p (void) 5373 -- Function: bool mpz_class::fits_uint_p (void) 5374 -- Function: bool mpz_class::fits_ulong_p (void) 5375 -- Function: bool mpz_class::fits_ushort_p (void) 5376 -- Function: double mpz_class::get_d (void) 5377 -- Function: long mpz_class::get_si (void) 5378 -- Function: string mpz_class::get_str (int BASE = 10) 5379 -- Function: unsigned long mpz_class::get_ui (void) 5380 -- Function: int mpz_class::set_str (const char *STR, int BASE) 5381 -- Function: int mpz_class::set_str (const string& STR, int BASE) 5382 -- Function: int sgn (mpz_class OP) 5383 -- Function: mpz_class sqrt (mpz_class OP) 5384 These functions provide a C++ class interface to the corresponding 5385 GMP C routines. 5386 5387 `cmp' can be used with any of the classes or the standard C++ 5388 types, except `long long' and `long double'. 5389 5390 5391 Overloaded operators for combinations of `mpz_class' and `double' 5392 are provided for completeness, but it should be noted that if the given 5393 `double' is not an integer then the way any rounding is done is 5394 currently unspecified. The rounding might take place at the start, in 5395 the middle, or at the end of the operation, and it might change in the 5396 future. 5397 5398 Conversions between `mpz_class' and `double', however, are defined 5399 to follow the corresponding C functions `mpz_get_d' and `mpz_set_d'. 5400 And comparisons are always made exactly, as per `mpz_cmp_d'. 5401 5402 5403 File: gmp.info, Node: C++ Interface Rationals, Next: C++ Interface Floats, Prev: C++ Interface Integers, Up: C++ Class Interface 5404 5405 12.3 C++ Interface Rationals 5406 ============================ 5407 5408 In all the following constructors, if a fraction is given then it 5409 should be in canonical form, or if not then `mpq_class::canonicalize' 5410 called. 5411 5412 -- Function: mpq_class::mpq_class (type OP) 5413 -- Function: mpq_class::mpq_class (integer NUM, integer DEN) 5414 Construct an `mpq_class'. The initial value can be a single value 5415 of any type, or a pair of integers (`mpz_class' or standard C++ 5416 integer types) representing a fraction, except that `long long' 5417 and `long double' are not supported. For example, 5418 5419 mpq_class q (99); 5420 mpq_class q (1.75); 5421 mpq_class q (1, 3); 5422 5423 -- Function: explicit mpq_class::mpq_class (mpq_t Q) 5424 Construct an `mpq_class' from an `mpq_t'. The value in Q is 5425 copied into the new `mpq_class', there won't be any permanent 5426 association between it and Q. 5427 5428 -- Function: explicit mpq_class::mpq_class (const char *S, int BASE = 5429 0) 5430 -- Function: explicit mpq_class::mpq_class (const string& S, int BASE 5431 = 0) 5432 Construct an `mpq_class' converted from a string using 5433 `mpq_set_str' (*note Initializing Rationals::). 5434 5435 If the string is not a valid rational, an `std::invalid_argument' 5436 exception is thrown. The same applies to `operator='. 5437 5438 -- Function: void mpq_class::canonicalize () 5439 Put an `mpq_class' into canonical form, as per *note Rational 5440 Number Functions::. All arithmetic operators require their 5441 operands in canonical form, and will return results in canonical 5442 form. 5443 5444 -- Function: mpq_class abs (mpq_class OP) 5445 -- Function: int cmp (mpq_class OP1, type OP2) 5446 -- Function: int cmp (type OP1, mpq_class OP2) 5447 -- Function: double mpq_class::get_d (void) 5448 -- Function: string mpq_class::get_str (int BASE = 10) 5449 -- Function: int mpq_class::set_str (const char *STR, int BASE) 5450 -- Function: int mpq_class::set_str (const string& STR, int BASE) 5451 -- Function: int sgn (mpq_class OP) 5452 These functions provide a C++ class interface to the corresponding 5453 GMP C routines. 5454 5455 `cmp' can be used with any of the classes or the standard C++ 5456 types, except `long long' and `long double'. 5457 5458 -- Function: mpz_class& mpq_class::get_num () 5459 -- Function: mpz_class& mpq_class::get_den () 5460 Get a reference to an `mpz_class' which is the numerator or 5461 denominator of an `mpq_class'. This can be used both for read and 5462 write access. If the object returned is modified, it modifies the 5463 original `mpq_class'. 5464 5465 If direct manipulation might produce a non-canonical value, then 5466 `mpq_class::canonicalize' must be called before further operations. 5467 5468 -- Function: mpz_t mpq_class::get_num_mpz_t () 5469 -- Function: mpz_t mpq_class::get_den_mpz_t () 5470 Get a reference to the underlying `mpz_t' numerator or denominator 5471 of an `mpq_class'. This can be passed to C functions expecting an 5472 `mpz_t'. Any modifications made to the `mpz_t' will modify the 5473 original `mpq_class'. 5474 5475 If direct manipulation might produce a non-canonical value, then 5476 `mpq_class::canonicalize' must be called before further operations. 5477 5478 -- Function: istream& operator>> (istream& STREAM, mpq_class& ROP); 5479 Read ROP from STREAM, using its `ios' formatting settings, the 5480 same as `mpq_t operator>>' (*note C++ Formatted Input::). 5481 5482 If the ROP read might not be in canonical form then 5483 `mpq_class::canonicalize' must be called. 5484 5485 5486 File: gmp.info, Node: C++ Interface Floats, Next: C++ Interface Random Numbers, Prev: C++ Interface Rationals, Up: C++ Class Interface 5487 5488 12.4 C++ Interface Floats 5489 ========================= 5490 5491 When an expression requires the use of temporary intermediate 5492 `mpf_class' values, like `f=g*h+x*y', those temporaries will have the 5493 same precision as the destination `f'. Explicit constructors can be 5494 used if this doesn't suit. 5495 5496 -- Function: mpf_class::mpf_class (type OP) 5497 -- Function: mpf_class::mpf_class (type OP, mp_bitcnt_t PREC) 5498 Construct an `mpf_class'. Any standard C++ type can be used, 5499 except `long long' and `long double', and any of the GMP C++ 5500 classes can be used. 5501 5502 If PREC is given, the initial precision is that value, in bits. If 5503 PREC is not given, then the initial precision is determined by the 5504 type of OP given. An `mpz_class', `mpq_class', or C++ builtin 5505 type will give the default `mpf' precision (*note Initializing 5506 Floats::). An `mpf_class' or expression will give the precision 5507 of that value. The precision of a binary expression is the higher 5508 of the two operands. 5509 5510 mpf_class f(1.5); // default precision 5511 mpf_class f(1.5, 500); // 500 bits (at least) 5512 mpf_class f(x); // precision of x 5513 mpf_class f(abs(x)); // precision of x 5514 mpf_class f(-g, 1000); // 1000 bits (at least) 5515 mpf_class f(x+y); // greater of precisions of x and y 5516 5517 -- Function: explicit mpf_class::mpf_class (mpf_t F) 5518 -- Function: mpf_class::mpf_class (mpf_t F, mp_bitcnt_t PREC) 5519 Construct an `mpf_class' from an `mpf_t'. The value in F is 5520 copied into the new `mpf_class', there won't be any permanent 5521 association between it and F. 5522 5523 If PREC is given, the initial precision is that value, in bits. If 5524 PREC is not given, then the initial precision is that of F. 5525 5526 -- Function: explicit mpf_class::mpf_class (const char *S) 5527 -- Function: mpf_class::mpf_class (const char *S, mp_bitcnt_t PREC, 5528 int BASE = 0) 5529 -- Function: explicit mpf_class::mpf_class (const string& S) 5530 -- Function: mpf_class::mpf_class (const string& S, mp_bitcnt_t PREC, 5531 int BASE = 0) 5532 Construct an `mpf_class' converted from a string using 5533 `mpf_set_str' (*note Assigning Floats::). If PREC is given, the 5534 initial precision is that value, in bits. If not, the default 5535 `mpf' precision (*note Initializing Floats::) is used. 5536 5537 If the string is not a valid float, an `std::invalid_argument' 5538 exception is thrown. The same applies to `operator='. 5539 5540 -- Function: mpf_class& mpf_class::operator= (type OP) 5541 Convert and store the given OP value to an `mpf_class' object. The 5542 same types are accepted as for the constructors above. 5543 5544 Note that `operator=' only stores a new value, it doesn't copy or 5545 change the precision of the destination, instead the value is 5546 truncated if necessary. This is the same as `mpf_set' etc. Note 5547 in particular this means for `mpf_class' a copy constructor is not 5548 the same as a default constructor plus assignment. 5549 5550 mpf_class x (y); // x created with precision of y 5551 5552 mpf_class x; // x created with default precision 5553 x = y; // value truncated to that precision 5554 5555 Applications using templated code may need to be careful about the 5556 assumptions the code makes in this area, when working with 5557 `mpf_class' values of various different or non-default precisions. 5558 For instance implementations of the standard `complex' template 5559 have been seen in both styles above, though of course `complex' is 5560 normally only actually specified for use with the builtin float 5561 types. 5562 5563 -- Function: mpf_class abs (mpf_class OP) 5564 -- Function: mpf_class ceil (mpf_class OP) 5565 -- Function: int cmp (mpf_class OP1, type OP2) 5566 -- Function: int cmp (type OP1, mpf_class OP2) 5567 -- Function: bool mpf_class::fits_sint_p (void) 5568 -- Function: bool mpf_class::fits_slong_p (void) 5569 -- Function: bool mpf_class::fits_sshort_p (void) 5570 -- Function: bool mpf_class::fits_uint_p (void) 5571 -- Function: bool mpf_class::fits_ulong_p (void) 5572 -- Function: bool mpf_class::fits_ushort_p (void) 5573 -- Function: mpf_class floor (mpf_class OP) 5574 -- Function: mpf_class hypot (mpf_class OP1, mpf_class OP2) 5575 -- Function: double mpf_class::get_d (void) 5576 -- Function: long mpf_class::get_si (void) 5577 -- Function: string mpf_class::get_str (mp_exp_t& EXP, int BASE = 10, 5578 size_t DIGITS = 0) 5579 -- Function: unsigned long mpf_class::get_ui (void) 5580 -- Function: int mpf_class::set_str (const char *STR, int BASE) 5581 -- Function: int mpf_class::set_str (const string& STR, int BASE) 5582 -- Function: int sgn (mpf_class OP) 5583 -- Function: mpf_class sqrt (mpf_class OP) 5584 -- Function: mpf_class trunc (mpf_class OP) 5585 These functions provide a C++ class interface to the corresponding 5586 GMP C routines. 5587 5588 `cmp' can be used with any of the classes or the standard C++ 5589 types, except `long long' and `long double'. 5590 5591 The accuracy provided by `hypot' is not currently guaranteed. 5592 5593 -- Function: mp_bitcnt_t mpf_class::get_prec () 5594 -- Function: void mpf_class::set_prec (mp_bitcnt_t PREC) 5595 -- Function: void mpf_class::set_prec_raw (mp_bitcnt_t PREC) 5596 Get or set the current precision of an `mpf_class'. 5597 5598 The restrictions described for `mpf_set_prec_raw' (*note 5599 Initializing Floats::) apply to `mpf_class::set_prec_raw'. Note 5600 in particular that the `mpf_class' must be restored to it's 5601 allocated precision before being destroyed. This must be done by 5602 application code, there's no automatic mechanism for it. 5603 5604 5605 File: gmp.info, Node: C++ Interface Random Numbers, Next: C++ Interface Limitations, Prev: C++ Interface Floats, Up: C++ Class Interface 5606 5607 12.5 C++ Interface Random Numbers 5608 ================================= 5609 5610 -- Class: gmp_randclass 5611 The C++ class interface to the GMP random number functions uses 5612 `gmp_randclass' to hold an algorithm selection and current state, 5613 as per `gmp_randstate_t'. 5614 5615 -- Function: gmp_randclass::gmp_randclass (void (*RANDINIT) 5616 (gmp_randstate_t, ...), ...) 5617 Construct a `gmp_randclass', using a call to the given RANDINIT 5618 function (*note Random State Initialization::). The arguments 5619 expected are the same as RANDINIT, but with `mpz_class' instead of 5620 `mpz_t'. For example, 5621 5622 gmp_randclass r1 (gmp_randinit_default); 5623 gmp_randclass r2 (gmp_randinit_lc_2exp_size, 32); 5624 gmp_randclass r3 (gmp_randinit_lc_2exp, a, c, m2exp); 5625 gmp_randclass r4 (gmp_randinit_mt); 5626 5627 `gmp_randinit_lc_2exp_size' will fail if the size requested is too 5628 big, an `std::length_error' exception is thrown in that case. 5629 5630 -- Function: gmp_randclass::gmp_randclass (gmp_randalg_t ALG, ...) 5631 Construct a `gmp_randclass' using the same parameters as 5632 `gmp_randinit' (*note Random State Initialization::). This 5633 function is obsolete and the above RANDINIT style should be 5634 preferred. 5635 5636 -- Function: void gmp_randclass::seed (unsigned long int S) 5637 -- Function: void gmp_randclass::seed (mpz_class S) 5638 Seed a random number generator. See *note Random Number 5639 Functions::, for how to choose a good seed. 5640 5641 -- Function: mpz_class gmp_randclass::get_z_bits (unsigned long BITS) 5642 -- Function: mpz_class gmp_randclass::get_z_bits (mpz_class BITS) 5643 Generate a random integer with a specified number of bits. 5644 5645 -- Function: mpz_class gmp_randclass::get_z_range (mpz_class N) 5646 Generate a random integer in the range 0 to N-1 inclusive. 5647 5648 -- Function: mpf_class gmp_randclass::get_f () 5649 -- Function: mpf_class gmp_randclass::get_f (mp_bitcnt_t PREC) 5650 Generate a random float F in the range 0 <= F < 1. F will be to 5651 PREC bits precision, or if PREC is not given then to the precision 5652 of the destination. For example, 5653 5654 gmp_randclass r; 5655 ... 5656 mpf_class f (0, 512); // 512 bits precision 5657 f = r.get_f(); // random number, 512 bits 5658 5659 5660 File: gmp.info, Node: C++ Interface Limitations, Prev: C++ Interface Random Numbers, Up: C++ Class Interface 5661 5662 12.6 C++ Interface Limitations 5663 ============================== 5664 5665 `mpq_class' and Templated Reading 5666 A generic piece of template code probably won't know that 5667 `mpq_class' requires a `canonicalize' call if inputs read with 5668 `operator>>' might be non-canonical. This can lead to incorrect 5669 results. 5670 5671 `operator>>' behaves as it does for reasons of efficiency. A 5672 canonicalize can be quite time consuming on large operands, and is 5673 best avoided if it's not necessary. 5674 5675 But this potential difficulty reduces the usefulness of 5676 `mpq_class'. Perhaps a mechanism to tell `operator>>' what to do 5677 will be adopted in the future, maybe a preprocessor define, a 5678 global flag, or an `ios' flag pressed into service. Or maybe, at 5679 the risk of inconsistency, the `mpq_class' `operator>>' could 5680 canonicalize and leave `mpq_t' `operator>>' not doing so, for use 5681 on those occasions when that's acceptable. Send feedback or 5682 alternate ideas to <gmp-bugs (a] gmplib.org>. 5683 5684 Subclassing 5685 Subclassing the GMP C++ classes works, but is not currently 5686 recommended. 5687 5688 Expressions involving subclasses resolve correctly (or seem to), 5689 but in normal C++ fashion the subclass doesn't inherit 5690 constructors and assignments. There's many of those in the GMP 5691 classes, and a good way to reestablish them in a subclass is not 5692 yet provided. 5693 5694 Templated Expressions 5695 A subtle difficulty exists when using expressions together with 5696 application-defined template functions. Consider the following, 5697 with `T' intended to be some numeric type, 5698 5699 template <class T> 5700 T fun (const T &, const T &); 5701 5702 When used with, say, plain `mpz_class' variables, it works fine: 5703 `T' is resolved as `mpz_class'. 5704 5705 mpz_class f(1), g(2); 5706 fun (f, g); // Good 5707 5708 But when one of the arguments is an expression, it doesn't work. 5709 5710 mpz_class f(1), g(2), h(3); 5711 fun (f, g+h); // Bad 5712 5713 This is because `g+h' ends up being a certain expression template 5714 type internal to `gmpxx.h', which the C++ template resolution 5715 rules are unable to automatically convert to `mpz_class'. The 5716 workaround is simply to add an explicit cast. 5717 5718 mpz_class f(1), g(2), h(3); 5719 fun (f, mpz_class(g+h)); // Good 5720 5721 Similarly, within `fun' it may be necessary to cast an expression 5722 to type `T' when calling a templated `fun2'. 5723 5724 template <class T> 5725 void fun (T f, T g) 5726 { 5727 fun2 (f, f+g); // Bad 5728 } 5729 5730 template <class T> 5731 void fun (T f, T g) 5732 { 5733 fun2 (f, T(f+g)); // Good 5734 } 5735 5736 5737 File: gmp.info, Node: BSD Compatible Functions, Next: Custom Allocation, Prev: C++ Class Interface, Up: Top 5738 5739 13 Berkeley MP Compatible Functions 5740 *********************************** 5741 5742 These functions are intended to be fully compatible with the Berkeley MP 5743 library which is available on many BSD derived U*ix systems. The 5744 `--enable-mpbsd' option must be used when building GNU MP to make these 5745 available (*note Installing GMP::). 5746 5747 The original Berkeley MP library has a usage restriction: you cannot 5748 use the same variable as both source and destination in a single 5749 function call. The compatible functions in GNU MP do not share this 5750 restriction--inputs and outputs may overlap. 5751 5752 It is not recommended that new programs are written using these 5753 functions. Apart from the incomplete set of functions, the interface 5754 for initializing `MINT' objects is more error prone, and the `pow' 5755 function collides with `pow' in `libm.a'. 5756 5757 Include the header `mp.h' to get the definition of the necessary 5758 types and functions. If you are on a BSD derived system, make sure to 5759 include GNU `mp.h' if you are going to link the GNU `libmp.a' to your 5760 program. This means that you probably need to give the `-I<dir>' 5761 option to the compiler, where `<dir>' is the directory where you have 5762 GNU `mp.h'. 5763 5764 -- Function: MINT * itom (signed short int INITIAL_VALUE) 5765 Allocate an integer consisting of a `MINT' object and dynamic limb 5766 space. Initialize the integer to INITIAL_VALUE. Return a pointer 5767 to the `MINT' object. 5768 5769 -- Function: MINT * xtom (char *INITIAL_VALUE) 5770 Allocate an integer consisting of a `MINT' object and dynamic limb 5771 space. Initialize the integer from INITIAL_VALUE, a hexadecimal, 5772 null-terminated C string. Return a pointer to the `MINT' object. 5773 5774 -- Function: void move (MINT *SRC, MINT *DEST) 5775 Set DEST to SRC by copying. Both variables must be previously 5776 initialized. 5777 5778 -- Function: void madd (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION) 5779 Add SRC_1 and SRC_2 and put the sum in DESTINATION. 5780 5781 -- Function: void msub (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION) 5782 Subtract SRC_2 from SRC_1 and put the difference in DESTINATION. 5783 5784 -- Function: void mult (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION) 5785 Multiply SRC_1 and SRC_2 and put the product in DESTINATION. 5786 5787 -- Function: void mdiv (MINT *DIVIDEND, MINT *DIVISOR, MINT *QUOTIENT, 5788 MINT *REMAINDER) 5789 -- Function: void sdiv (MINT *DIVIDEND, signed short int DIVISOR, MINT 5790 *QUOTIENT, signed short int *REMAINDER) 5791 Set QUOTIENT to DIVIDEND/DIVISOR, and REMAINDER to DIVIDEND mod 5792 DIVISOR. The quotient is rounded towards zero; the remainder has 5793 the same sign as the dividend unless it is zero. 5794 5795 Some implementations of these functions work differently--or not 5796 at all--for negative arguments. 5797 5798 -- Function: void msqrt (MINT *OP, MINT *ROOT, MINT *REMAINDER) 5799 Set ROOT to the truncated integer part of the square root of OP, 5800 like `mpz_sqrt'. Set REMAINDER to OP-ROOT*ROOT, i.e. zero if OP 5801 is a perfect square. 5802 5803 If ROOT and REMAINDER are the same variable, the results are 5804 undefined. 5805 5806 -- Function: void pow (MINT *BASE, MINT *EXP, MINT *MOD, MINT *DEST) 5807 Set DEST to (BASE raised to EXP) modulo MOD. 5808 5809 Note that the name `pow' clashes with `pow' from the standard C 5810 math library (*note Exponentiation and Logarithms: (libc)Exponents 5811 and Logarithms.). An application will only be able to use one or 5812 the other. 5813 5814 -- Function: void rpow (MINT *BASE, signed short int EXP, MINT *DEST) 5815 Set DEST to BASE raised to EXP. 5816 5817 -- Function: void gcd (MINT *OP1, MINT *OP2, MINT *RES) 5818 Set RES to the greatest common divisor of OP1 and OP2. 5819 5820 -- Function: int mcmp (MINT *OP1, MINT *OP2) 5821 Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero 5822 if OP1 = OP2, and a negative value if OP1 < OP2. 5823 5824 -- Function: void min (MINT *DEST) 5825 Input a decimal string from `stdin', and put the read integer in 5826 DEST. SPC and TAB are allowed in the number string, and are 5827 ignored. 5828 5829 -- Function: void mout (MINT *SRC) 5830 Output SRC to `stdout', as a decimal string. Also output a 5831 newline. 5832 5833 -- Function: char * mtox (MINT *OP) 5834 Convert OP to a hexadecimal string, and return a pointer to the 5835 string. The returned string is allocated using the default memory 5836 allocation function, `malloc' by default. It will be 5837 `strlen(str)+1' bytes, that being exactly enough for the string 5838 and null-terminator. 5839 5840 -- Function: void mfree (MINT *OP) 5841 De-allocate, the space used by OP. *This function should only be 5842 passed a value returned by `itom' or `xtom'.* 5843 5844 5845 File: gmp.info, Node: Custom Allocation, Next: Language Bindings, Prev: BSD Compatible Functions, Up: Top 5846 5847 14 Custom Allocation 5848 ******************** 5849 5850 By default GMP uses `malloc', `realloc' and `free' for memory 5851 allocation, and if they fail GMP prints a message to the standard error 5852 output and terminates the program. 5853 5854 Alternate functions can be specified, to allocate memory in a 5855 different way or to have a different error action on running out of 5856 memory. 5857 5858 This feature is available in the Berkeley compatibility library 5859 (*note BSD Compatible Functions::) as well as the main GMP library. 5860 5861 -- Function: void mp_set_memory_functions ( 5862 void *(*ALLOC_FUNC_PTR) (size_t), 5863 void *(*REALLOC_FUNC_PTR) (void *, size_t, size_t), 5864 void (*FREE_FUNC_PTR) (void *, size_t)) 5865 Replace the current allocation functions from the arguments. If 5866 an argument is `NULL', the corresponding default function is used. 5867 5868 These functions will be used for all memory allocation done by 5869 GMP, apart from temporary space from `alloca' if that function is 5870 available and GMP is configured to use it (*note Build Options::). 5871 5872 *Be sure to call `mp_set_memory_functions' only when there are no 5873 active GMP objects allocated using the previous memory functions! 5874 Usually that means calling it before any other GMP function.* 5875 5876 The functions supplied should fit the following declarations: 5877 5878 -- Function: void * allocate_function (size_t ALLOC_SIZE) 5879 Return a pointer to newly allocated space with at least ALLOC_SIZE 5880 bytes. 5881 5882 -- Function: void * reallocate_function (void *PTR, size_t OLD_SIZE, 5883 size_t NEW_SIZE) 5884 Resize a previously allocated block PTR of OLD_SIZE bytes to be 5885 NEW_SIZE bytes. 5886 5887 The block may be moved if necessary or if desired, and in that 5888 case the smaller of OLD_SIZE and NEW_SIZE bytes must be copied to 5889 the new location. The return value is a pointer to the resized 5890 block, that being the new location if moved or just PTR if not. 5891 5892 PTR is never `NULL', it's always a previously allocated block. 5893 NEW_SIZE may be bigger or smaller than OLD_SIZE. 5894 5895 -- Function: void free_function (void *PTR, size_t SIZE) 5896 De-allocate the space pointed to by PTR. 5897 5898 PTR is never `NULL', it's always a previously allocated block of 5899 SIZE bytes. 5900 5901 A "byte" here means the unit used by the `sizeof' operator. 5902 5903 The REALLOCATE_FUNCTION parameter OLD_SIZE and the FREE_FUNCTION 5904 parameter SIZE are passed for convenience, but of course they can be 5905 ignored if not needed by an implementation. The default functions 5906 using `malloc' and friends for instance don't use them. 5907 5908 No error return is allowed from any of these functions, if they 5909 return then they must have performed the specified operation. In 5910 particular note that ALLOCATE_FUNCTION or REALLOCATE_FUNCTION mustn't 5911 return `NULL'. 5912 5913 Getting a different fatal error action is a good use for custom 5914 allocation functions, for example giving a graphical dialog rather than 5915 the default print to `stderr'. How much is possible when genuinely out 5916 of memory is another question though. 5917 5918 There's currently no defined way for the allocation functions to 5919 recover from an error such as out of memory, they must terminate 5920 program execution. A `longjmp' or throwing a C++ exception will have 5921 undefined results. This may change in the future. 5922 5923 GMP may use allocated blocks to hold pointers to other allocated 5924 blocks. This will limit the assumptions a conservative garbage 5925 collection scheme can make. 5926 5927 Since the default GMP allocation uses `malloc' and friends, those 5928 functions will be linked in even if the first thing a program does is an 5929 `mp_set_memory_functions'. It's necessary to change the GMP sources if 5930 this is a problem. 5931 5932 5933 -- Function: void mp_get_memory_functions ( 5934 void *(**ALLOC_FUNC_PTR) (size_t), 5935 void *(**REALLOC_FUNC_PTR) (void *, size_t, size_t), 5936 void (**FREE_FUNC_PTR) (void *, size_t)) 5937 Get the current allocation functions, storing function pointers to 5938 the locations given by the arguments. If an argument is `NULL', 5939 that function pointer is not stored. 5940 5941 For example, to get just the current free function, 5942 5943 void (*freefunc) (void *, size_t); 5944 5945 mp_get_memory_functions (NULL, NULL, &freefunc); 5946 5947 5948 File: gmp.info, Node: Language Bindings, Next: Algorithms, Prev: Custom Allocation, Up: Top 5949 5950 15 Language Bindings 5951 ******************** 5952 5953 The following packages and projects offer access to GMP from languages 5954 other than C, though perhaps with varying levels of functionality and 5955 efficiency. 5956 5957 5958 C++ 5959 * GMP C++ class interface, *note C++ Class Interface:: 5960 Straightforward interface, expression templates to eliminate 5961 temporaries. 5962 5963 * ALP `http://www-sop.inria.fr/saga/logiciels/ALP/' 5964 Linear algebra and polynomials using templates. 5965 5966 * Arithmos `http://cant.ua.ac.be/old/arithmos/' 5967 Rationals with infinities and square roots. 5968 5969 * CLN `http://www.ginac.de/CLN/' 5970 High level classes for arithmetic. 5971 5972 * LiDIA `http://www.cdc.informatik.tu-darmstadt.de/TI/LiDIA/' 5973 A C++ library for computational number theory. 5974 5975 * Linbox `http://www.linalg.org/' 5976 Sparse vectors and matrices. 5977 5978 * NTL `http://www.shoup.net/ntl/' 5979 A C++ number theory library. 5980 5981 Eiffel 5982 * Eiffelroom `http://www.eiffelroom.org/node/442' 5983 5984 Fortran 5985 * Omni F77 `http://phase.hpcc.jp/Omni/home.html' 5986 Arbitrary precision floats. 5987 5988 Haskell 5989 * Glasgow Haskell Compiler `http://www.haskell.org/ghc/' 5990 5991 Java 5992 * Kaffe `http://www.kaffe.org/' 5993 5994 * Kissme `http://kissme.sourceforge.net/' 5995 5996 Lisp 5997 * GNU Common Lisp `http://www.gnu.org/software/gcl/gcl.html' 5998 5999 * Librep `http://librep.sourceforge.net/' 6000 6001 * XEmacs (21.5.18 beta and up) `http://www.xemacs.org' 6002 Optional big integers, rationals and floats using GMP. 6003 6004 M4 6005 * GNU m4 betas `http://www.seindal.dk/rene/gnu/' 6006 Optionally provides an arbitrary precision `mpeval'. 6007 6008 ML 6009 * MLton compiler `http://mlton.org/' 6010 6011 Objective Caml 6012 * MLGMP `http://www.di.ens.fr/~monniaux/programmes.html.en' 6013 6014 * Numerix `http://pauillac.inria.fr/~quercia/' 6015 Optionally using GMP. 6016 6017 Oz 6018 * Mozart `http://www.mozart-oz.org/' 6019 6020 Pascal 6021 * GNU Pascal Compiler `http://www.gnu-pascal.de/' 6022 GMP unit. 6023 6024 * Numerix `http://pauillac.inria.fr/~quercia/' 6025 For Free Pascal, optionally using GMP. 6026 6027 Perl 6028 * GMP module, see `demos/perl' in the GMP sources (*note 6029 Demonstration Programs::). 6030 6031 * Math::GMP `http://www.cpan.org/' 6032 Compatible with Math::BigInt, but not as many functions as 6033 the GMP module above. 6034 6035 * Math::BigInt::GMP `http://www.cpan.org/' 6036 Plug Math::GMP into normal Math::BigInt operations. 6037 6038 Pike 6039 * mpz module in the standard distribution, 6040 `http://pike.ida.liu.se/' 6041 6042 Prolog 6043 * SWI Prolog `http://www.swi-prolog.org/' 6044 Arbitrary precision floats. 6045 6046 Python 6047 * GMPY `http://code.google.com/p/gmpy/' 6048 6049 Ruby 6050 * http://rubygems.org/gems/gmp 6051 6052 Scheme 6053 * GNU Guile (upcoming 1.8) 6054 `http://www.gnu.org/software/guile/guile.html' 6055 6056 * RScheme `http://www.rscheme.org/' 6057 6058 * STklos `http://www.stklos.org/' 6059 6060 Smalltalk 6061 * GNU Smalltalk 6062 `http://www.smalltalk.org/versions/GNUSmalltalk.html' 6063 6064 Other 6065 * Axiom `http://savannah.nongnu.org/projects/axiom' 6066 Computer algebra using GCL. 6067 6068 * DrGenius `http://drgenius.seul.org/' 6069 Geometry system and mathematical programming language. 6070 6071 * GiNaC `http://www.ginac.de/' 6072 C++ computer algebra using CLN. 6073 6074 * GOO `http://www.googoogaga.org/' 6075 Dynamic object oriented language. 6076 6077 * Maxima `http://www.ma.utexas.edu/users/wfs/maxima.html' 6078 Macsyma computer algebra using GCL. 6079 6080 * Q `http://q-lang.sourceforge.net/' 6081 Equational programming system. 6082 6083 * Regina `http://regina.sourceforge.net/' 6084 Topological calculator. 6085 6086 * Yacas `yacas.sourceforge.net' 6087 Yet another computer algebra system. 6088 6089 6090 6091 File: gmp.info, Node: Algorithms, Next: Internals, Prev: Language Bindings, Up: Top 6092 6093 16 Algorithms 6094 ************* 6095 6096 This chapter is an introduction to some of the algorithms used for 6097 various GMP operations. The code is likely to be hard to understand 6098 without knowing something about the algorithms. 6099 6100 Some GMP internals are mentioned, but applications that expect to be 6101 compatible with future GMP releases should take care to use only the 6102 documented functions. 6103 6104 * Menu: 6105 6106 * Multiplication Algorithms:: 6107 * Division Algorithms:: 6108 * Greatest Common Divisor Algorithms:: 6109 * Powering Algorithms:: 6110 * Root Extraction Algorithms:: 6111 * Radix Conversion Algorithms:: 6112 * Other Algorithms:: 6113 * Assembly Coding:: 6114 6115 6116 File: gmp.info, Node: Multiplication Algorithms, Next: Division Algorithms, Prev: Algorithms, Up: Algorithms 6117 6118 16.1 Multiplication 6119 =================== 6120 6121 NxN limb multiplications and squares are done using one of seven 6122 algorithms, as the size N increases. 6123 6124 Algorithm Threshold 6125 Basecase (none) 6126 Karatsuba `MUL_TOOM22_THRESHOLD' 6127 Toom-3 `MUL_TOOM33_THRESHOLD' 6128 Toom-4 `MUL_TOOM44_THRESHOLD' 6129 Toom-6.5 `MUL_TOOM6H_THRESHOLD' 6130 Toom-8.5 `MUL_TOOM8H_THRESHOLD' 6131 FFT `MUL_FFT_THRESHOLD' 6132 6133 Similarly for squaring, with the `SQR' thresholds. 6134 6135 NxM multiplications of operands with different sizes above 6136 `MUL_TOOM22_THRESHOLD' are currently done by special Toom-inspired 6137 algorithms or directly with FFT, depending on operand size (*note 6138 Unbalanced Multiplication::). 6139 6140 * Menu: 6141 6142 * Basecase Multiplication:: 6143 * Karatsuba Multiplication:: 6144 * Toom 3-Way Multiplication:: 6145 * Toom 4-Way Multiplication:: 6146 * Higher degree Toom'n'half:: 6147 * FFT Multiplication:: 6148 * Other Multiplication:: 6149 * Unbalanced Multiplication:: 6150 6151 6152 File: gmp.info, Node: Basecase Multiplication, Next: Karatsuba Multiplication, Prev: Multiplication Algorithms, Up: Multiplication Algorithms 6153 6154 16.1.1 Basecase Multiplication 6155 ------------------------------ 6156 6157 Basecase NxM multiplication is a straightforward rectangular set of 6158 cross-products, the same as long multiplication done by hand and for 6159 that reason sometimes known as the schoolbook or grammar school method. 6160 This is an O(N*M) algorithm. See Knuth section 4.3.1 algorithm M 6161 (*note References::), and the `mpn/generic/mul_basecase.c' code. 6162 6163 Assembly implementations of `mpn_mul_basecase' are essentially the 6164 same as the generic C code, but have all the usual assembly tricks and 6165 obscurities introduced for speed. 6166 6167 A square can be done in roughly half the time of a multiply, by 6168 using the fact that the cross products above and below the diagonal are 6169 the same. A triangle of products below the diagonal is formed, doubled 6170 (left shift by one bit), and then the products on the diagonal added. 6171 This can be seen in `mpn/generic/sqr_basecase.c'. Again the assembly 6172 implementations take essentially the same approach. 6173 6174 u0 u1 u2 u3 u4 6175 +---+---+---+---+---+ 6176 u0 | d | | | | | 6177 +---+---+---+---+---+ 6178 u1 | | d | | | | 6179 +---+---+---+---+---+ 6180 u2 | | | d | | | 6181 +---+---+---+---+---+ 6182 u3 | | | | d | | 6183 +---+---+---+---+---+ 6184 u4 | | | | | d | 6185 +---+---+---+---+---+ 6186 6187 In practice squaring isn't a full 2x faster than multiplying, it's 6188 usually around 1.5x. Less than 1.5x probably indicates 6189 `mpn_sqr_basecase' wants improving on that CPU. 6190 6191 On some CPUs `mpn_mul_basecase' can be faster than the generic C 6192 `mpn_sqr_basecase' on some small sizes. `SQR_BASECASE_THRESHOLD' is 6193 the size at which to use `mpn_sqr_basecase', this will be zero if that 6194 routine should be used always. 6195 6196 6197 File: gmp.info, Node: Karatsuba Multiplication, Next: Toom 3-Way Multiplication, Prev: Basecase Multiplication, Up: Multiplication Algorithms 6198 6199 16.1.2 Karatsuba Multiplication 6200 ------------------------------- 6201 6202 The Karatsuba multiplication algorithm is described in Knuth section 6203 4.3.3 part A, and various other textbooks. A brief description is 6204 given here. 6205 6206 The inputs x and y are treated as each split into two parts of equal 6207 length (or the most significant part one limb shorter if N is odd). 6208 6209 high low 6210 +----------+----------+ 6211 | x1 | x0 | 6212 +----------+----------+ 6213 6214 +----------+----------+ 6215 | y1 | y0 | 6216 +----------+----------+ 6217 6218 Let b be the power of 2 where the split occurs, i.e. if x0 is k 6219 limbs (y0 the same) then b=2^(k*mp_bits_per_limb). With that x=x1*b+x0 6220 and y=y1*b+y0, and the following holds, 6221 6222 x*y = (b^2+b)*x1*y1 - b*(x1-x0)*(y1-y0) + (b+1)*x0*y0 6223 6224 This formula means doing only three multiplies of (N/2)x(N/2) limbs, 6225 whereas a basecase multiply of NxN limbs is equivalent to four 6226 multiplies of (N/2)x(N/2). The factors (b^2+b) etc represent the 6227 positions where the three products must be added. 6228 6229 high low 6230 +--------+--------+ +--------+--------+ 6231 | x1*y1 | | x0*y0 | 6232 +--------+--------+ +--------+--------+ 6233 +--------+--------+ 6234 add | x1*y1 | 6235 +--------+--------+ 6236 +--------+--------+ 6237 add | x0*y0 | 6238 +--------+--------+ 6239 +--------+--------+ 6240 sub | (x1-x0)*(y1-y0) | 6241 +--------+--------+ 6242 6243 The term (x1-x0)*(y1-y0) is best calculated as an absolute value, 6244 and the sign used to choose to add or subtract. Notice the sum 6245 high(x0*y0)+low(x1*y1) occurs twice, so it's possible to do 5*k limb 6246 additions, rather than 6*k, but in GMP extra function call overheads 6247 outweigh the saving. 6248 6249 Squaring is similar to multiplying, but with x=y the formula reduces 6250 to an equivalent with three squares, 6251 6252 x^2 = (b^2+b)*x1^2 - b*(x1-x0)^2 + (b+1)*x0^2 6253 6254 The final result is accumulated from those three squares the same 6255 way as for the three multiplies above. The middle term (x1-x0)^2 is now 6256 always positive. 6257 6258 A similar formula for both multiplying and squaring can be 6259 constructed with a middle term (x1+x0)*(y1+y0). But those sums can 6260 exceed k limbs, leading to more carry handling and additions than the 6261 form above. 6262 6263 Karatsuba multiplication is asymptotically an O(N^1.585) algorithm, 6264 the exponent being log(3)/log(2), representing 3 multiplies each 1/2 6265 the size of the inputs. This is a big improvement over the basecase 6266 multiply at O(N^2) and the advantage soon overcomes the extra additions 6267 Karatsuba performs. `MUL_TOOM22_THRESHOLD' can be as little as 10 6268 limbs. The `SQR' threshold is usually about twice the `MUL'. 6269 6270 The basecase algorithm will take a time of the form M(N) = a*N^2 + 6271 b*N + c and the Karatsuba algorithm K(N) = 3*M(N/2) + d*N + e, which 6272 expands to K(N) = 3/4*a*N^2 + 3/2*b*N + 3*c + d*N + e. The factor 3/4 6273 for a means per-crossproduct speedups in the basecase code will 6274 increase the threshold since they benefit M(N) more than K(N). And 6275 conversely the 3/2 for b means linear style speedups of b will increase 6276 the threshold since they benefit K(N) more than M(N). The latter can 6277 be seen for instance when adding an optimized `mpn_sqr_diagonal' to 6278 `mpn_sqr_basecase'. Of course all speedups reduce total time, and in 6279 that sense the algorithm thresholds are merely of academic interest. 6280 6281 6282 File: gmp.info, Node: Toom 3-Way Multiplication, Next: Toom 4-Way Multiplication, Prev: Karatsuba Multiplication, Up: Multiplication Algorithms 6283 6284 16.1.3 Toom 3-Way Multiplication 6285 -------------------------------- 6286 6287 The Karatsuba formula is the simplest case of a general approach to 6288 splitting inputs that leads to both Toom and FFT algorithms. A 6289 description of Toom can be found in Knuth section 4.3.3, with an 6290 example 3-way calculation after Theorem A. The 3-way form used in GMP 6291 is described here. 6292 6293 The operands are each considered split into 3 pieces of equal length 6294 (or the most significant part 1 or 2 limbs shorter than the other two). 6295 6296 high low 6297 +----------+----------+----------+ 6298 | x2 | x1 | x0 | 6299 +----------+----------+----------+ 6300 6301 +----------+----------+----------+ 6302 | y2 | y1 | y0 | 6303 +----------+----------+----------+ 6304 6305 These parts are treated as the coefficients of two polynomials 6306 6307 X(t) = x2*t^2 + x1*t + x0 6308 Y(t) = y2*t^2 + y1*t + y0 6309 6310 Let b equal the power of 2 which is the size of the x0, x1, y0 and 6311 y1 pieces, i.e. if they're k limbs each then b=2^(k*mp_bits_per_limb). 6312 With this x=X(b) and y=Y(b). 6313 6314 Let a polynomial W(t)=X(t)*Y(t) and suppose its coefficients are 6315 6316 W(t) = w4*t^4 + w3*t^3 + w2*t^2 + w1*t + w0 6317 6318 The w[i] are going to be determined, and when they are they'll give 6319 the final result using w=W(b), since x*y=X(b)*Y(b)=W(b). The 6320 coefficients will be roughly b^2 each, and the final W(b) will be an 6321 addition like, 6322 6323 high low 6324 +-------+-------+ 6325 | w4 | 6326 +-------+-------+ 6327 +--------+-------+ 6328 | w3 | 6329 +--------+-------+ 6330 +--------+-------+ 6331 | w2 | 6332 +--------+-------+ 6333 +--------+-------+ 6334 | w1 | 6335 +--------+-------+ 6336 +-------+-------+ 6337 | w0 | 6338 +-------+-------+ 6339 6340 The w[i] coefficients could be formed by a simple set of cross 6341 products, like w4=x2*y2, w3=x2*y1+x1*y2, w2=x2*y0+x1*y1+x0*y2 etc, but 6342 this would need all nine x[i]*y[j] for i,j=0,1,2, and would be 6343 equivalent merely to a basecase multiply. Instead the following 6344 approach is used. 6345 6346 X(t) and Y(t) are evaluated and multiplied at 5 points, giving 6347 values of W(t) at those points. In GMP the following points are used, 6348 6349 Point Value 6350 t=0 x0 * y0, which gives w0 immediately 6351 t=1 (x2+x1+x0) * (y2+y1+y0) 6352 t=-1 (x2-x1+x0) * (y2-y1+y0) 6353 t=2 (4*x2+2*x1+x0) * (4*y2+2*y1+y0) 6354 t=inf x2 * y2, which gives w4 immediately 6355 6356 At t=-1 the values can be negative and that's handled using the 6357 absolute values and tracking the sign separately. At t=inf the value 6358 is actually X(t)*Y(t)/t^4 in the limit as t approaches infinity, but 6359 it's much easier to think of as simply x2*y2 giving w4 immediately 6360 (much like x0*y0 at t=0 gives w0 immediately). 6361 6362 Each of the points substituted into W(t)=w4*t^4+...+w0 gives a 6363 linear combination of the w[i] coefficients, and the value of those 6364 combinations has just been calculated. 6365 6366 W(0) = w0 6367 W(1) = w4 + w3 + w2 + w1 + w0 6368 W(-1) = w4 - w3 + w2 - w1 + w0 6369 W(2) = 16*w4 + 8*w3 + 4*w2 + 2*w1 + w0 6370 W(inf) = w4 6371 6372 This is a set of five equations in five unknowns, and some 6373 elementary linear algebra quickly isolates each w[i]. This involves 6374 adding or subtracting one W(t) value from another, and a couple of 6375 divisions by powers of 2 and one division by 3, the latter using the 6376 special `mpn_divexact_by3' (*note Exact Division::). 6377 6378 The conversion of W(t) values to the coefficients is interpolation. 6379 A polynomial of degree 4 like W(t) is uniquely determined by values 6380 known at 5 different points. The points are arbitrary and can be 6381 chosen to make the linear equations come out with a convenient set of 6382 steps for quickly isolating the w[i]. 6383 6384 Squaring follows the same procedure as multiplication, but there's 6385 only one X(t) and it's evaluated at the 5 points, and those values 6386 squared to give values of W(t). The interpolation is then identical, 6387 and in fact the same `toom_interpolate_5pts' subroutine is used for 6388 both squaring and multiplying. 6389 6390 Toom-3 is asymptotically O(N^1.465), the exponent being 6391 log(5)/log(3), representing 5 recursive multiplies of 1/3 the original 6392 size each. This is an improvement over Karatsuba at O(N^1.585), though 6393 Toom does more work in the evaluation and interpolation and so it only 6394 realizes its advantage above a certain size. 6395 6396 Near the crossover between Toom-3 and Karatsuba there's generally a 6397 range of sizes where the difference between the two is small. 6398 `MUL_TOOM33_THRESHOLD' is a somewhat arbitrary point in that range and 6399 successive runs of the tune program can give different values due to 6400 small variations in measuring. A graph of time versus size for the two 6401 shows the effect, see `tune/README'. 6402 6403 At the fairly small sizes where the Toom-3 thresholds occur it's 6404 worth remembering that the asymptotic behaviour for Karatsuba and 6405 Toom-3 can't be expected to make accurate predictions, due of course to 6406 the big influence of all sorts of overheads, and the fact that only a 6407 few recursions of each are being performed. Even at large sizes 6408 there's a good chance machine dependent effects like cache architecture 6409 will mean actual performance deviates from what might be predicted. 6410 6411 The formula given for the Karatsuba algorithm (*note Karatsuba 6412 Multiplication::) has an equivalent for Toom-3 involving only five 6413 multiplies, but this would be complicated and unenlightening. 6414 6415 An alternate view of Toom-3 can be found in Zuras (*note 6416 References::), using a vector to represent the x and y splits and a 6417 matrix multiplication for the evaluation and interpolation stages. The 6418 matrix inverses are not meant to be actually used, and they have 6419 elements with values much greater than in fact arise in the 6420 interpolation steps. The diagram shown for the 3-way is attractive, 6421 but again doesn't have to be implemented that way and for example with 6422 a bit of rearrangement just one division by 6 can be done. 6423 6424 6425 File: gmp.info, Node: Toom 4-Way Multiplication, Next: Higher degree Toom'n'half, Prev: Toom 3-Way Multiplication, Up: Multiplication Algorithms 6426 6427 16.1.4 Toom 4-Way Multiplication 6428 -------------------------------- 6429 6430 Karatsuba and Toom-3 split the operands into 2 and 3 coefficients, 6431 respectively. Toom-4 analogously splits the operands into 4 6432 coefficients. Using the notation from the section on Toom-3 6433 multiplication, we form two polynomials: 6434 6435 X(t) = x3*t^3 + x2*t^2 + x1*t + x0 6436 Y(t) = y3*t^3 + y2*t^2 + y1*t + y0 6437 6438 X(t) and Y(t) are evaluated and multiplied at 7 points, giving 6439 values of W(t) at those points. In GMP the following points are used, 6440 6441 Point Value 6442 t=0 x0 * y0, which gives w0 immediately 6443 t=1/2 (x3+2*x2+4*x1+8*x0) * (y3+2*y2+4*y1+8*y0) 6444 t=-1/2 (-x3+2*x2-4*x1+8*x0) * (-y3+2*y2-4*y1+8*y0) 6445 t=1 (x3+x2+x1+x0) * (y3+y2+y1+y0) 6446 t=-1 (-x3+x2-x1+x0) * (-y3+y2-y1+y0) 6447 t=2 (8*x3+4*x2+2*x1+x0) * (8*y3+4*y2+2*y1+y0) 6448 t=inf x3 * y3, which gives w6 immediately 6449 6450 The number of additions and subtractions for Toom-4 is much larger 6451 than for Toom-3. But several subexpressions occur multiple times, for 6452 example x2+x0, occurs for both t=1 and t=-1. 6453 6454 Toom-4 is asymptotically O(N^1.404), the exponent being 6455 log(7)/log(4), representing 7 recursive multiplies of 1/4 the original 6456 size each. 6457 6458 6459 File: gmp.info, Node: Higher degree Toom'n'half, Next: FFT Multiplication, Prev: Toom 4-Way Multiplication, Up: Multiplication Algorithms 6460 6461 16.1.5 Higher degree Toom'n'half 6462 -------------------------------- 6463 6464 The Toom algorithms described above (*note Toom 3-Way Multiplication::, 6465 *note Toom 4-Way Multiplication::) generalizes to split into an 6466 arbitrary number of pieces. In general a split of two equally long 6467 operands into r pieces leads to evaluations and pointwise 6468 multiplications done at 2*r-1 points. To fully exploit symmetries it 6469 would be better to have a multiple of 4 points, that's why for higher 6470 degree Toom'n'half is used. 6471 6472 Toom'n'half means that the existence of one more piece is considered 6473 for a single operand. It can be virtual, i.e. zero, or real, when the 6474 two operand are not exactly balanced. By chosing an even r, Toom-r+1/2 6475 requires 2r points, a multiple of four. 6476 6477 The four-plets of points inlcude 0, inf, +1, -1 and +-2^i, +-2^-i . 6478 Each of them giving shortcuts for the evaluation phase and for some 6479 steps in the interpolation phase. Further tricks are used to reduce the 6480 memory footprint of the whole multiplication algorithm to a memory 6481 buffer equanl in size to the result of the product. 6482 6483 Current GMP uses both Toom-6'n'half and Toom-8'n'half. 6484 6485 6486 File: gmp.info, Node: FFT Multiplication, Next: Other Multiplication, Prev: Higher degree Toom'n'half, Up: Multiplication Algorithms 6487 6488 16.1.6 FFT Multiplication 6489 ------------------------- 6490 6491 At large to very large sizes a Fermat style FFT multiplication is used, 6492 following Schnhage and Strassen (*note References::). Descriptions of 6493 FFTs in various forms can be found in many textbooks, for instance 6494 Knuth section 4.3.3 part C or Lipson chapter IX. A brief description 6495 of the form used in GMP is given here. 6496 6497 The multiplication done is x*y mod 2^N+1, for a given N. A full 6498 product x*y is obtained by choosing N>=bits(x)+bits(y) and padding x 6499 and y with high zero limbs. The modular product is the native form for 6500 the algorithm, so padding to get a full product is unavoidable. 6501 6502 The algorithm follows a split, evaluate, pointwise multiply, 6503 interpolate and combine similar to that described above for Karatsuba 6504 and Toom-3. A k parameter controls the split, with an FFT-k splitting 6505 into 2^k pieces of M=N/2^k bits each. N must be a multiple of 6506 (2^k)*mp_bits_per_limb so the split falls on limb boundaries, avoiding 6507 bit shifts in the split and combine stages. 6508 6509 The evaluations, pointwise multiplications, and interpolation, are 6510 all done modulo 2^N'+1 where N' is 2M+k+3 rounded up to a multiple of 6511 2^k and of `mp_bits_per_limb'. The results of interpolation will be 6512 the following negacyclic convolution of the input pieces, and the 6513 choice of N' ensures these sums aren't truncated. 6514 6515 --- 6516 \ b 6517 w[n] = / (-1) * x[i] * y[j] 6518 --- 6519 i+j==b*2^k+n 6520 b=0,1 6521 6522 The points used for the evaluation are g^i for i=0 to 2^k-1 where 6523 g=2^(2N'/2^k). g is a 2^k'th root of unity mod 2^N'+1, which produces 6524 necessary cancellations at the interpolation stage, and it's also a 6525 power of 2 so the fast Fourier transforms used for the evaluation and 6526 interpolation do only shifts, adds and negations. 6527 6528 The pointwise multiplications are done modulo 2^N'+1 and either 6529 recurse into a further FFT or use a plain multiplication (Toom-3, 6530 Karatsuba or basecase), whichever is optimal at the size N'. The 6531 interpolation is an inverse fast Fourier transform. The resulting set 6532 of sums of x[i]*y[j] are added at appropriate offsets to give the final 6533 result. 6534 6535 Squaring is the same, but x is the only input so it's one transform 6536 at the evaluate stage and the pointwise multiplies are squares. The 6537 interpolation is the same. 6538 6539 For a mod 2^N+1 product, an FFT-k is an O(N^(k/(k-1))) algorithm, 6540 the exponent representing 2^k recursed modular multiplies each 6541 1/2^(k-1) the size of the original. Each successive k is an asymptotic 6542 improvement, but overheads mean each is only faster at bigger and 6543 bigger sizes. In the code, `MUL_FFT_TABLE' and `SQR_FFT_TABLE' are the 6544 thresholds where each k is used. Each new k effectively swaps some 6545 multiplying for some shifts, adds and overheads. 6546 6547 A mod 2^N+1 product can be formed with a normal NxN->2N bit multiply 6548 plus a subtraction, so an FFT and Toom-3 etc can be compared directly. 6549 A k=4 FFT at O(N^1.333) can be expected to be the first faster than 6550 Toom-3 at O(N^1.465). In practice this is what's found, with 6551 `MUL_FFT_MODF_THRESHOLD' and `SQR_FFT_MODF_THRESHOLD' being between 300 6552 and 1000 limbs, depending on the CPU. So far it's been found that only 6553 very large FFTs recurse into pointwise multiplies above these sizes. 6554 6555 When an FFT is to give a full product, the change of N to 2N doesn't 6556 alter the theoretical complexity for a given k, but for the purposes of 6557 considering where an FFT might be first used it can be assumed that the 6558 FFT is recursing into a normal multiply and that on that basis it's 6559 doing 2^k recursed multiplies each 1/2^(k-2) the size of the inputs, 6560 making it O(N^(k/(k-2))). This would mean k=7 at O(N^1.4) would be the 6561 first FFT faster than Toom-3. In practice `MUL_FFT_THRESHOLD' and 6562 `SQR_FFT_THRESHOLD' have been found to be in the k=8 range, somewhere 6563 between 3000 and 10000 limbs. 6564 6565 The way N is split into 2^k pieces and then 2M+k+3 is rounded up to 6566 a multiple of 2^k and `mp_bits_per_limb' means that when 6567 2^k>=mp_bits_per_limb the effective N is a multiple of 2^(2k-1) bits. 6568 The +k+3 means some values of N just under such a multiple will be 6569 rounded to the next. The complexity calculations above assume that a 6570 favourable size is used, meaning one which isn't padded through 6571 rounding, and it's also assumed that the extra +k+3 bits are negligible 6572 at typical FFT sizes. 6573 6574 The practical effect of the 2^(2k-1) constraint is to introduce a 6575 step-effect into measured speeds. For example k=8 will round N up to a 6576 multiple of 32768 bits, so for a 32-bit limb there'll be 512 limb 6577 groups of sizes for which `mpn_mul_n' runs at the same speed. Or for 6578 k=9 groups of 2048 limbs, k=10 groups of 8192 limbs, etc. In practice 6579 it's been found each k is used at quite small multiples of its size 6580 constraint and so the step effect is quite noticeable in a time versus 6581 size graph. 6582 6583 The threshold determinations currently measure at the mid-points of 6584 size steps, but this is sub-optimal since at the start of a new step it 6585 can happen that it's better to go back to the previous k for a while. 6586 Something more sophisticated for `MUL_FFT_TABLE' and `SQR_FFT_TABLE' 6587 will be needed. 6588 6589 6590 File: gmp.info, Node: Other Multiplication, Next: Unbalanced Multiplication, Prev: FFT Multiplication, Up: Multiplication Algorithms 6591 6592 16.1.7 Other Multiplication 6593 --------------------------- 6594 6595 The Toom algorithms described above (*note Toom 3-Way Multiplication::, 6596 *note Toom 4-Way Multiplication::) generalizes to split into an 6597 arbitrary number of pieces, as per Knuth section 4.3.3 algorithm C. 6598 This is not currently used. The notes here are merely for interest. 6599 6600 In general a split into r+1 pieces is made, and evaluations and 6601 pointwise multiplications done at 2*r+1 points. A 4-way split does 7 6602 pointwise multiplies, 5-way does 9, etc. Asymptotically an (r+1)-way 6603 algorithm is O(N^(log(2*r+1)/log(r+1))). Only the pointwise 6604 multiplications count towards big-O complexity, but the time spent in 6605 the evaluate and interpolate stages grows with r and has a significant 6606 practical impact, with the asymptotic advantage of each r realized only 6607 at bigger and bigger sizes. The overheads grow as O(N*r), whereas in 6608 an r=2^k FFT they grow only as O(N*log(r)). 6609 6610 Knuth algorithm C evaluates at points 0,1,2,...,2*r, but exercise 4 6611 uses -r,...,0,...,r and the latter saves some small multiplies in the 6612 evaluate stage (or rather trades them for additions), and has a further 6613 saving of nearly half the interpolate steps. The idea is to separate 6614 odd and even final coefficients and then perform algorithm C steps C7 6615 and C8 on them separately. The divisors at step C7 become j^2 and the 6616 multipliers at C8 become 2*t*j-j^2. 6617 6618 Splitting odd and even parts through positive and negative points 6619 can be thought of as using -1 as a square root of unity. If a 4th root 6620 of unity was available then a further split and speedup would be 6621 possible, but no such root exists for plain integers. Going to complex 6622 integers with i=sqrt(-1) doesn't help, essentially because in Cartesian 6623 form it takes three real multiplies to do a complex multiply. The 6624 existence of 2^k'th roots of unity in a suitable ring or field lets the 6625 fast Fourier transform keep splitting and get to O(N*log(r)). 6626 6627 Floating point FFTs use complex numbers approximating Nth roots of 6628 unity. Some processors have special support for such FFTs. But these 6629 are not used in GMP since it's very difficult to guarantee an exact 6630 result (to some number of bits). An occasional difference of 1 in the 6631 last bit might not matter to a typical signal processing algorithm, but 6632 is of course of vital importance to GMP. 6633 6634 6635 File: gmp.info, Node: Unbalanced Multiplication, Prev: Other Multiplication, Up: Multiplication Algorithms 6636 6637 16.1.8 Unbalanced Multiplication 6638 -------------------------------- 6639 6640 Multiplication of operands with different sizes, both below 6641 `MUL_TOOM22_THRESHOLD' are done with plain schoolbook multiplication 6642 (*note Basecase Multiplication::). 6643 6644 For really large operands, we invoke FFT directly. 6645 6646 For operands between these sizes, we use Toom inspired algorithms 6647 suggested by Alberto Zanoni and Marco Bodrato. The idea is to split 6648 the operands into polynomials of different degree. GMP currently 6649 splits the smaller operand onto 2 coefficients, i.e., a polynomial of 6650 degree 1, but the larger operand can be split into 2, 3, or 4 6651 coefficients, i.e., a polynomial of degree 1 to 3. 6652 6653 6654 File: gmp.info, Node: Division Algorithms, Next: Greatest Common Divisor Algorithms, Prev: Multiplication Algorithms, Up: Algorithms 6655 6656 16.2 Division Algorithms 6657 ======================== 6658 6659 * Menu: 6660 6661 * Single Limb Division:: 6662 * Basecase Division:: 6663 * Divide and Conquer Division:: 6664 * Block-Wise Barrett Division:: 6665 * Exact Division:: 6666 * Exact Remainder:: 6667 * Small Quotient Division:: 6668 6669 6670 File: gmp.info, Node: Single Limb Division, Next: Basecase Division, Prev: Division Algorithms, Up: Division Algorithms 6671 6672 16.2.1 Single Limb Division 6673 --------------------------- 6674 6675 Nx1 division is implemented using repeated 2x1 divisions from high to 6676 low, either with a hardware divide instruction or a multiplication by 6677 inverse, whichever is best on a given CPU. 6678 6679 The multiply by inverse follows "Improved division by invariant 6680 integers" by Mller and Granlund (*note References::) and is 6681 implemented as `udiv_qrnnd_preinv' in `gmp-impl.h'. The idea is to 6682 have a fixed-point approximation to 1/d (see `invert_limb') and then 6683 multiply by the high limb (plus one bit) of the dividend to get a 6684 quotient q. With d normalized (high bit set), q is no more than 1 too 6685 small. Subtracting q*d from the dividend gives a remainder, and 6686 reveals whether q or q-1 is correct. 6687 6688 The result is a division done with two multiplications and four or 6689 five arithmetic operations. On CPUs with low latency multipliers this 6690 can be much faster than a hardware divide, though the cost of 6691 calculating the inverse at the start may mean it's only better on 6692 inputs bigger than say 4 or 5 limbs. 6693 6694 When a divisor must be normalized, either for the generic C 6695 `__udiv_qrnnd_c' or the multiply by inverse, the division performed is 6696 actually a*2^k by d*2^k where a is the dividend and k is the power 6697 necessary to have the high bit of d*2^k set. The bit shifts for the 6698 dividend are usually accomplished "on the fly" meaning by extracting 6699 the appropriate bits at each step. Done this way the quotient limbs 6700 come out aligned ready to store. When only the remainder is wanted, an 6701 alternative is to take the dividend limbs unshifted and calculate r = a 6702 mod d*2^k followed by an extra final step r*2^k mod d*2^k. This can 6703 help on CPUs with poor bit shifts or few registers. 6704 6705 The multiply by inverse can be done two limbs at a time. The 6706 calculation is basically the same, but the inverse is two limbs and the 6707 divisor treated as if padded with a low zero limb. This means more 6708 work, since the inverse will need a 2x2 multiply, but the four 1x1s to 6709 do that are independent and can therefore be done partly or wholly in 6710 parallel. Likewise for a 2x1 calculating q*d. The net effect is to 6711 process two limbs with roughly the same two multiplies worth of latency 6712 that one limb at a time gives. This extends to 3 or 4 limbs at a time, 6713 though the extra work to apply the inverse will almost certainly soon 6714 reach the limits of multiplier throughput. 6715 6716 A similar approach in reverse can be taken to process just half a 6717 limb at a time if the divisor is only a half limb. In this case the 6718 1x1 multiply for the inverse effectively becomes two (1/2)x1 for each 6719 limb, which can be a saving on CPUs with a fast half limb multiply, or 6720 in fact if the only multiply is a half limb, and especially if it's not 6721 pipelined. 6722 6723 6724 File: gmp.info, Node: Basecase Division, Next: Divide and Conquer Division, Prev: Single Limb Division, Up: Division Algorithms 6725 6726 16.2.2 Basecase Division 6727 ------------------------ 6728 6729 Basecase NxM division is like long division done by hand, but in base 6730 2^mp_bits_per_limb. See Knuth section 4.3.1 algorithm D, and 6731 `mpn/generic/sb_divrem_mn.c'. 6732 6733 Briefly stated, while the dividend remains larger than the divisor, 6734 a high quotient limb is formed and the Nx1 product q*d subtracted at 6735 the top end of the dividend. With a normalized divisor (most 6736 significant bit set), each quotient limb can be formed with a 2x1 6737 division and a 1x1 multiplication plus some subtractions. The 2x1 6738 division is by the high limb of the divisor and is done either with a 6739 hardware divide or a multiply by inverse (the same as in *note Single 6740 Limb Division::) whichever is faster. Such a quotient is sometimes one 6741 too big, requiring an addback of the divisor, but that happens rarely. 6742 6743 With Q=N-M being the number of quotient limbs, this is an O(Q*M) 6744 algorithm and will run at a speed similar to a basecase QxM 6745 multiplication, differing in fact only in the extra multiply and divide 6746 for each of the Q quotient limbs. 6747 6748 6749 File: gmp.info, Node: Divide and Conquer Division, Next: Block-Wise Barrett Division, Prev: Basecase Division, Up: Division Algorithms 6750 6751 16.2.3 Divide and Conquer Division 6752 ---------------------------------- 6753 6754 For divisors larger than `DC_DIV_QR_THRESHOLD', division is done by 6755 dividing. Or to be precise by a recursive divide and conquer algorithm 6756 based on work by Moenck and Borodin, Jebelean, and Burnikel and Ziegler 6757 (*note References::). 6758 6759 The algorithm consists essentially of recognising that a 2NxN 6760 division can be done with the basecase division algorithm (*note 6761 Basecase Division::), but using N/2 limbs as a base, not just a single 6762 limb. This way the multiplications that arise are (N/2)x(N/2) and can 6763 take advantage of Karatsuba and higher multiplication algorithms (*note 6764 Multiplication Algorithms::). The two "digits" of the quotient are 6765 formed by recursive Nx(N/2) divisions. 6766 6767 If the (N/2)x(N/2) multiplies are done with a basecase multiplication 6768 then the work is about the same as a basecase division, but with more 6769 function call overheads and with some subtractions separated from the 6770 multiplies. These overheads mean that it's only when N/2 is above 6771 `MUL_TOOM22_THRESHOLD' that divide and conquer is of use. 6772 6773 `DC_DIV_QR_THRESHOLD' is based on the divisor size N, so it will be 6774 somewhere above twice `MUL_TOOM22_THRESHOLD', but how much above 6775 depends on the CPU. An optimized `mpn_mul_basecase' can lower 6776 `DC_DIV_QR_THRESHOLD' a little by offering a ready-made advantage over 6777 repeated `mpn_submul_1' calls. 6778 6779 Divide and conquer is asymptotically O(M(N)*log(N)) where M(N) is 6780 the time for an NxN multiplication done with FFTs. The actual time is 6781 a sum over multiplications of the recursed sizes, as can be seen near 6782 the end of section 2.2 of Burnikel and Ziegler. For example, within 6783 the Toom-3 range, divide and conquer is 2.63*M(N). With higher 6784 algorithms the M(N) term improves and the multiplier tends to log(N). 6785 In practice, at moderate to large sizes, a 2NxN division is about 2 to 6786 4 times slower than an NxN multiplication. 6787 6788 6789 File: gmp.info, Node: Block-Wise Barrett Division, Next: Exact Division, Prev: Divide and Conquer Division, Up: Division Algorithms 6790 6791 16.2.4 Block-Wise Barrett Division 6792 ---------------------------------- 6793 6794 For the largest divisions, a block-wise Barrett division algorithm is 6795 used. Here, the divisor is inverted to a precision determined by the 6796 relative size of the dividend and divisor. Blocks of quotient limbs 6797 are then generated by multiplying blocks from the dividend by the 6798 inverse. 6799 6800 Our block-wise algorithm computes a smaller inverse than in the 6801 plain Barrett algorithm. For a 2n/n division, the inverse will be just 6802 ceil(n/2) limbs. 6803 6804 6805 File: gmp.info, Node: Exact Division, Next: Exact Remainder, Prev: Block-Wise Barrett Division, Up: Division Algorithms 6806 6807 16.2.5 Exact Division 6808 --------------------- 6809 6810 A so-called exact division is when the dividend is known to be an exact 6811 multiple of the divisor. Jebelean's exact division algorithm uses this 6812 knowledge to make some significant optimizations (*note References::). 6813 6814 The idea can be illustrated in decimal for example with 368154 6815 divided by 543. Because the low digit of the dividend is 4, the low 6816 digit of the quotient must be 8. This is arrived at from 4*7 mod 10, 6817 using the fact 7 is the modular inverse of 3 (the low digit of the 6818 divisor), since 3*7 == 1 mod 10. So 8*543=4344 can be subtracted from 6819 the dividend leaving 363810. Notice the low digit has become zero. 6820 6821 The procedure is repeated at the second digit, with the next 6822 quotient digit 7 (7 == 1*7 mod 10), subtracting 7*543=3801, leaving 6823 325800. And finally at the third digit with quotient digit 6 (8*7 mod 6824 10), subtracting 6*543=3258 leaving 0. So the quotient is 678. 6825 6826 Notice however that the multiplies and subtractions don't need to 6827 extend past the low three digits of the dividend, since that's enough 6828 to determine the three quotient digits. For the last quotient digit no 6829 subtraction is needed at all. On a 2NxN division like this one, only 6830 about half the work of a normal basecase division is necessary. 6831 6832 For an NxM exact division producing Q=N-M quotient limbs, the saving 6833 over a normal basecase division is in two parts. Firstly, each of the 6834 Q quotient limbs needs only one multiply, not a 2x1 divide and 6835 multiply. Secondly, the crossproducts are reduced when Q>M to 6836 Q*M-M*(M+1)/2, or when Q<=M to Q*(Q-1)/2. Notice the savings are 6837 complementary. If Q is big then many divisions are saved, or if Q is 6838 small then the crossproducts reduce to a small number. 6839 6840 The modular inverse used is calculated efficiently by `binvert_limb' 6841 in `gmp-impl.h'. This does four multiplies for a 32-bit limb, or six 6842 for a 64-bit limb. `tune/modlinv.c' has some alternate implementations 6843 that might suit processors better at bit twiddling than multiplying. 6844 6845 The sub-quadratic exact division described by Jebelean in "Exact 6846 Division with Karatsuba Complexity" is not currently implemented. It 6847 uses a rearrangement similar to the divide and conquer for normal 6848 division (*note Divide and Conquer Division::), but operating from low 6849 to high. A further possibility not currently implemented is 6850 "Bidirectional Exact Integer Division" by Krandick and Jebelean which 6851 forms quotient limbs from both the high and low ends of the dividend, 6852 and can halve once more the number of crossproducts needed in a 2NxN 6853 division. 6854 6855 A special case exact division by 3 exists in `mpn_divexact_by3', 6856 supporting Toom-3 multiplication and `mpq' canonicalizations. It forms 6857 quotient digits with a multiply by the modular inverse of 3 (which is 6858 `0xAA..AAB') and uses two comparisons to determine a borrow for the next 6859 limb. The multiplications don't need to be on the dependent chain, as 6860 long as the effect of the borrows is applied, which can help chips with 6861 pipelined multipliers. 6862 6863 6864 File: gmp.info, Node: Exact Remainder, Next: Small Quotient Division, Prev: Exact Division, Up: Division Algorithms 6865 6866 16.2.6 Exact Remainder 6867 ---------------------- 6868 6869 If the exact division algorithm is done with a full subtraction at each 6870 stage and the dividend isn't a multiple of the divisor, then low zero 6871 limbs are produced but with a remainder in the high limbs. For 6872 dividend a, divisor d, quotient q, and b = 2^mp_bits_per_limb, this 6873 remainder r is of the form 6874 6875 a = q*d + r*b^n 6876 6877 n represents the number of zero limbs produced by the subtractions, 6878 that being the number of limbs produced for q. r will be in the range 6879 0<=r<d and can be viewed as a remainder, but one shifted up by a factor 6880 of b^n. 6881 6882 Carrying out full subtractions at each stage means the same number 6883 of cross products must be done as a normal division, but there's still 6884 some single limb divisions saved. When d is a single limb some 6885 simplifications arise, providing good speedups on a number of 6886 processors. 6887 6888 `mpn_divexact_by3', `mpn_modexact_1_odd' and the `mpn_redc_X' 6889 functions differ subtly in how they return r, leading to some negations 6890 in the above formula, but all are essentially the same. 6891 6892 Clearly r is zero when a is a multiple of d, and this leads to 6893 divisibility or congruence tests which are potentially more efficient 6894 than a normal division. 6895 6896 The factor of b^n on r can be ignored in a GCD when d is odd, hence 6897 the use of `mpn_modexact_1_odd' by `mpn_gcd_1' and `mpz_kronecker_ui' 6898 etc (*note Greatest Common Divisor Algorithms::). 6899 6900 Montgomery's REDC method for modular multiplications uses operands 6901 of the form of x*b^-n and y*b^-n and on calculating (x*b^-n)*(y*b^-n) 6902 uses the factor of b^n in the exact remainder to reach a product in the 6903 same form (x*y)*b^-n (*note Modular Powering Algorithm::). 6904 6905 Notice that r generally gives no useful information about the 6906 ordinary remainder a mod d since b^n mod d could be anything. If 6907 however b^n == 1 mod d, then r is the negative of the ordinary 6908 remainder. This occurs whenever d is a factor of b^n-1, as for example 6909 with 3 in `mpn_divexact_by3'. For a 32 or 64 bit limb other such 6910 factors include 5, 17 and 257, but no particular use has been found for 6911 this. 6912 6913 6914 File: gmp.info, Node: Small Quotient Division, Prev: Exact Remainder, Up: Division Algorithms 6915 6916 16.2.7 Small Quotient Division 6917 ------------------------------ 6918 6919 An NxM division where the number of quotient limbs Q=N-M is small can 6920 be optimized somewhat. 6921 6922 An ordinary basecase division normalizes the divisor by shifting it 6923 to make the high bit set, shifting the dividend accordingly, and 6924 shifting the remainder back down at the end of the calculation. This 6925 is wasteful if only a few quotient limbs are to be formed. Instead a 6926 division of just the top 2*Q limbs of the dividend by the top Q limbs 6927 of the divisor can be used to form a trial quotient. This requires 6928 only those limbs normalized, not the whole of the divisor and dividend. 6929 6930 A multiply and subtract then applies the trial quotient to the M-Q 6931 unused limbs of the divisor and N-Q dividend limbs (which includes Q 6932 limbs remaining from the trial quotient division). The starting trial 6933 quotient can be 1 or 2 too big, but all cases of 2 too big and most 6934 cases of 1 too big are detected by first comparing the most significant 6935 limbs that will arise from the subtraction. An addback is done if the 6936 quotient still turns out to be 1 too big. 6937 6938 This whole procedure is essentially the same as one step of the 6939 basecase algorithm done in a Q limb base, though with the trial 6940 quotient test done only with the high limbs, not an entire Q limb 6941 "digit" product. The correctness of this weaker test can be 6942 established by following the argument of Knuth section 4.3.1 exercise 6943 20 but with the v2*q>b*r+u2 condition appropriately relaxed. 6944 6945 6946 File: gmp.info, Node: Greatest Common Divisor Algorithms, Next: Powering Algorithms, Prev: Division Algorithms, Up: Algorithms 6947 6948 16.3 Greatest Common Divisor 6949 ============================ 6950 6951 * Menu: 6952 6953 * Binary GCD:: 6954 * Lehmer's Algorithm:: 6955 * Subquadratic GCD:: 6956 * Extended GCD:: 6957 * Jacobi Symbol:: 6958 6959 6960 File: gmp.info, Node: Binary GCD, Next: Lehmer's Algorithm, Prev: Greatest Common Divisor Algorithms, Up: Greatest Common Divisor Algorithms 6961 6962 16.3.1 Binary GCD 6963 ----------------- 6964 6965 At small sizes GMP uses an O(N^2) binary style GCD. This is described 6966 in many textbooks, for example Knuth section 4.5.2 algorithm B. It 6967 simply consists of successively reducing odd operands a and b using 6968 6969 a,b = abs(a-b),min(a,b) 6970 strip factors of 2 from a 6971 6972 The Euclidean GCD algorithm, as per Knuth algorithms E and A, 6973 repeatedly computes the quotient q = floor(a/b) and replaces a,b by v, 6974 u - q v. The binary algorithm has so far been found to be faster than 6975 the Euclidean algorithm everywhere. One reason the binary method does 6976 well is that the implied quotient at each step is usually small, so 6977 often only one or two subtractions are needed to get the same effect as 6978 a division. Quotients 1, 2 and 3 for example occur 67.7% of the time, 6979 see Knuth section 4.5.3 Theorem E. 6980 6981 When the implied quotient is large, meaning b is much smaller than 6982 a, then a division is worthwhile. This is the basis for the initial a 6983 mod b reductions in `mpn_gcd' and `mpn_gcd_1' (the latter for both Nx1 6984 and 1x1 cases). But after that initial reduction, big quotients occur 6985 too rarely to make it worth checking for them. 6986 6987 6988 The final 1x1 GCD in `mpn_gcd_1' is done in the generic C code as 6989 described above. For two N-bit operands, the algorithm takes about 6990 0.68 iterations per bit. For optimum performance some attention needs 6991 to be paid to the way the factors of 2 are stripped from a. 6992 6993 Firstly it may be noted that in twos complement the number of low 6994 zero bits on a-b is the same as b-a, so counting or testing can begin on 6995 a-b without waiting for abs(a-b) to be determined. 6996 6997 A loop stripping low zero bits tends not to branch predict well, 6998 since the condition is data dependent. But on average there's only a 6999 few low zeros, so an option is to strip one or two bits arithmetically 7000 then loop for more (as done for AMD K6). Or use a lookup table to get 7001 a count for several bits then loop for more (as done for AMD K7). An 7002 alternative approach is to keep just one of a or b odd and iterate 7003 7004 a,b = abs(a-b), min(a,b) 7005 a = a/2 if even 7006 b = b/2 if even 7007 7008 This requires about 1.25 iterations per bit, but stripping of a 7009 single bit at each step avoids any branching. Repeating the bit strip 7010 reduces to about 0.9 iterations per bit, which may be a worthwhile 7011 tradeoff. 7012 7013 Generally with the above approaches a speed of perhaps 6 cycles per 7014 bit can be achieved, which is still not terribly fast with for instance 7015 a 64-bit GCD taking nearly 400 cycles. It's this sort of time which 7016 means it's not usually advantageous to combine a set of divisibility 7017 tests into a GCD. 7018 7019 Currently, the binary algorithm is used for GCD only when N < 3. 7020 7021 7022 File: gmp.info, Node: Lehmer's Algorithm, Next: Subquadratic GCD, Prev: Binary GCD, Up: Greatest Common Divisor Algorithms 7023 7024 16.3.2 Lehmer's algorithm 7025 ------------------------- 7026 7027 Lehmer's improvement of the Euclidean algorithms is based on the 7028 observation that the initial part of the quotient sequence depends only 7029 on the most significant parts of the inputs. The variant of Lehmer's 7030 algorithm used in GMP splits off the most significant two limbs, as 7031 suggested, e.g., in "A Double-Digit Lehmer-Euclid Algorithm" by 7032 Jebelean (*note References::). The quotients of two double-limb inputs 7033 are collected as a 2 by 2 matrix with single-limb elements. This is 7034 done by the function `mpn_hgcd2'. The resulting matrix is applied to 7035 the inputs using `mpn_mul_1' and `mpn_submul_1'. Each iteration usually 7036 reduces the inputs by almost one limb. In the rare case of a large 7037 quotient, no progress can be made by examining just the most 7038 significant two limbs, and the quotient is computed using plain 7039 division. 7040 7041 The resulting algorithm is asymptotically O(N^2), just as the 7042 Euclidean algorithm and the binary algorithm. The quadratic part of the 7043 work are the calls to `mpn_mul_1' and `mpn_submul_1'. For small sizes, 7044 the linear work is also significant. There are roughly N calls to the 7045 `mpn_hgcd2' function. This function uses a couple of important 7046 optimizations: 7047 7048 * It uses the same relaxed notion of correctness as `mpn_hgcd' (see 7049 next section). This means that when called with the most 7050 significant two limbs of two large numbers, the returned matrix 7051 does not always correspond exactly to the initial quotient 7052 sequence for the two large numbers; the final quotient may 7053 sometimes be one off. 7054 7055 * It takes advantage of the fact the quotients are usually small. 7056 The division operator is not used, since the corresponding 7057 assembler instruction is very slow on most architectures. (This 7058 code could probably be improved further, it uses many branches 7059 that are unfriendly to prediction). 7060 7061 * It switches from double-limb calculations to single-limb 7062 calculations half-way through, when the input numbers have been 7063 reduced in size from two limbs to one and a half. 7064 7065 7066 7067 7068 Local Variables: 7069 coding: iso-8859-1 7070 End: 7071
