MPIR The Multiple Precision Integers and Rationals Library Edition 1.0 8 April 2009 This manual describes how to install and use MPIR, the Multiple Precision Integers and Ratio- nals library, version 1.0. Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. Copyright 2008 William Hart Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being \A GNU Manual", and with the Back-Cover Texts being \You have freedom to copy and modify this GNU Manual, like GNU software". A copy of the license is included in Appendix C [GNU Free Documentation License], page 121. i Table of Contents MPIR Copying Conditions ................................. 1 1 Introduction to MPIR .................................. 2 1.1 How to use this Manual ........................................................ 2 2 Installing MPIR........................................ 3 2.1 Build Options ................................................................. 3 2.2 ABI and ISA.................................................................. 8 2.3 Notes for Package Builds ...................................................... 11 2.4 Notes for Particular Systems .................................................. 12 2.5 Known Build Problems ....................................................... 14 2.6 Performance optimization ..................................................... 15 3 MPIR Basics ......................................... 17 3.1 Headers and Libraries ........................................................ 17 3.2 Nomenclature and Types...................................................... 17 3.3 Function Classes ............................................................. 18 3.4 Variable Conventions ......................................................... 18 3.5 Parameter Conventions ....................................................... 19 3.6 Memory Management......................................................... 20 3.7 Reentrancy .................................................................. 20 3.8 Useful Macros and Constants.................................................. 21 3.9 Compatibility with older versions .............................................. 21 3.10 Demonstration programs ..................................................... 22 3.11 Efficiency ................................................................... 22 3.12 Debugging .................................................................. 24 3.13 Profiling .................................................................... 26 3.14 Autoconf ................................................................... 27 3.15 Emacs ...................................................................... 28 4 Reporting Bugs ....................................... 29 5 Integer Functions ..................................... 30 5.1 Initialization Functions ....................................................... 30 5.2 Assignment Functions ........................................................ 30 5.3 Combined Initialization and Assignment Functions .............................. 31 5.4 Conversion Functions ......................................................... 32 5.5 Arithmetic Functions ......................................................... 33 5.6 Division Functions............................................................ 33 5.7 Exponentiation Functions ..................................................... 35 5.8 Root Extraction Functions .................................................... 36 5.9 Number Theoretic Functions .................................................. 36 5.10 Comparison Functions ....................................................... 38 5.11 Logical and Bit Manipulation Functions....................................... 39 5.12 Input and Output Functions ................................................. 40 5.13 Random Number Functions .................................................. 41 ii MPIR 1.0 5.14 Integer Import and Export ................................................... 41 5.15 Miscellaneous Functions ..................................................... 43 5.16 Special Functions............................................................ 43 6 Rational Number Functions............................ 45 6.1 Initialization and Assignment Functions ........................................ 45 6.2 Conversion Functions ......................................................... 46 6.3 Arithmetic Functions ......................................................... 46 6.4 Comparison Functions ........................................................ 47 6.5 Applying Integer Functions to Rationals........................................ 47 6.6 Input and Output Functions .................................................. 48 7 Floating-point Functions ............................... 49 7.1 Initialization Functions ....................................................... 49 7.2 Assignment Functions ........................................................ 51 7.3 Combined Initialization and Assignment Functions .............................. 51 7.4 Conversion Functions ......................................................... 52 7.5 Arithmetic Functions ......................................................... 53 7.6 Comparison Functions ........................................................ 54 7.7 Input and Output Functions .................................................. 54 7.8 Miscellaneous Functions....................................................... 55 8 Low-level Functions ................................... 56 8.1 Nails ........................................................................ 62 9 Random Number Functions ............................ 64 9.1 Random State Initialization ................................................... 64 9.2 Random State Seeding ........................................................ 65 9.3 Random State Miscellaneous .................................................. 65 10 Formatted Output ................................... 66 10.1 Format Strings .............................................................. 66 10.2 Functions ................................................................... 68 10.3 C++ Formatted Output ...................................................... 69 11 Formatted Input ..................................... 71 11.1 Formatted Input Strings ..................................................... 71 11.2 Formatted Input Functions................................................... 72 11.3 C++ Formatted Input ........................................................ 73 12 C++ Class Interface ................................... 75 12.1 C++ Interface General ....................................................... 75 12.2 C++ Interface Integers ....................................................... 76 12.3 C++ Interface Rationals ...................................................... 77 12.4 C++ Interface Floats ......................................................... 79 12.5 C++ Interface Random Numbers .............................................. 80 12.6 C++ Interface Limitations .................................................... 81 13 Berkeley MP Compatible Functions ................... 83 iii 14 Custom Allocation ................................... 85 15 Language Bindings ................................... 87 16 Algorithms .......................................... 89 16.1 Multiplication............................................................... 89 16.1.1 Basecase Multiplication ................................................. 89 16.1.2 Karatsuba Multiplication ................................................ 90 16.1.3 Toom 3-Way Multiplication.............................................. 91 16.1.4 FFT Multiplication ..................................................... 92 16.1.5 Other Multiplication .................................................... 94 16.2 Division Algorithms ......................................................... 94 16.2.1 Single Limb Division .................................................... 94 16.2.2 Basecase Division ....................................................... 95 16.2.3 Divide and Conquer Division ............................................ 95 16.2.4 Exact Division.......................................................... 96 16.2.5 Exact Remainder ....................................................... 97 16.2.6 Small Quotient Division ................................................. 98 16.3 Greatest Common Divisor ................................................... 98 16.3.1 Binary GCD ........................................................... 98 16.3.2 Accelerated GCD ....................................................... 99 16.3.3 Extended GCD ......................................................... 99 16.3.4 Jacobi Symbol......................................................... 100 16.4 Powering Algorithms ....................................................... 100 16.4.1 Normal Powering ...................................................... 100 16.4.2 Modular Powering ..................................................... 100 16.5 Root Extraction Algorithms................................................. 100 16.5.1 Square Root..........................................................