MPIR The Multiple Precision Integers and Rationals Library Edition 3.0.0 18 February 2017 Original Authors: Torbjorn Granlund and the GMP Development Team Subsequent modifications: William Hart and the MPIR Team This manual describes how to install and use MPIR, the Multiple Precision Integers and Ratio- nals library, version 3.0.0. Copyright 1991, 1993-2016 Free Software Foundation, Inc. Copyright 2008, 2009, 2010 William Hart Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 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 148. 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 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 10 2.4 Building with Microsoft Visual Studio :::::::::::::::::::::::::::::::::::::::::::: 11 2.5 Notes for Particular Systems ::::::::::::::::::::::::::::::::::::::::::::::::::::: 13 2.6 Known Build Problems ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 14 2.7 Performance optimization :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 15 3 MPIR Basics ::::::::::::::::::::::::::::::::::::::::::::::::: 16 3.1 Headers and Libraries :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 16 3.2 Nomenclature and Types ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 16 3.3 MPIR on Windows x64::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 17 3.4 Function Classes ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 18 3.5 Variable Conventions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 18 3.6 Parameter Conventions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 19 3.7 Memory Management :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 20 3.8 Reentrancy::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 20 3.9 Useful Macros and Constants ::::::::::::::::::::::::::::::::::::::::::::::::::::: 20 3.10 Compatibility with older versions :::::::::::::::::::::::::::::::::::::::::::::::: 21 3.11 Efficiency ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 21 3.12 Debugging :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 23 3.13 Profiling :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 25 3.14 Autoconf:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 27 3.15 Emacs :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 27 4 Reporting Bugs::::::::::::::::::::::::::::::::::::::::::::::: 28 5 Integer Functions::::::::::::::::::::::::::::::::::::::::::::: 29 5.1 Initialization Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 29 5.2 Assignment Functions :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 30 5.3 Combined Initialization and Assignment Functions :::::::::::::::::::::::::::::::: 30 5.4 Conversion Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 31 5.5 Arithmetic Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 32 5.6 Division Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 33 5.7 Exponentiation Functions :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 35 5.8 Root Extraction Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 35 5.9 Number Theoretic Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::: 36 5.10 Comparison Functions::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 39 5.11 Logical and Bit Manipulation Functions ::::::::::::::::::::::::::::::::::::::::: 39 5.12 Input and Output Functions::::::::::::::::::::::::::::::::::::::::::::::::::::: 40 ii MPIR 3.0.0 5.13 Random Number Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::: 41 5.14 Integer Import and Export :::::::::::::::::::::::::::::::::::::::::::::::::::::: 41 5.15 Miscellaneous Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 43 5.16 Special Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 43 6 Rational Number Functions ::::::::::::::::::::::::::::::::: 46 6.1 Initialization and Assignment Functions :::::::::::::::::::::::::::::::::::::::::: 46 6.2 Conversion Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 47 6.3 Arithmetic Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 47 6.4 Comparison Functions :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 48 6.5 Applying Integer Functions to Rationals :::::::::::::::::::::::::::::::::::::::::: 48 6.6 Input and Output Functions :::::::::::::::::::::::::::::::::::::::::::::::::::::: 49 7 Floating-point Functions::::::::::::::::::::::::::::::::::::: 50 7.1 Initialization Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 50 7.2 Assignment Functions :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 52 7.3 Combined Initialization and Assignment Functions :::::::::::::::::::::::::::::::: 53 7.4 Conversion Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 53 7.5 Arithmetic Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 54 7.6 Comparison Functions :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 55 7.7 Input and Output Functions :::::::::::::::::::::::::::::::::::::::::::::::::::::: 55 7.8 Miscellaneous Functions :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 56 8 Low-level Functions :::::::::::::::::::::::::::::::::::::::::: 58 8.1 Nails ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 65 9 Random Number Functions ::::::::::::::::::::::::::::::::: 67 9.1 Random State Initialization :::::::::::::::::::::::::::::::::::::::::::::::::::::: 67 9.2 Random State Seeding ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 68 9.3 Random State Miscellaneous ::::::::::::::::::::::::::::::::::::::::::::::::::::: 68 10 Formatted Output :::::::::::::::::::::::::::::::::::::::::: 69 10.1 Format Strings :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 69 10.2 Functions ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 71 10.3 C++ Formatted Output::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 72 11 Formatted Input :::::::::::::::::::::::::::::::::::::::::::: 74 11.1 Formatted Input Strings::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 74 11.2 Formatted Input Functions :::::::::::::::::::::::::::::::::::::::::::::::::::::: 76 11.3 C++ Formatted Input :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 76 12 C++ Class Interface :::::::::::::::::::::::::::::::::::::::: 78 12.1 C++ Interface General :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 78 12.2 C++ Interface Integers :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 79 12.3 C++ Interface Rationals :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 80 12.4 C++ Interface Floats ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 82 12.5 C++ Interface Random Numbers:::::::::::::::::::::::::::::::::::::::::::::::: 84 12.6 C++ Interface Limitations :::::::::::::::::::::::::::::::::::::::::::::::::::::: 85 iii 13 .Net Interface ::::::::::::::::::::::::::::::::::::::::::::::: 87 13.1 MPIR.Net Feature Overview :::::::::::::::::::::::::::::::::::::::::::::::::::: 87 13.2 Building MPIR.Net ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 90 13.3 MPIR.Net Integers :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 91 13.4 MPIR.Net Rationals :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 97 13.5 MPIR.Net Floats :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 100 13.6 MPIR.Net Random Numbers ::::::::::::::::::::::::::::::::::::::::::::::::::: 104 13.7 MPIR.Net Settings::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 105 14 Custom Allocation::::::::::::::::::::::::::::::::::::::::: 106 15 Language Bindings :::::::::::::::::::::::::::::::::::::::: 108 16 Algorithms ::::::::::::::::::::::::::::::::::::::::::::::::: 111 16.1 Multiplication:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 111 16.1.1 Basecase Multiplication ::::::::::::::::::::::::::::::::::::::::::::::::::: 111 16.1.2 Karatsuba Multiplication :::::::::::::::::::::::::::::::::::::::::::::::::: 112 16.1.3 Toom 3-Way Multiplication ::::::::::::::::::::::::::::::::::::::::::::::: 113 16.1.4 Toom 4-Way Multiplication ::::::::::::::::::::::::::::::::::::::::::::::: 115 16.1.5 FFT Multiplication:::::::::::::::::::::::::::::::::::::::::::::::::::::::: 115 16.1.6 Other Multiplication :::::::::::::::::::::::::::::::::::::::::::::::::::::: 117 16.1.7 Unbalanced Multiplication::::::::::::::::::::::::::::::::::::::::::::::::: 117 16.2 Division Algorithms ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::