1.. _integer_reference: 2 3Multiprecision integers 4======================= 5 6*#include <mp++/integer.hpp>* 7 8The integer class 9----------------- 10 11.. cpp:class:: template <std::size_t SSize> mppp::integer 12 13 Multiprecision integer class. 14 15 This class represents arbitrary-precision signed integers. It acts as a wrapper around the GMP :cpp:type:`mpz_t` type, with 16 a small value optimisation: integers whose size is up to ``SSize`` limbs are stored directly in the storage 17 occupied by the :cpp:class:`~mppp::integer` object, without resorting to dynamic memory allocation. The value of 18 ``SSize`` must be at least 1 and less than an implementation-defined upper limit. On most modern architectures, 19 a limb contains either 32 or 64 bits of data. Thus, for instance, if ``SSize`` is set to 2 on a 64-bit system, 20 the small value optimisation will be employed for all integral values less than :math:`2^{64 \times 2} = 2^{128}`. 21 22 When the value of an :cpp:class:`~mppp::integer` is stored directly within the object, the *storage type* of the 23 integer is said to be *static*. When the limb size of the integer exceeds the maximum value ``SSize``, the storage 24 type becomes *dynamic*. The transition from static to dynamic storage happens transparently whenever the integer 25 value becomes large enough. The demotion from dynamic to static storage usually needs to be requested explicitly. 26 For values of ``SSize`` of 1 and 2, optimised implementations of basic arithmetic operations are employed, 27 if supported by the target architecture and if the storage type is static. For larger values of ``SSize``, 28 the ``mpn_`` low-level functions of the GMP API are used if the storage type is static. If the storage type is 29 dynamic, the usual ``mpz_`` functions from the GMP API are used. 30 31 Most of the functionality is exposed via plain :ref:`functions <integer_functions>`, with the 32 general convention that the functions are named after the corresponding GMP functions minus the leading ``mpz_`` 33 prefix. For instance, the GMP call 34 35 .. code-block:: c++ 36 37 mpz_add(rop,a,b); 38 39 that writes the result of ``a + b`` into ``rop`` becomes simply 40 41 .. code-block:: c++ 42 43 add(rop,a,b); 44 45 where the ``add()`` function is resolved via argument-dependent lookup. Function calls with overlapping arguments 46 are allowed, unless noted otherwise. Various :ref:`overloaded operators <integer_operators>` are also provided. 47 48 Several facilities for interfacing with the GMP library are provided. Specifically, :cpp:class:`~mppp::integer` 49 features: 50 51 * a constructor and an assignment operator from the GMP integer type :cpp:type:`mpz_t`, 52 * a :cpp:func:`~mppp::integer::get_mpz_t()` method that promotes ``this`` to dynamic 53 storage and returns a pointer to the internal :cpp:type:`mpz_t` instance, 54 * an :cpp:class:`mpz_view` class, an instance of which can be requested via the :cpp:func:`~mppp::integer::get_mpz_view()` 55 method, which allows to use :cpp:class:`~mppp::integer` in the GMP API as a drop-in replacement for 56 ``const`` :cpp:type:`mpz_t` function arguments. 57 58 The :cpp:class:`mpz_view` class represent a read-only view of an integer object which is implicitly convertible to the type 59 ``const`` :cpp:type:`mpz_t` and which is thus usable as an argument to GMP functions. For example: 60 61 .. code-block:: c++ 62 63 mpz_t m; 64 mpz_init_set_si(m,1); // Create an mpz_t with the value 1. 65 integer<1> n{1}; // Initialize an integer with the value 1. 66 mpz_add(m,m,n.get_mpz_view()); // Compute the result of n + m and store 67 // it in m using the GMP API. 68 69 See the documentation of :cpp:func:`~mppp::integer::get_mpz_view()` for more details about the :cpp:class:`mpz_view` class. 70 Via the GMP interfacing facilities, it is thus possible to use directly the GMP C API with 71 :cpp:class:`~mppp::integer` objects whenever necessary (e.g., if a GMP function has not been wrapped yet by mp++). 72 73 The :cpp:class:`~mppp::integer` class supports a simple binary serialisation API, through member functions 74 such as :cpp:func:`~mppp::integer::binary_save()` and :cpp:func:`~mppp::integer::binary_load()`, and the 75 corresponding :ref:`free function overloads <integer_s11n>`. 76 77 A :ref:`tutorial <tutorial_integer>` showcasing various features of :cpp:class:`~mppp::integer` 78 is available. 79 80 .. cpp:member:: static constexpr std::size_t ssize = SSize 81 82 Alias for the static size. 83 84 .. cpp:function:: integer() 85 86 Default constructor. 87 88 The default constructor initialises an integer with static storage type and value 0. 89 90 .. cpp:function:: integer(const integer &other) 91 92 Copy constructor. 93 94 The copy constructor deep-copies *other* into ``this``, copying the original 95 storage type as well. 96 97 :param other: the object that will be copied into ``this``. 98 99 .. cpp:function:: integer(integer &&other) noexcept 100 101 Move constructor. 102 103 The move constructor will leave *other* in an unspecified but valid state. 104 The storage type of ``this`` will be the same as *other*'s. 105 106 :param other: the object that will be moved into ``this``. 107 108 .. cpp:function:: explicit integer(const mp_limb_t *p, std::size_t size) 109 110 Constructor from an array of limbs. 111 112 This constructor will initialise ``this`` with the content of the array 113 sized *size* starting at *p*. The array is expected to contain 114 the limbs of the desired value for ``this``, ordered from the least significant 115 to the most significant. 116 117 For instance, the following code: 118 119 .. code-block:: c++ 120 121 mp_limb_t arr[] = {5,6,7}; 122 integer<1> n{arr, 3}; 123 124 will initialise ``n`` to the value :math:`5 + 6 \times 2^{N} + 7 \times 2^{2N}`, 125 where :math:`N` is the compile-time GMP constant ``GMP_NUMB_BITS`` representing the number of 126 value bits in a limb (typically 64 or 32, depending on the platform). 127 128 This constructor always initialises ``this`` to a non-negative value, 129 and it requires the most significant limb of *p* to be nonzero. It also requires 130 every member of the input array not to be greater than the ``GMP_NUMB_MAX`` GMP constant. 131 If *size* is zero, ``this`` will be initialised to zero without ever dereferencing *p*. 132 133 .. warning:: 134 135 The effects of this constructor are highly dependent on the platform 136 currently in use and also on the build configuration of the GMP library. 137 Do not use it for portable initialisation. 138 139 .. seealso:: 140 https://gmplib.org/manual/Low_002dlevel-Functions.html#Low_002dlevel-Functions 141 142 143 :param p: a pointer to the beginning of the limbs array. 144 :param size: the size of the limbs array. 145 146 :exception std\:\:invalid_argument: if the last element of the *p* array is zero, 147 or if at least one element of the *p* array is greater than ``GMP_NUMB_MAX``. 148 :exception std\:\:overflow_error: if *size* is larger than an implementation-defined limit. 149 150 .. cpp:function:: explicit integer(integer_bitcnt_t nbits) 151 152 Constructor from number of bits. 153 154 This constructor will initialise ``this`` to zero, allocating enough memory 155 to represent a value with a magnitude of *nbits* binary digits. The storage type 156 will be static if *nbits* is small enough, dynamic otherwise. For instance, the code 157 158 .. code-block:: c++ 159 160 integer n{integer_bitcnt_t(64)}; 161 162 will initialise an integer ``n`` with value zero and enough storage for a 64-bit value. 163 164 :param nbits: the number of bits of storage that will be allocated. 165 166 :exception std\:\:overflow_error: if the value of *nbits* is larger than an 167 implementation-defined limit. 168 169 .. cpp:function:: template <integer_cpp_arithmetic T> explicit integer(const T &x) 170 171 Generic constructor from arithmetic C++ types. 172 173 .. note:: 174 175 This constructor is not ``explicit`` if ``T`` satisfies :cpp:concept:`cpp_integral`. 176 177 This constructor will initialize an integer with the value of *x*. 178 The initialisation is always successful if *x* is an integral value 179 (construction from ``bool`` yields 1 for ``true``, 0 for ``false``). 180 If *x* is a floating-point value, the construction will fail if *x* 181 is not finite. Construction from a floating-point type yields the 182 truncated counterpart of the input value. 183 184 :param x: value that will be used to initialize ``this``. 185 186 :exception std\:\:domain_error: if *x* is a non-finite floating-point value. 187 188 .. cpp:function:: template <integer_cpp_complex T> explicit integer(const T &c) 189 190 .. versionadded:: 0.19 191 192 Generic constructor from complex C++ types. 193 194 This constructor will initialize an integer with the value of *c*. The initialisation is 195 successful only if the imaginary part of *c* is zero and the real part of *c* is finite. 196 197 :param c: value that will be used to initialize ``this``. 198 199 :exception std\:\:domain_error: if the imaginary part of *c* is not zero or if 200 the real part of *c* is not finite. 201 202 .. cpp:function:: template <string_type T> explicit integer(const T &s, int base = 10) 203 204 Constructor from string. 205 206 This constructor will initialize ``this`` from *s*, which must represent 207 an integer value in base *base*. The expected format is the same as specified by the ``mpz_set_str()`` 208 GMP function. *base* may vary from 2 to 62, or be zero. In the latter case, the base is inferred 209 from the leading characters of the string. 210 211 .. seealso:: 212 213 https://gmplib.org/manual/Assigning-Integers.html 214 215 :param s: the input string. 216 :param base: the base used in the string representation. 217 218 :exception std\:\:invalid_argument: if the *base* parameter is invalid or if *s* is not a 219 valid string representation of an integer in the specified base. 220 :exception unspecified: any exception thrown by memory allocation errors in 221 standard containers. 222 223 .. cpp:function:: explicit integer(const char *begin, const char *end, int base = 10) 224 225 Constructor from range of characters. 226 227 This constructor will initialise ``this`` from the content of the input half-open range, 228 which is interpreted as the string representation of an integer in base *base*. 229 230 Internally, the constructor will copy the content of the range to a local buffer, add a 231 string terminator, and invoke the constructor from string. 232 233 :param begin: the begin of the input range. 234 :param end: the end of the input range. 235 :param base: the base used in the string representation. 236 237 :exception unspecified: any exception thrown by the constructor from string, or by memory 238 allocation errors in standard containers. 239 240 .. cpp:function:: explicit integer(const mpz_t n) 241 242 Copy constructor from :cpp:type:`mpz_t`. 243 244 This constructor will initialize ``this`` with the value of the GMP integer *n*. 245 The storage type of ``this`` will be static if *n* fits in the static storage, 246 otherwise it will be dynamic. 247 248 .. warning:: 249 250 It is the user's responsibility to ensure that *n* has been correctly 251 initialized. Calling this constructor with an uninitialized *n* 252 results in undefined behaviour. 253 254 :param n: the input GMP integer. 255 256 .. cpp:function:: explicit integer(mpz_t &&n) 257 258 Move constructor from :cpp:type:`mpz_t`. 259 260 This constructor will initialize ``this`` with the value of the 261 GMP integer *n*, transferring the state of *n* into ``this``. 262 The storage type of ``this`` will be static if *n* fits in the 263 static storage, otherwise it will be dynamic. 264 265 .. warning:: 266 267 It is the user's responsibility to ensure that *n* has been 268 correctly initialized. Calling this constructor 269 with an uninitialized *n* results in undefined behaviour. 270 271 Additionally, the user must ensure that, after construction, 272 ``mpz_clear()`` is never called on *n*: the resources previously 273 owned by *n* are now owned by ``this``, which 274 will take care of releasing them when the destructor is called. 275 276 .. note:: 277 278 Due to a compiler bug, this constructor is not available on Microsoft Visual Studio. 279 280 :param n: the input GMP integer. 281 282 .. cpp:function:: integer &operator=(const integer &other) 283 284 Copy assignment operator. 285 286 This operator will perform a deep copy of *other*, copying its storage type as well. 287 288 :param other: the assignment argument. 289 290 :return: a reference to ``this``. 291 292 .. cpp:function:: integer &operator=(integer &&other) 293 294 Move assignment operator. 295 296 After the move, *other* will be in an unspecified but valid state, 297 and the storage type of ``this`` will be 298 *other*'s original storage type. 299 300 :param other: the assignment argument. 301 302 :return: a reference to ``this``. 303 304 .. cpp:function:: template <integer_cpp_arithmetic T> integer &operator=(const T &x) 305 306 Generic assignment operator from arithmetic C++ types. 307 308 This operator will assign *x* to ``this``. The storage type of ``this`` after the assignment 309 will depend only on the value of *x* (that is, the storage type will be static if the value of *x* 310 is small enough, dynamic otherwise). Assignment from floating-point types will assign the truncated 311 counterpart of *x*. 312 313 :param x: the assignment argument. 314 315 :return: a reference to ``this``. 316 317 :exception std\:\:domain_error: if *x* is a non-finite floating-point value. 318 319 .. cpp:function:: template <integer_cpp_complex T> integer &operator=(const T &c) 320 321 .. versionadded:: 0.19 322 323 Generic assignment operator from complex C++ types. 324 325 This operator will assign *c* to ``this``. The storage type of ``this`` after the assignment 326 will depend only on the value of *c* (that is, the storage type will be static if the value of *c* 327 is small enough, dynamic otherwise). The assignment will be successful only if 328 the imaginary part of *c* is zero and the real part of *c* is finite. 329 330 :param c: the assignment argument. 331 332 :return: a reference to ``this``. 333 334 :exception std\:\:domain_error: if the imaginary part of *c* is not zero or if 335 the real part of *c* is not finite. 336 337 .. cpp:function:: integer &operator=(const rational<SSize> &x) 338 .. cpp:function:: integer &operator=(const real128 &x) 339 .. cpp:function:: integer &operator=(const real &x) 340 .. cpp:function:: integer &operator=(const complex128 &x) 341 .. cpp:function:: integer &operator=(const complex &x) 342 343 .. note:: 344 345 The :cpp:class:`~mppp::real128` and :cpp:class:`~mppp::complex128` 346 overloads are available only if mp++ was configured with the ``MPPP_WITH_QUADMATH`` 347 option enabled. The :cpp:class:`~mppp::real` overload 348 is available only if mp++ was configured with the ``MPPP_WITH_MPFR`` option enabled. 349 The :cpp:class:`~mppp::complex` overload 350 is available only if mp++ was configured with the ``MPPP_WITH_MPC`` option enabled. 351 352 .. versionadded:: 0.20 353 354 Assignment operators from other mp++ classes. 355 356 These operators are formally equivalent to converting *x* to 357 :cpp:class:`~mppp::integer` and then move-assigning the result 358 to ``this``. 359 360 :param x: the assignment argument. 361 362 :return: a reference to ``this``. 363 364 :exception unspecified: any exception raised by the conversion of *x* 365 to :cpp:class:`~mppp::integer`. 366 367 .. cpp:function:: template <string_type T> integer &operator=(const T &s) 368 369 Assignment from string. 370 371 The body of this operator is equivalent to: 372 373 .. code-block:: c++ 374 375 return *this = integer{s}; 376 377 That is, a temporary integer is constructed from 378 *s* and it is then move-assigned to ``this``. 379 380 :param s: the string that will be used for the assignment. 381 382 :return: a reference to ``this``. 383 384 :exception unspecified: any exception thrown by the constructor from string. 385 386 .. cpp:function:: integer &operator=(const mpz_t n) 387 388 Copy assignment from :cpp:type:`mpz_t`. 389 390 This assignment operator will copy into ``this`` the value of the GMP integer *n*. 391 The storage type of ``this`` after the assignment will be static if *n* fits in 392 the static storage, otherwise it will be dynamic. 393 394 .. warning:: 395 396 It is the user's responsibility to ensure that *n* has been correctly initialized. Calling this operator 397 with an uninitialized *n* results in undefined behaviour. Also, no aliasing is allowed: the data in *n* 398 must be completely distinct from the data in ``this`` (e.g., if *n* is an :cpp:class:`~mppp::integer::mpz_view` 399 of ``this`` then it might point to internal data of ``this``, and the behaviour of this operator will thus be undefined). 400 401 :param n: the input GMP integer. 402 403 :return: a reference to ``this``. 404 405 .. cpp:function:: integer &operator=(mpz_t &&n) 406 407 Move assignment from :cpp:type:`mpz_t`. 408 409 This assignment operator will move into ``this`` the GMP integer *n*. The storage type of ``this`` 410 after the assignment will be static if *n* fits in the static storage, otherwise it will be dynamic. 411 412 .. warning:: 413 414 It is the user's responsibility to ensure that *n* has been correctly initialized. Calling this operator 415 with an uninitialized *n* results in undefined behaviour. Also, no aliasing is allowed: the data in *n* 416 must be completely distinct from the data in ``this`` (e.g., if *n* is an :cpp:class:`~mppp::integer::mpz_view` 417 of ``this`` then it might point to internal data of ``this``, and the behaviour of this operator will thus be undefined). 418 419 Additionally, the user must ensure that, after the assignment, ``mpz_clear()`` is never 420 called on *n*: the resources previously owned by *n* are now owned by ``this``, which 421 will take care of releasing them when the destructor is called. 422 423 .. note:: 424 425 Due to a compiler bug, this operator is not available on Microsoft Visual Studio. 426 427 :param n: the input GMP integer. 428 429 :return: a reference to ``this``. 430 431 .. cpp:function:: integer &set_zero() 432 .. cpp:function:: integer &set_one() 433 .. cpp:function:: integer &set_negative_one() 434 435 Set to :math:`0`, :math:`1` or :math:`-1`. 436 437 After calling these member functions, the storage type of ``this`` will be static. 438 439 .. note:: 440 441 These are specialised higher-performance alternatives to the assignment operators. 442 443 :return: a reference to ``this``. 444 445 .. cpp:function:: bool is_static() const 446 .. cpp:function:: bool is_dynamic() const 447 448 Query the storage type currently in use. 449 450 :return: ``true`` if the current storage type is static (resp. dynamic), 451 ``false`` otherwise. 452 453 .. cpp:function:: std::string to_string(int base = 10) const 454 455 Conversion to string. 456 457 This member function will convert ``this`` into a string in base *base* 458 using the GMP function ``mpz_get_str()``. 459 460 .. seealso:: 461 462 https://gmplib.org/manual/Converting-Integers.html 463 464 :param base: the desired base. 465 466 :return: a string representation of ``this``. 467 468 :exception std\:\:invalid_argument: if *base* is smaller than 2 or greater than 62. 469 470 .. cpp:function:: template <integer_cpp_arithmetic T> explicit operator T() const 471 472 Generic conversion operator to arithmetic C++ types. 473 474 This operator will convert ``this`` to ``T``. 475 Conversion to ``bool`` yields ``false`` if ``this`` is zero, 476 ``true`` otherwise. Conversion to other integral types yields the exact result, if representable by the target 477 type. Conversion to floating-point types might yield inexact values and 478 infinities. 479 480 :return: ``this`` converted to the target type. 481 482 :exception std\:\:overflow_error: if the target type is an integral type and the value of 483 ``this`` cannot be represented by it. 484 485 .. cpp:function:: template <integer_cpp_complex T> explicit operator T() const 486 487 .. versionadded:: 0.19 488 489 Generic conversion operator to complex C++ types. 490 491 This operator will convert ``this`` to ``T``. 492 The conversion might yield inexact values and infinities. 493 494 :return: ``this`` converted to the target type. 495 496 .. cpp:function:: template <integer_cpp_arithmetic T> bool get(T &rop) const 497 498 Generic conversion member function to arithmetic C++ types. 499 500 This member function, similarly to the conversion operator, will convert ``this`` 501 to ``T``, storing the result of the conversion into *rop*. Differently 502 from the conversion operator, this member function does not raise any exception: if the conversion is successful, 503 the member function will return ``true``, otherwise the member function will return ``false``. If the conversion 504 fails, *rop* will not be altered. 505 506 :param rop: the variable which will store the result of the conversion. 507 508 :return: ``true`` if the conversion succeeded, ``false`` otherwise. The conversion can fail only if ``T`` is 509 an integral C++ type which cannot represent the value of ``this``. 510 511 .. cpp:function:: template <integer_cpp_complex T> bool get(T &rop) const 512 513 .. versionadded:: 0.19 514 515 Generic conversion member function to complex C++ types. 516 517 This member function, similarly to the conversion operator, will convert ``this`` 518 to ``T``, storing the result of the conversion into *rop*. 519 The conversion is always successful, and this member function 520 will always return ``true``. 521 522 :param rop: the variable which will store the result of the conversion. 523 524 :return: ``true``. 525 526 .. cpp:function:: bool promote() 527 528 Promote to dynamic storage. 529 530 This member function will promote the storage type of ``this`` from static to dynamic. 531 532 :return: ``false`` if the storage type of ``this`` is already dynamic and no promotion 533 takes place, ``true`` otherwise. 534 535 .. cpp:function:: bool demote() 536 537 Demote to static storage. 538 539 This member function will demote the storage type of ``this`` from dynamic to static. 540 541 :return: ``false`` if the storage type of ``this`` is already static and no demotion 542 takes place, or if the current value of ``this`` does not fit in static storage, 543 ``true`` otherwise. 544 545 .. cpp:function:: std::size_t nbits() const 546 .. cpp:function:: std::size_t size() const 547 548 Size in bits or limbs. 549 550 :return: the number of bits/limbs needed to represent ``this``. If ``this`` 551 is zero, zero will be returned. 552 553 :exception std\:\:overflow_error: if the size in bits of ``this`` is 554 larger than an implementation-defined value. 555 556 .. cpp:function:: int sgn() const 557 558 Sign. 559 560 :return: :math:`0` if ``this`` is zero, :math:`1` if ``this`` is positive, 561 :math:`-1` if ``this`` is negative. 562 563 .. cpp:class:: mpz_view 564 565 Read-only view onto an :cpp:type:`mpz_t`. 566 567 This is a proxy class with an implicit conversion operator to a ``const`` pointer 568 to the ``struct`` underlying :cpp:type:`mpz_t`. Thus, objects of this class can be 569 passed as read-only parameters to GMP functions. 570 571 In addition to the implicit conversion operator, a ``get()`` member function 572 provides the same functionality (i.e., conversion to a ``const`` pointer 573 to the ``struct`` underlying :cpp:type:`mpz_t`). 574 575 Objects of this class can only be constructed by :cpp:func:`mppp::integer::get_mpz_view()`, 576 or move-constructed. All assignment operators are disabled. 577 578 .. cpp:function:: mpz_view get_mpz_view() const 579 580 Get a GMP-compatible read-only view of ``this``. 581 582 This member function will return an :cpp:class:`mpz_view` object containing 583 a read-only GMP-compatible representation of the value stored in ``this``. 584 That is, the return value of this function can be used in the GMP API 585 where a ``const`` :cpp:type:`mpz_t` parameter is expected. 586 587 .. warning:: 588 589 Because the returned object is a non-owning view of ``this``, 590 it is important to keep in mind the following facts in order 591 to avoid undefined behaviour at runtime: 592 593 * the returned object and the pointer returned by its conversion operator 594 might reference internal data belonging to ``this``, and they can 595 thus be safely used only during the lifetime of ``this``; 596 * the lifetime of the pointer returned by the conversion operator 597 of the returned object is tied to the lifetime of the 598 returned object itself (that is, if the :cpp:class:`mpz_view` object is 599 destroyed, 600 any pointer previously returned by its conversion operator becomes invalid); 601 * any modification to ``this`` will also invalidate the view and the pointer. 602 603 :return: an :cpp:class:`mpz_view` of ``this``. 604 605 .. cpp:function:: integer &neg() 606 607 Negate in-place. 608 609 This member function will set ``this`` to ``-this``. 610 611 :return: a reference to ``this``. 612 613 .. cpp:function:: integer &abs() 614 615 In-place absolute value. 616 617 This member function will set ``this`` to its absolute value. 618 619 :return: a reference to ``this``. 620 621 .. cpp:function:: integer &nextprime() 622 623 Compute next prime number in-place. 624 625 This member function will set ``this`` to the first prime number 626 greater than the current value. 627 628 :return: a reference to ``this``. 629 630 .. cpp:function:: int probab_prime_p(int reps = 25) const 631 632 Test primality. 633 634 This member function will run a series of probabilistic tests to determine if ``this`` is a prime number. 635 It will return 2 if ``this`` is definitely a prime, 1 if ``this`` is probably a prime and 0 if ``this`` 636 is definitely not-prime. 637 638 :param reps: the number of tests to run. 639 640 :return: an integer indicating if ``this`` is a prime. 641 642 :exception std\:\:invalid_argument: if *reps* is less than 1 or if ``this`` is negative. 643 644 .. cpp:function:: integer &sqrt() 645 646 Integer square root. 647 648 This member function will set ``this`` to its integer square root. 649 650 :return: a reference to ``this``. 651 652 :exception std\:\:domain_error: if ``this`` is negative. 653 654 .. cpp:function:: integer &sqr() 655 656 Integer squaring. 657 658 This member function will set ``this`` to its square. 659 660 :return: a reference to ``this``. 661 662 .. cpp:function:: bool odd_p() const 663 .. cpp:function:: bool even_p() const 664 665 Parity detection. 666 667 :return: ``true`` if ``this`` is odd (resp. even), ``false`` otherwise. 668 669 .. cpp:function:: std::remove_extent<mpz_t>::type *get_mpz_t() 670 671 Get a pointer to the dynamic storage. 672 673 This member function will first promote ``this`` to dynamic storage (if ``this`` is not already employing dynamic 674 storage), and it will then return a pointer to the internal :cpp:type:`mpz_t`. The returned pointer can be used 675 as an argument for the functions of the GMP API. 676 677 .. note:: 678 679 The returned pointer is a raw, non-owning pointer tied to the lifetime of ``this``. Calling 680 :cpp:func:`~mppp::integer::demote()` or 681 assigning an :cpp:class:`~mppp::integer` with static storage to ``this`` will invalidate the returned 682 pointer. 683 684 :return: a pointer to the internal GMP integer. 685 686 .. cpp:function:: bool is_zero() const 687 .. cpp:function:: bool is_one() const 688 .. cpp:function:: bool is_negative_one() const 689 690 Detect special values. 691 692 :return: ``true`` if ``this`` is :math:`0`, :math:`1` or :math:`-1` respectively, 693 ``false`` otherwise. 694 695 .. cpp:function:: std::size_t binary_size() const 696 697 Size of the serialised binary representation. 698 699 This member function will return a value representing the number of bytes necessary 700 to serialise ``this`` into a memory buffer in binary format via one of the available 701 :cpp:func:`~mppp::integer::binary_save()` overloads. The returned value 702 is platform-dependent. 703 704 :return: the number of bytes needed for the binary serialisation of ``this``. 705 706 :exception std\:\:overflow_error: if the size in limbs of ``this`` is larger than an 707 implementation-defined limit. 708 709 .. cpp:function:: std::size_t binary_save(char *dest) const 710 .. cpp:function:: std::size_t binary_save(std::vector<char> &dest) const 711 .. cpp:function:: template <std::size_t S> std::size_t binary_save(std::array<char, S> &dest) const 712 .. cpp:function:: std::size_t binary_save(std::ostream &dest) const 713 714 Serialise into a memory buffer or an output stream. 715 716 These member functions will write into *dest* a binary representation of ``this``. The serialised 717 representation produced by these member functions can be read back with one of the 718 :cpp:func:`~mppp::integer::binary_load()` overloads. 719 720 For the first overload, *dest* must point to a memory area whose size is at least equal to the value returned 721 by :cpp:func:`~mppp::integer::binary_size()`, otherwise the behaviour will be undefined. 722 *dest* does not have any special alignment requirements. 723 724 For the second overload, the size of *dest* must be at least equal to the value returned by 725 :cpp:func:`~mppp::integer::binary_size()`. If that is not the case, *dest* will be resized 726 to :cpp:func:`~mppp::integer::binary_size()`. 727 728 For the third overload, the size of *dest* must be at least equal to the value returned by 729 :cpp:func:`~mppp::integer::binary_size()`. If that is not the case, no data 730 will be written to *dest* and zero will be returned. 731 732 For the fourth overload, if the serialisation is successful (that is, no stream error state is ever detected 733 in *dest* after write 734 operations), then the binary size of ``this`` (that is, the number of bytes written into *dest*) will be 735 returned. Otherwise, zero will be returned. Note that a return value of zero does not necessarily imply that no 736 bytes were written into *dest*, just that an error occurred at some point during the serialisation process. 737 738 .. warning:: 739 740 The binary representation produced by these member functions is compiler, platform and architecture 741 specific, and it is subject to possible breaking changes in future versions of mp++. Thus, 742 it should not be used as an exchange format or for long-term data storage. 743 744 :param dest: the output buffer or stream. 745 746 :return: the number of bytes written into ``dest`` (i.e., the output of :cpp:func:`~mppp::integer::binary_size()`, 747 if the serialisation was successful). 748 749 :exception std\:\:overflow_error: in case of (unlikely) overflow errors. 750 :exception unspecified: any exception thrown by :cpp:func:`~mppp::integer::binary_size()`, by memory errors in 751 standard containers, or by the public interface of ``std::ostream``. 752 753 .. cpp:function:: std::size_t binary_load(const char *src) 754 .. cpp:function:: std::size_t binary_load(const std::vector<char> &src) 755 .. cpp:function:: template <std::size_t S> std::size_t binary_load(const std::array<char, S> &src) 756 .. cpp:function:: std::size_t binary_load(std::istream &src) 757 758 Deserialise from a memory buffer or an input stream. 759 760 These member functions will load into ``this`` the content of the memory buffer or input stream 761 *src*, which must contain the serialised representation of an :cpp:class:`~mppp::integer` 762 produced by one of the :cpp:func:`~mppp::integer::binary_save()` overloads. 763 764 For the first overload, *src* does not have any special alignment requirements. 765 766 For the second and third overloads, the serialised representation of the 767 :cpp:class:`~mppp::integer` must start at the beginning of *src*, 768 but it can end before the end of *src*. Data 769 past the end of the serialised representation of the :cpp:class:`~mppp::integer` 770 will be ignored. 771 772 For the fourth overload, the serialised representation of the :cpp:class:`~mppp::integer` 773 must start at 774 the current position of *src*, but *src* can contain other data before and after 775 the serialised :cpp:class:`~mppp::integer` value. Data 776 past the end of the serialised representation of the :cpp:class:`~mppp::integer` 777 will be ignored. If a stream error state is detected at any point of the deserialisation 778 process after a read operation, zero will be returned and ``this`` will not have been modified. 779 Note that a return value of zero does not necessarily imply that no 780 bytes were read from *src*, just that an error occurred at some point during the serialisation process. 781 782 .. warning:: 783 784 Although these member functions perform a few consistency checks on the data in *src*, 785 they cannot ensure complete safety against maliciously-crafted data. Users are 786 advised to use these member functions only with trusted data. 787 788 :param src: the source memory buffer or stream. 789 790 :return: the number of bytes read from *src* (that is, the output of :cpp:func:`~mppp::integer::binary_size()` 791 after the deserialisation into ``this`` has successfully completed). 792 793 :exception std\:\:overflow_error: in case of (unlikely) overflow errors. 794 :exception std\:\:invalid_argument: if invalid data is detected in *src*. 795 :exception unspecified: any exception thrown by memory errors in standard containers, 796 the public interface of ``std::istream``, or :cpp:func:`~mppp::integer::binary_size()`. 797 798Types 799----- 800 801.. cpp:type:: mpz_t 802 803 This is the type used by the GMP library to represent multiprecision integers. 804 It is defined as an array of size 1 of an unspecified structure. 805 806 .. seealso:: 807 808 https://gmplib.org/manual/Nomenclature-and-Types.html#Nomenclature-and-Types 809 810.. cpp:type:: mp_limb_t 811 812 This type is defined by the GMP library. It is used to represents a limb, that is, 813 the part of a multiprecision integer that fits in a single machine word. This is an 814 unsigned integral type, typically 64 or 32 bits wide. 815 816 .. seealso:: 817 818 https://gmplib.org/manual/Nomenclature-and-Types.html#Nomenclature-and-Types 819 820.. cpp:type:: mp_bitcnt_t 821 822 This type is defined by the GMP library. It is an unsigned integral type used to count bits in a multiprecision 823 number. 824 825 .. seealso:: 826 827 https://gmplib.org/manual/Nomenclature-and-Types.html#Nomenclature-and-Types 828 829.. cpp:enum-class:: mppp::integer_bitcnt_t : mp_bitcnt_t 830 831 A strongly-typed counterpart to :cpp:type:`mp_bitcnt_t`, used in the constructor of :cpp:class:`~mppp::integer` 832 from number of bits. 833 834Concepts 835-------- 836 837.. cpp:concept:: template <typename T> mppp::integer_cpp_arithmetic 838 839 This concept is satisfied if ``T`` is an arithmetic C++ type compatible with :cpp:class:`~mppp::integer`. 840 841 Specifically, this concept is equivalent to :cpp:concept:`~mppp::cpp_arithmetic` if mp++ 842 was built with the ``MPPP_WITH_MPFR`` option enabled (see the :ref:`installation instructions <installation>`). 843 Otherwise, this concept is equivalent to :cpp:concept:`~mppp::cpp_arithmetic` minus the ``long double`` type. 844 845.. cpp:concept:: template <typename T> mppp::integer_cpp_complex 846 847 This concept is satisfied if ``T`` is a complex C++ type compatible with :cpp:class:`~mppp::integer`. 848 849 Specifically, this concept is equivalent to :cpp:concept:`~mppp::cpp_complex` if mp++ 850 was built with the ``MPPP_WITH_MPFR`` option enabled (see the :ref:`installation instructions <installation>`). 851 Otherwise, this concept is equivalent to :cpp:concept:`~mppp::cpp_complex` minus the 852 ``std::complex<long double>`` type. 853 854.. cpp:concept:: template <typename T, typename U> mppp::integer_op_types 855 856 This concept is satisfied if the types ``T`` and ``U`` are suitable for use in the 857 generic binary :ref:`operators <integer_operators>` and :ref:`functions <integer_functions>` 858 involving :cpp:class:`~mppp::integer`. Specifically, the concept will be ``true`` if either: 859 860 * ``T`` and ``U`` are both :cpp:class:`~mppp::integer` with the same static size ``SSize``, or 861 * one type is an :cpp:class:`~mppp::integer` and the other is an :cpp:concept:`~mppp::integer_cpp_arithmetic` 862 or an :cpp:concept:`~mppp::integer_cpp_complex` type. 863 864 Note that the modulo, bit-shifting and bitwise logic operators have additional restrictions. 865 866.. cpp:concept:: template <typename T, typename U> mppp::integer_real_op_types 867 868 This concept will be ``true`` if: 869 870 * ``T`` and ``U`` satisfy :cpp:concept:`~mppp::integer_op_types`, and 871 * neither ``T`` nor ``U`` satisfy :cpp:concept:`~mppp::integer_cpp_complex`. 872 873.. cpp:concept:: template <typename T, typename U> mppp::integer_integral_op_types 874 875 This concept is satisfied if the types ``T`` and ``U`` are suitable for use in the 876 generic binary :ref:`operators <integer_operators>` and :ref:`functions <integer_functions>` 877 involving :cpp:class:`~mppp::integer` and integral C++ types. Specifically, the concept will be ``true`` 878 if either: 879 880 * ``T`` and ``U`` are both :cpp:class:`~mppp::integer` with the same static size, or 881 * one type is an :cpp:class:`~mppp::integer` and the other is a :cpp:concept:`~mppp::cpp_integral` type. 882 883.. _integer_functions: 884 885Functions 886--------- 887 888Much of the functionality of the :cpp:class:`~mppp::integer` class 889is exposed via plain functions. These functions 890mimic the `GMP API <https://gmplib.org/manual/Integer-Functions.html>`__ where appropriate, but a variety of 891convenience/generic overloads is provided as well. 892 893.. _integer_assignment: 894 895Assignment 896~~~~~~~~~~ 897 898.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::set_zero(mppp::integer<SSize> &n) 899.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::set_one(mppp::integer<SSize> &n) 900.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::set_negative_one(mppp::integer<SSize> &n) 901 902 Set to :math:`0`, :math:`1` or :math:`-1`. 903 904 After calling these functions, the storage type of *n* will be static and its value will be 905 :math:`0`, :math:`1` or :math:`-1`. 906 907 .. note:: 908 909 These are specialised higher-performance alternatives to the assignment operators. 910 911 :param n: the argument. 912 913 :return: a reference to *n*. 914 915.. cpp:function:: template <std::size_t SSize> void mppp::swap(mppp::integer<SSize> &n1, mppp::integer<SSize> &n2) noexcept 916 917 .. versionadded:: 0.15 918 919 Swap. 920 921 This function will efficiently swap the values of *n1* and *n2*. 922 923 :param n1: the first argument. 924 :param n2: the second argument. 925 926.. _integer_conversion: 927 928Conversion 929~~~~~~~~~~ 930 931.. cpp:function:: template <mppp::integer_cpp_arithmetic T, std::size_t SSize> bool mppp::get(T &rop, const mppp::integer<SSize> &n) 932 933 Generic conversion function from :cpp:class:`~mppp::integer` to arithmetic C++ types. 934 935 This function will convert the input :cpp:class:`~mppp::integer` *n* to ``T``, 936 storing the result of the conversion into *rop*. 937 If the conversion is successful, the function 938 will return ``true``, otherwise the function will return ``false``. If the conversion fails, *rop* will 939 not be altered. 940 941 :param rop: the variable which will store the result of the conversion. 942 :param n: the input :cpp:class:`~mppp::integer`. 943 944 :return: ``true`` if the conversion succeeded, ``false`` otherwise. The conversion can fail only if ``T`` is 945 an integral C++ type which cannot represent the value of *n*. 946 947.. cpp:function:: template <mppp::integer_cpp_complex T, std::size_t SSize> bool mppp::get(T &rop, const mppp::integer<SSize> &n) 948 949 .. versionadded:: 0.19 950 951 Generic conversion function from :cpp:class:`~mppp::integer` to complex C++ types. 952 953 This function will convert the input :cpp:class:`~mppp::integer` *n* to ``T``, 954 storing the result of the conversion into *rop*. 955 The conversion is always successful, and this function will always return ``true``. 956 957 :param rop: the variable which will store the result of the conversion. 958 :param n: the input :cpp:class:`~mppp::integer`. 959 960 :return: ``true``. 961 962.. _integer_arithmetic: 963 964Arithmetic 965~~~~~~~~~~ 966 967.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::add(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const mppp::integer<SSize> &y) 968.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::sub(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const mppp::integer<SSize> &y) 969.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::mul(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const mppp::integer<SSize> &y) 970 971 Ternary arithmetic primitives. 972 973 These functions will set *rop* to, respectively: 974 975 * :math:`x + y`, 976 * :math:`x - y`, 977 * :math:`x \times y`. 978 979 :param rop: the return value. 980 :param x: the first operand. 981 :param y: the second operand. 982 983 :return: a reference to *rop*. 984 985.. cpp:function:: template <std::size_t SSize, mppp::cpp_unsigned_integral T> mppp::integer<SSize> &mppp::add_ui(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const T &y) 986.. cpp:function:: template <std::size_t SSize, mppp::cpp_signed_integral T> mppp::integer<SSize> &mppp::add_si(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const T &y) 987.. cpp:function:: template <std::size_t SSize, mppp::cpp_unsigned_integral T> mppp::integer<SSize> &mppp::sub_ui(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const T &y) 988.. cpp:function:: template <std::size_t SSize, mppp::cpp_signed_integral T> mppp::integer<SSize> &mppp::sub_si(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const T &y) 989 990 Ternary addition/subtraction primitives with integral C++ types. 991 992 These functions, which will set *rop* to :math:`x \pm y`, can be faster 993 alternatives to the :cpp:class:`~mppp::integer` addition function 994 if *y* fits in a single limb. 995 996 :param rop: the return value. 997 :param x: the first operand. 998 :param y: the second operand. 999 1000 :return: a reference to *rop*. 1001 1002.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::addmul(mppp::integer<SSize> &z, const mppp::integer<SSize> &x, const mppp::integer<SSize> &y) 1003.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::submul(mppp::integer<SSize> &z, const mppp::integer<SSize> &x, const mppp::integer<SSize> &y) 1004 1005 Ternary fused multiply-add/sub. 1006 1007 These functions will set *z* to :math:`z \pm x \times y`. 1008 1009 :param z: the return value. 1010 :param x: the first argument. 1011 :param y: the second argument. 1012 1013 :return: a reference to *z*. 1014 1015.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::mul_2exp(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n, mp_bitcnt_t s) 1016 1017 Ternary left shift. 1018 1019 This function will set *rop* to :math:`n\times 2^s`. 1020 1021 :param rop: the return value. 1022 :param n: the multiplicand. 1023 :param s: the bit shift value. 1024 1025 :return: a reference to *rop*. 1026 1027 :exception std\:\:overflow_error: if *s* is larger than an implementation-defined limit. 1028 1029.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::sqr(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n) 1030 1031 .. versionadded:: 0.18 1032 1033 Binary squaring. 1034 1035 This function will set *rop* to the square of *n*. 1036 1037 :param rop: the return value. 1038 :param n: the argument. 1039 1040 :return: a reference to *rop*. 1041 1042.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::sqr(const mppp::integer<SSize> &n) 1043 1044 .. versionadded:: 0.18 1045 1046 Unary squaring. 1047 1048 This function will return the square of *n*. 1049 1050 :param n: the argument. 1051 1052 :return: the square of *n*. 1053 1054.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::sqrm(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n, const mppp::integer<SSize> &mod) 1055 1056 .. versionadded:: 0.18 1057 1058 Ternary modular squaring. 1059 1060 This function will set *rop* to the square of *n* modulo *mod*. 1061 1062 :param rop: the return value. 1063 :param n: the argument. 1064 :param mod: the modulus. 1065 1066 :return: a reference to *rop*. 1067 1068 :exception mppp\:\:zero_division_error: if *mod* is zero. 1069 1070.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::sqrm(const mppp::integer<SSize> &n, const mppp::integer<SSize> &mod) 1071 1072 .. versionadded:: 0.18 1073 1074 Binary modular squaring. 1075 1076 This function will return the square of *n* modulo *mod*. 1077 1078 :param n: the argument. 1079 :param mod: the modulus. 1080 1081 :return: the square of *n* modulo *mod*. 1082 :exception mppp\:\:zero_division_error: if *mod* is zero. 1083 1084.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::neg(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n) 1085.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::abs(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n) 1086 1087 Binary negation and absolute value. 1088 1089 These functions will set *rop* to, respectively, :math:`-n` and :math:`\left| n \right|`. 1090 1091 :param rop: the return value. 1092 :param n: the input argument. 1093 1094 :return: a reference to *rop*. 1095 1096.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::neg(const mppp::integer<SSize> &n) 1097.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::abs(const mppp::integer<SSize> &n) 1098 1099 Unary negation and absolute value. 1100 1101 :param n: the input argument. 1102 1103 :return: :math:`-n` and :math:`\left| n \right|` respectively. 1104 1105.. _integer_division: 1106 1107Division 1108~~~~~~~~ 1109 1110.. cpp:function:: template <std::size_t SSize> void mppp::tdiv_qr(mppp::integer<SSize> &q, mppp::integer<SSize> &r, const mppp::integer<SSize> &n, const mppp::integer<SSize> &d) 1111 1112 Truncated division with remainder. 1113 1114 This function will set *q* to the truncated quotient, :math:`n \operatorname{div} d`, and *r* to 1115 the remainder, :math:`n \bmod d`. The remainder *r* has the same sign as *n*. *q* and *r* must be 1116 distinct objects. 1117 1118 :param q: the quotient. 1119 :param r: the remainder. 1120 :param n: the dividend. 1121 :param d: the divisor. 1122 1123 :exception std\:\:invalid_argument: if *q* and *r* are the same object. 1124 :exception mppp\:\:zero_division_error: if *d* is zero. 1125 1126.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::tdiv_q(mppp::integer<SSize> &q, const mppp::integer<SSize> &n, const mppp::integer<SSize> &d) 1127 1128 Truncated division without remainder. 1129 1130 This function will set *q* to the truncated quotient, :math:`n \operatorname{div} d`. 1131 1132 :param q: the quotient. 1133 :param n: the dividend. 1134 :param d: the divisor. 1135 1136 :return: a reference to *q*. 1137 1138 :exception mppp\:\:zero_division_error: if *d* is zero. 1139 1140.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::divexact(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n, const mppp::integer<SSize> &d) 1141.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::divexact_gcd(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n, const mppp::integer<SSize> &d) 1142 1143 Ternary exact divisions. 1144 1145 These functions will set *rop* to the quotient :math:`\frac{n}{d}`. 1146 1147 .. warning:: 1148 1149 Both functions require *d* to divide *n* **exactly**. ``divexact_gcd()`` 1150 additionally requires *d* to be positive. 1151 1152 :param rop: the return value. 1153 :param n: the dividend. 1154 :param d: the divisor. 1155 1156 :return: a reference to *rop*. 1157 1158.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::divexact(const mppp::integer<SSize> &n, const mppp::integer<SSize> &d) 1159.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::divexact_gcd(const mppp::integer<SSize> &n, const mppp::integer<SSize> &d) 1160 1161 Binary exact divisions. 1162 1163 These functions will return the quotient :math:`\frac{n}{d}`. 1164 1165 .. warning:: 1166 1167 Both functions require *d* to divide *n* **exactly**. ``divexact_gcd()`` 1168 additionally requires *d* to be positive. 1169 1170 :param n: the dividend. 1171 :param d: the divisor. 1172 1173 :return: :math:`\frac{n}{d}`. 1174 1175.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::tdiv_q_2exp(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n, mp_bitcnt_t s) 1176 1177 Ternary right shift. 1178 1179 This function will set *rop* to the truncated quotient :math:`n \operatorname{div} 2^s`. 1180 1181 :param rop: the return value. 1182 :param n: the dividend. 1183 :param s: the bit shift value. 1184 1185 :return: a reference to *rop*. 1186 1187.. _integer_comparison: 1188 1189Comparison 1190~~~~~~~~~~ 1191 1192.. cpp:function:: template <std::size_t SSize> int mppp::cmp(const mppp::integer<SSize> &x, const mppp::integer<SSize> &y) 1193 1194 Three-way comparison. 1195 1196 :param x: the first operand. 1197 :param y: the second operand. 1198 1199 :return: 0 if :math:`x = y`, a negative value if :math:`x<y`, a positive value if 1200 :math:`x>y`. 1201 1202.. cpp:function:: template <std::size_t SSize> int mppp::sgn(const mppp::integer<SSize> &n) 1203 1204 Sign function. 1205 1206 :param n: the input argument. 1207 1208 :return: 0 if *n* is zero, 1 if *n* is positive, -1 if *n* is negative. 1209 1210.. cpp:function:: template <std::size_t SSize> bool mppp::odd_p(const mppp::integer<SSize> &n) 1211.. cpp:function:: template <std::size_t SSize> bool mppp::even_p(const mppp::integer<SSize> &n) 1212 1213 Parity detection. 1214 1215 :param n: the input argument. 1216 1217 :return: ``true`` if *n* is odd (resp. even), ``false`` otherwise. 1218 1219.. cpp:function:: template <std::size_t SSize> bool mppp::is_zero(const mppp::integer<SSize> &n) 1220.. cpp:function:: template <std::size_t SSize> bool mppp::is_one(const mppp::integer<SSize> &n) 1221.. cpp:function:: template <std::size_t SSize> bool mppp::is_negative_one(const mppp::integer<SSize> &n) 1222 1223 Detect special values. 1224 1225 :param n: the input argument. 1226 1227 :return: ``true`` if *n* is equal to :math:`0`, :math:`1` or :math:`-1` respectively, 1228 ``false`` otherwise. 1229 1230.. _integer_logic: 1231 1232Logic and bit fiddling 1233~~~~~~~~~~~~~~~~~~~~~~ 1234 1235.. versionadded:: 0.6 1236 1237.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::bitwise_not(mppp::integer<SSize> &rop, const mppp::integer<SSize> &op) 1238 1239 Bitwise NOT. 1240 1241 This function will set *rop* to the bitwise NOT (i.e., the one's complement) of *op*. Negative operands 1242 are treated as-if they were represented using two's complement. 1243 1244 :param rop: the return value. 1245 :param op: the operand. 1246 1247 :return: a reference to *rop*. 1248 1249.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::bitwise_ior(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const mppp::integer<SSize> &y) 1250.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::bitwise_and(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const mppp::integer<SSize> &y) 1251.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::bitwise_xor(mppp::integer<SSize> &rop, const mppp::integer<SSize> &x, const mppp::integer<SSize> &y) 1252 1253 Binary bitwise operations. 1254 1255 These functions will set *rop* to, respectively the bitwise OR, AND and XOR of :math:`x` and :math:`y`. 1256 Negative operands are treated as-if they were represented using two's complement. 1257 1258 :param rop: the return value. 1259 :param x: the first operand. 1260 :param y: the second operand. 1261 1262 :return: a reference to *rop*. 1263 1264.. _integer_ntheory: 1265 1266Number theoretic functions 1267~~~~~~~~~~~~~~~~~~~~~~~~~~ 1268 1269.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::gcd(mppp::integer<SSize> &rop, const mppp::integer<SSize> &op1, const mppp::integer<SSize> &op2) 1270.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::lcm(mppp::integer<SSize> &rop, const mppp::integer<SSize> &op1, const mppp::integer<SSize> &op2) 1271 1272 Ternary GCD and LCM. 1273 1274 These functions will set *rop* to, respectively, the GCD and LCM of *op1* and *op2*. The result is always nonnegative. 1275 If both operands are zero, *rop* is set to zero. 1276 1277 .. versionadded:: 0.21 1278 1279 The ``lcm()`` function. 1280 1281 :param rop: the return value. 1282 :param op1: the first operand. 1283 :param op2: the second operand. 1284 1285 :return: a reference to *rop*. 1286 1287.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::gcd(const mppp::integer<SSize> &op1, const mppp::integer<SSize> &op2) 1288.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::lcm(const mppp::integer<SSize> &op1, const mppp::integer<SSize> &op2) 1289 1290 Binary GCD and LCM. 1291 1292 These functions will return, respectively, the GCD and LCM of *op1* and *op2*. The result is always nonnegative. 1293 If both operands are zero, zero is returned. 1294 1295 .. versionadded:: 0.21 1296 1297 The ``lcm()`` function. 1298 1299 :param op1: the first operand. 1300 :param op2: the second operand. 1301 1302 :return: the GCD or LCM of *op1* and *op2*. 1303 1304.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::fac_ui(mppp::integer<SSize> &rop, unsigned long n) 1305 1306 Factorial. 1307 1308 This function will set *rop* to :math:`n!`. 1309 1310 :param rop: the return value. 1311 :param n: the operand. 1312 1313 :return: a reference to *rop*. 1314 1315 :exception std\:\:invalid_argument: if *n* is larger than an implementation-defined limit. 1316 1317.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::bin_ui(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n, unsigned long k) 1318 1319 Ternary binomial coefficient. 1320 1321 This function will set *rop* to :math:`{n \choose k}`. Negative values of *n* are 1322 supported. 1323 1324 :param rop: the return value. 1325 :param n: the top argument. 1326 :param k: the bottom argument. 1327 1328 :return: a reference to *rop*. 1329 1330.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::bin_ui(const mppp::integer<SSize> &n, unsigned long k) 1331 1332 Binary binomial coefficient. 1333 1334 :param n: the top argument. 1335 :param k: the bottom argument. 1336 1337 :return: :math:`{n \choose k}`. 1338 1339.. cpp:function:: template <typename T, mppp::integer_integral_op_types<T> U> auto mppp::binomial(const T &n, const U &k) 1340 1341 Generic binomial coefficient. 1342 1343 This function will compute the binomial coefficient :math:`{{n}\choose{k}}`, supporting integral input values. 1344 The implementation can handle positive and negative values for both the top and the bottom argument. 1345 1346 The return type is always :cpp:class:`~mppp::integer`. 1347 1348 .. seealso:: 1349 1350 https://arxiv.org/abs/1105.3689/ 1351 1352 :param n: the top argument. 1353 :param k: the bottom argument. 1354 1355 :return: :math:`{n \choose k}`. 1356 1357 :exception std\:\:overflow_error: if *k* is outside an implementation-defined range. 1358 1359.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::nextprime(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n) 1360 1361 Compute next prime number (binary version). 1362 1363 This function will set *rop* to the first prime number greater than *n*. 1364 Note that for negative values of *n* this function always sets *rop* to :math:`2`. 1365 1366 :param rop: the return value. 1367 :param n: the input argument. 1368 1369 :return: a reference to *rop*. 1370 1371.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::nextprime(const mppp::integer<SSize> &n) 1372 1373 Compute next prime number (unary version). 1374 1375 For negative values of *n* this function always returns :math:`2`. 1376 1377 :param n: the input argument. 1378 1379 :return: the first prime number greater than *n*. 1380 1381.. cpp:function:: template <std::size_t SSize> int mppp::probab_prime_p(const mppp::integer<SSize> &n, int reps = 25) 1382 1383 Primality test. 1384 1385 This is the free-function version of :cpp:func:`mppp::integer::probab_prime_p()`. 1386 1387 :param n: the integer whose primality will be tested. 1388 :param reps: the number of tests to run. 1389 1390 :return: an integer indicating if *n* is a prime. 1391 1392 :exception unspecified: any exception thrown by :cpp:func:`mppp::integer::probab_prime_p()`. 1393 1394.. _integer_exponentiation: 1395 1396Exponentiation 1397~~~~~~~~~~~~~~ 1398 1399.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::pow_ui(mppp::integer<SSize> &rop, const mppp::integer<SSize> &base, unsigned long exp) 1400 1401 Ternary integral exponentiation. 1402 1403 This function will set *rop* to ``base**exp``. 1404 1405 :param rop: the return value. 1406 :param base: the base. 1407 :param exp: the exponent. 1408 1409 :return: a reference to *rop*. 1410 1411.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::pow_ui(const mppp::integer<SSize> &base, unsigned long exp) 1412 1413 Binary integral exponentiation. 1414 1415 :param base: the base. 1416 :param exp: the exponent. 1417 1418 :return: ``base**exp``. 1419 1420.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> auto mppp::pow(const T &base, const U &exp) 1421 1422 Generic binary exponentiation. 1423 1424 This function will raise *base* to the power *exp*, and return the result. If one of the arguments 1425 is a floating-point or complex value, then the result will be computed via ``std::pow()`` and it will 1426 also be a floating-point or complex value. Otherwise, the result will be an :cpp:class:`~mppp::integer`. 1427 In case of a negative integral exponent and integral base, the result will be zero unless 1428 the absolute value of ``base`` is 1. 1429 1430 :param base: the base. 1431 :param exp: the exponent. 1432 1433 :return: ``base**exp``. 1434 1435 :exception std\:\:overflow_error: if *base* and *exp* are integrals and *exp* is non-negative and outside the range 1436 of ``unsigned long``. 1437 :exception mppp\:\:zero_division_error: if *base* and *exp* are integrals and *base* is zero and *exp* is negative. 1438 1439.. _integer_roots: 1440 1441Roots 1442~~~~~ 1443 1444.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::sqrt(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n) 1445 1446 Binary square root. 1447 1448 This function will set *rop* to the truncated integer part of the square root of *n*. 1449 1450 :param rop: the return value. 1451 :param n: the argument. 1452 1453 :return: a reference to *rop*. 1454 1455 :exception std\:\:domain_error: if *n* is negative. 1456 1457.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::sqrt(const mppp::integer<SSize> &n) 1458 1459 Unary square root. 1460 1461 This function will return the truncated integer part of the square root of *n*. 1462 1463 :param n: the argument. 1464 1465 :return: the integer square root of *n*. 1466 1467 :exception std\:\:domain_error: if *n* is negative. 1468 1469.. cpp:function:: template <std::size_t SSize> void mppp::sqrtrem(mppp::integer<SSize> &rop, mppp::integer<SSize> &rem, const mppp::integer<SSize> &n) 1470 1471 .. versionadded:: 0.12 1472 1473 Square root with remainder. 1474 1475 This function will set *rop* to the truncated integer part of the square root of *n*, and *rem* to the remainder of the operation. 1476 That is, *rem* will be equal to ``n-rop*rop``, and it will be zero if *n* is a perfect square. 1477 1478 *rop* and *rem* must be distinct objects. 1479 1480 :param rop: the first return value (i.e., the integer square root of *n*). 1481 :param rem: the second return value (i.e., the remainder of the operation). 1482 :param n: the argument. 1483 1484 :exception std\:\:domain_error: if *n* is negative. 1485 :exception std\:\:invalid_argument: if *rop* and *rem* are the same object. 1486 1487.. cpp:function:: template <std::size_t SSize> bool mppp::perfect_square_p(const mppp::integer<SSize> &n) 1488 1489 .. versionadded:: 0.12 1490 1491 Detect perfect square. 1492 1493 This function returns ``true`` if *n* is a perfect square, ``false`` otherwise. 1494 1495 :param n: the argument. 1496 1497 :return: ``true`` if *n* is a perfect square, ``false`` otherwise. 1498 1499.. cpp:function:: template <std::size_t SSize> bool mppp::root(mppp::integer<SSize> &rop, const mppp::integer<SSize> &n, unsigned long m) 1500 1501 .. versionadded:: 0.12 1502 1503 Ternary :math:`m`-th root. 1504 1505 This function will set *rop* to the truncated integer part of the :math:`m`-th root of *n*. The return value will be ``true`` if the 1506 computation is exact, ``false`` otherwise. 1507 1508 :param rop: the return value. 1509 :param n: the argument. 1510 :param m: the degree of the root. 1511 1512 :return: ``true`` if the computation is exact, ``false`` otherwise. 1513 1514 :exception std\:\:domain_error: if *m* is even and *n* is negative, or if *m* is zero. 1515 1516.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::root(const mppp::integer<SSize> &n, unsigned long m) 1517 1518 .. versionadded:: 0.12 1519 1520 Binary :math:`m`-th root. 1521 1522 This function will return the truncated integer part of the :math:`m`-th root of *n*. 1523 1524 :param n: the argument. 1525 :param m: the degree of the root. 1526 1527 :return: the truncated integer part of the :math:`m`-th root of *n*. 1528 1529 :exception std\:\:domain_error: if *m* is even and *n* is negative, or if *m* is zero. 1530 1531.. cpp:function:: template <std::size_t SSize> void mppp::rootrem(mppp::integer<SSize> &rop, mppp::integer<SSize> &rem, const mppp::integer<SSize> &n, unsigned long m) 1532 1533 .. versionadded:: 0.12 1534 1535 :math:`m`-th root with remainder. 1536 1537 This function will set *rop* to the truncated integer part of the :math:`m`-th root of *n*, and *rem* to the remainder 1538 of the operation. That is, *rem* will be equal to ``n-rop**m``, and it will be zero if *n* is a perfect power. 1539 1540 :param rop: the first return value (i.e., the :math:`m`-th root root of *n*). 1541 :param rem: the second return value (i.e., the remainder of the operation). 1542 :param n: the argument. 1543 :param m: the degree of the root. 1544 1545 :exception std\:\:domain_error: if *m* is even and *n* is negative, or if *m* is zero. 1546 1547.. cpp:function:: template <std::size_t SSize> bool mppp::perfect_power_p(const mppp::integer<SSize> &n) 1548 1549 .. versionadded:: 0.12 1550 1551 Detect perfect power. 1552 1553 This function will return ``true`` if *n* is a perfect power, that is, if there exist integers :math:`a` and :math:`b`, 1554 with :math:`b>1`, such that *n* equals :math:`a^b`. Otherwise, the function will return ``false``. 1555 1556 :param n: the argument. 1557 1558 :return: ``true`` if *n* is a perfect power, ``false`` otherwise. 1559 1560.. _integer_io: 1561 1562Input/Output 1563~~~~~~~~~~~~ 1564 1565.. cpp:function:: template <std::size_t SSize> std::ostream &mppp::operator<<(std::ostream &os, const mppp::integer<SSize> &n) 1566 1567 Stream insertion operator. 1568 1569 This function will direct to the output stream *os* the input :cpp:class:`~mppp::integer` *n*. 1570 1571 :param os: the output stream. 1572 :param n: the input :cpp:class:`~mppp::integer`. 1573 1574 :return: a reference to *os*. 1575 1576 :exception std\:\:overflow_error: in case of (unlikely) overflow errors. 1577 :exception unspecified: any exception raised by the public interface of ``std::ostream`` or by memory allocation errors. 1578 1579.. _integer_s11n: 1580 1581Serialisation 1582~~~~~~~~~~~~~ 1583 1584.. versionadded:: 0.7 1585 1586.. cpp:function:: template <std::size_t SSize> std::size_t mppp::binary_size(const mppp::integer<SSize> &n) 1587 1588 Binary size. 1589 1590 This function is the free function equivalent of the 1591 :cpp:func:`mppp::integer::binary_size()` member function. 1592 1593 :param n: the input argument. 1594 1595 :return: the output of :cpp:func:`mppp::integer::binary_size()` called on *n*. 1596 1597 :exception unspecified: any exception thrown by :cpp:func:`mppp::integer::binary_size()`. 1598 1599.. cpp:function:: template <std::size_t SSize, typename T> std::size_t mppp::binary_save(const mppp::integer<SSize> &n, T &&dest) 1600 1601 Binary serialisation. 1602 1603 .. note:: 1604 1605 This function participates in overload resolution only if the expression 1606 1607 .. code-block:: c++ 1608 1609 return n.binary_save(std::forward<T>(dest)); 1610 1611 is well-formed. 1612 1613 This function is the free function equivalent of the 1614 :cpp:func:`mppp::integer::binary_save()` overloads. 1615 1616 :param n: the input argument. 1617 :param dest: the object into which *n* will be serialised. 1618 1619 :return: the output of the invoked :cpp:func:`mppp::integer::binary_save()` 1620 overload called on *n* with *dest* as argument. 1621 1622 :exception unspecified: any exception thrown by the invoked :cpp:func:`mppp::integer::binary_save()` overload. 1623 1624.. cpp:function:: template <std::size_t SSize, typename T> std::size_t mppp::binary_load(mppp::integer<SSize> &n, T &&src) 1625 1626 Binary deserialisation. 1627 1628 .. note:: 1629 1630 This function participates in overload resolution only if the expression 1631 1632 .. code-block:: c++ 1633 1634 return n.binary_load(std::forward<T>(src)); 1635 1636 is well-formed. 1637 1638 This function is the free function equivalent of the 1639 :cpp:func:`mppp::integer::binary_load()` overloads. 1640 1641 :param n: the output argument. 1642 :param src: the object containing the serialised :cpp:class:`~mppp::integer` 1643 that will be loaded into *n*. 1644 1645 :return: the output of the invoked :cpp:func:`mppp::integer::binary_load()` 1646 overload called on *n* with *src* as argument. 1647 1648 :exception unspecified: any exception thrown by the invoked :cpp:func:`mppp::integer::binary_load()` overload. 1649 1650.. _integer_other: 1651 1652Other 1653~~~~~ 1654 1655.. cpp:function:: template <std::size_t SSize> std::size_t mppp::hash(const mppp::integer<SSize> &n) 1656 1657 Hash value. 1658 1659 This function will return a hash value for *n*. The hash value depends only on the value of *n* 1660 (and *not* on its storage type). 1661 1662 A :ref:`specialisation <integer_std_specialisations>` of the standard ``std::hash`` functor is also provided, so that 1663 it is possible to use :cpp:class:`~mppp::integer` in standard unordered associative containers out of the box. 1664 1665 :param n: the input value. 1666 1667 :return: a hash value for *n*. 1668 1669.. cpp:function:: void mppp::free_integer_caches() 1670 1671 Free the :cpp:class:`~mppp::integer` caches. 1672 1673 On some platforms, :cpp:class:`~mppp::integer` manages thread-local caches 1674 to speed-up the allocation/deallocation of small objects. These caches are automatically 1675 freed on program shutdown or when a thread exits. In certain situations, however, 1676 it may be desirable to manually free the memory in use by the caches before 1677 the program's end or a thread's exit. This function does exactly that. 1678 1679 On platforms where thread local storage is not supported, this funcion will be a no-op. 1680 1681 It is safe to call this function concurrently from different threads. 1682 1683.. _integer_operators: 1684 1685Mathematical operators 1686---------------------- 1687 1688Overloaded operators are provided for convenience. 1689Their interface is generic, and their implementation 1690is typically built on top of basic :ref:`functions <integer_functions>`. 1691 1692.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::operator+(const mppp::integer<SSize> &n) 1693.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::operator-(const mppp::integer<SSize> &n) 1694 1695 Identity and negation operators. 1696 1697 :param n: the input argument. 1698 1699 :return: :math:`n` and :math:`-n` respectively. 1700 1701.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> auto mppp::operator+(const T &x, const U &y) 1702.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> auto mppp::operator-(const T &x, const U &y) 1703.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> auto mppp::operator*(const T &x, const U &y) 1704.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> auto mppp::operator/(const T &x, const U &y) 1705 1706 Binary arithmetic operators. 1707 1708 These operators will return, respectively: 1709 1710 * :math:`x+y`, 1711 * :math:`x-y`, 1712 * :math:`x \times y`, 1713 * :math:`x \operatorname{div} y`. 1714 1715 The return type is determined as follows: 1716 1717 * if the non-:cpp:class:`~mppp::integer` argument is a floating-point or complex value, then the 1718 type of the result is floating-point or complex; otherwise, 1719 * the type of the result is :cpp:class:`~mppp::integer`. 1720 1721 :param x: the first operand. 1722 :param y: the second operand. 1723 1724 :return: the result of the arithmetic operation. 1725 1726 :exception mppp\:\:zero_division_error: if, in a division, *y* is zero and only integral 1727 types are involved. 1728 1729.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> T &mppp::operator+=(T &x, const U &y) 1730.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> T &mppp::operator-=(T &x, const U &y) 1731.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> T &mppp::operator*=(T &x, const U &y) 1732.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> T &mppp::operator/=(T &x, const U &y) 1733 1734 In-place arithmetic operators. 1735 1736 These operators will set *x* to, respectively: 1737 1738 * :math:`x+y`, 1739 * :math:`x-y`, 1740 * :math:`x \times y`, 1741 * :math:`x \operatorname{div} y`. 1742 1743 :param x: the first operand. 1744 :param y: the second operand. 1745 1746 :return: a reference to *x*. 1747 1748 :exception mppp\:\:zero_division_error: if, in a division, *y* is zero and only integral 1749 types are involved. 1750 :exception unspecified: any exception thrown by the assignment/conversion operators 1751 of :cpp:class:`~mppp::integer`. 1752 1753.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::operator++(mppp::integer<SSize> &n) 1754.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> &mppp::operator--(mppp::integer<SSize> &n) 1755 1756 Prefix increment/decrement. 1757 1758 :param n: the input argument. 1759 1760 :return: a reference to *n* after the increment/decrement. 1761 1762.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::operator++(mppp::integer<SSize> &n, int) 1763.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::operator--(mppp::integer<SSize> &n, int) 1764 1765 Suffix increment/decrement. 1766 1767 :param n: the input argument. 1768 1769 :return: a copy of *n* before the increment/decrement. 1770 1771.. cpp:function:: template <typename T, mppp::integer_integral_op_types<T> U> auto mppp::operator%(const T &n, const U &d) 1772 1773 Binary modulo operator. 1774 1775 The return type is always :cpp:class:`~mppp::integer`. 1776 1777 :param n: the dividend. 1778 :param d: the divisor. 1779 1780 :return: :math:`n \bmod d`. 1781 1782 :exception mppp\:\:zero_division_error: if *d* is zero. 1783 1784.. cpp:function:: template <typename T, mppp::integer_integral_op_types<T> U> T &mppp::operator%=(T &rop, const U &op) 1785 1786 In-place modulo operator. 1787 1788 :param rop: the dividend. 1789 :param op: the divisor. 1790 1791 :return: a reference to *rop*. 1792 1793 :exception mppp\:\:zero_division_error: if *op* is zero. 1794 :exception unspecified: any exception thrown by the conversion operator of :cpp:class:`~mppp::integer`. 1795 1796.. cpp:function:: template <mppp::cpp_integral T, std::size_t SSize> mppp::integer<SSize> mppp::operator<<(const mppp::integer<SSize> &n, T s) 1797.. cpp:function:: template <mppp::cpp_integral T, std::size_t SSize> mppp::integer<SSize> mppp::operator>>(const mppp::integer<SSize> &n, T s) 1798 1799 Binary left/right shift operators. 1800 1801 :param n: the multiplicand/dividend. 1802 :param s: the bit shift value. 1803 1804 :return: :math:`n \times 2^s` and :math:`n \operatorname{div} 2^s` respectively. 1805 1806 :exception std\:\:overflow_error: if *s* is negative or larger than an implementation-defined value. 1807 1808.. cpp:function:: template <mppp::cpp_integral T, std::size_t SSize> mppp::integer<SSize> &mppp::operator<<=(mppp::integer<SSize> &rop, T s) 1809.. cpp:function:: template <mppp::cpp_integral T, std::size_t SSize> mppp::integer<SSize> &mppp::operator>>=(mppp::integer<SSize> &rop, T s) 1810 1811 In-place left/right shift operators. 1812 1813 :param rop: the multiplicand/dividend. 1814 :param s: the bit shift value. 1815 1816 :return: a reference to *rop*. 1817 1818 :exception std\:\:overflow_error: if *s* is negative or larger than an implementation-defined value. 1819 1820.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> bool mppp::operator==(const T &op1, const U &op2) 1821.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> bool mppp::operator!=(const T &op1, const U &op2) 1822.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> bool mppp::operator<(const T &op1, const U &op2) 1823.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> bool mppp::operator<=(const T &op1, const U &op2) 1824.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> bool mppp::operator>(const T &op1, const U &op2) 1825.. cpp:function:: template <typename T, mppp::integer_op_types<T> U> bool mppp::operator>=(const T &op1, const U &op2) 1826 1827 Binary comparison operators. 1828 1829 :param op1: first argument. 1830 :param op2: second argument. 1831 1832 :return: the result of the comparison. 1833 1834.. cpp:function:: template <std::size_t SSize> mppp::integer<SSize> mppp::operator~(const mppp::integer<SSize> &op) 1835 1836 Unary bitwise NOT. 1837 1838 This operator returns the bitwise NOT (i.e., the one's complement) of *op*. Negative operands 1839 are treated as-if they were represented using two's complement. 1840 1841 :param op: the operand. 1842 1843 :return: the bitwise NOT of *op*. 1844 1845.. cpp:function:: template <typename T, mppp::integer_integral_op_types<T> U> auto mppp::operator|(const T &op1, const U &op2) 1846.. cpp:function:: template <typename T, mppp::integer_integral_op_types<T> U> auto mppp::operator&(const T &op1, const U &op2) 1847.. cpp:function:: template <typename T, mppp::integer_integral_op_types<T> U> auto mppp::operator^(const T &op1, const U &op2) 1848 1849 Binary bitwise operators. 1850 1851 These operators will return, respectively: 1852 1853 * the bitwise OR, 1854 * the bitwise AND, 1855 * the bitwise XOR, 1856 1857 of *op1* and *op2*. 1858 1859 Negative operands are treated as-if they were represented using two's complement. 1860 1861 The return type is always :cpp:class:`~mppp::integer`. 1862 1863 :param op1: the first operand. 1864 :param op2: the second operand. 1865 1866 :return: the result of the bitwise operation. 1867 1868.. cpp:function:: template <typename T, mppp::integer_integral_op_types<T> U> T &mppp::operator|=(T &rop, const U &op) 1869.. cpp:function:: template <typename T, mppp::integer_integral_op_types<T> U> T &mppp::operator&=(T &rop, const U &op) 1870.. cpp:function:: template <typename T, mppp::integer_integral_op_types<T> U> T &mppp::operator^=(T &rop, const U &op) 1871 1872 In-place bitwise operators. 1873 1874 These operators will set *rop* to, respectively: 1875 1876 * the bitwise OR, 1877 * the bitwise AND, 1878 * the bitwise XOR, 1879 1880 of *rop* and *op*. 1881 1882 Negative operands are treated as-if they were represented using two's complement. 1883 1884 :param rop: the first operand. 1885 :param op: the second operand. 1886 1887 :return: a reference to *rop*. 1888 1889 :exception unspecified: any exception thrown by the conversion operator of :cpp:class:`~mppp::integer`. 1890 1891.. _integer_std_specialisations: 1892 1893Standard library specialisations 1894-------------------------------- 1895 1896.. cpp:class:: template <std::size_t SSize> std::hash<mppp::integer<SSize>> 1897 1898 Specialisation of ``std::hash`` for :cpp:class:`mppp::integer`. 1899 1900 .. cpp:type:: public argument_type = mppp::integer<SSize> 1901 .. cpp:type:: public result_type = std::size_t 1902 1903 .. note:: 1904 1905 The :cpp:type:`argument_type` and :cpp:type:`result_type` type aliases are defined only until C++14. 1906 1907 .. cpp:function:: public std::size_t operator()(const mppp::integer<SSize> &n) const 1908 1909 :param n: the input :cpp:class:`mppp::integer`. 1910 1911 :return: a hash value for *n*. 1912 1913.. _integer_literals: 1914 1915User-defined literals 1916--------------------- 1917 1918.. versionadded:: 0.18 1919 1920.. cpp:function:: template <char... Chars> mppp::integer<1> mppp::literals::operator"" _z1() 1921.. cpp:function:: template <char... Chars> mppp::integer<2> mppp::literals::operator"" _z2() 1922.. cpp:function:: template <char... Chars> mppp::integer<3> mppp::literals::operator"" _z3() 1923 1924 User-defined integer literals. 1925 1926 These numeric literal operator templates can be used to construct 1927 :cpp:class:`~mppp::integer` instances with, respectively, 1, 2 and 3 1928 limbs of static storage. Literals in binary, octal, decimal and 1929 hexadecimal format are supported. 1930 1931 .. seealso:: 1932 1933 https://en.cppreference.com/w/cpp/language/integer_literal 1934 1935 :exception std\:\:invalid_argument: if the input sequence of characters is not 1936 a valid integer literal (as defined by the C++ standard). 1937