fileserver/lib/Botan-3.2.0/doc/api_ref/bigint.rst

BigInt
========================================

``BigInt`` is Botan's implementation of a multiple-precision integer. Thanks to
C++'s operator overloading features, using ``BigInt`` is often quite similar to
using a native integer type. The number of functions related to ``BigInt`` is
quite large, and not all of them are documented here. You can find the complete
declarations in ``botan/bigint.h`` and ``botan/numthry.h``.

.. cpp:class:: BigInt

   .. cpp:function:: BigInt()

      Create a BigInt with value zero

   .. cpp:function:: BigInt(uint64_t n)

      Create a BigInt with value *n*

   .. cpp:function:: BigInt(const std::string& str)

      Create a BigInt from a string. By default decimal is expected. With an 0x
      prefix instead it is treated as hexadecimal.

   .. cpp:function:: BigInt(const uint8_t buf[], size_t length)

      Create a BigInt from a binary array (big-endian encoding).

   .. cpp:function:: BigInt(RandomNumberGenerator& rng, size_t bits, bool set_high_bit = true)

      Create a random BigInt of the specified size.

   .. cpp:function:: BigInt operator+(const BigInt& x, const BigInt& y)

      Add ``x`` and ``y`` and return result.

   .. cpp:function:: BigInt operator+(const BigInt& x, word y)

      Add ``x`` and ``y`` and return result.

   .. cpp:function:: BigInt operator+(word x, const BigInt& y)

      Add ``x`` and ``y`` and return result.

   .. cpp:function:: BigInt operator-(const BigInt& x, const BigInt& y)

      Subtract ``y`` from ``x`` and return result.

   .. cpp:function:: BigInt operator-(const BigInt& x, word y)

      Subtract ``y`` from ``x`` and return result.

   .. cpp:function:: BigInt operator*(const BigInt& x, const BigInt& y)

      Multiply ``x`` and ``y`` and return result.

   .. cpp:function:: BigInt operator/(const BigInt& x, const BigInt& y)

      Divide ``x`` by ``y`` and return result.

   .. cpp:function:: BigInt operator%(const BigInt& x, const BigInt& y)

      Divide ``x`` by ``y`` and return remainder.

   .. cpp:function:: word operator%(const BigInt& x, word y)

      Divide ``x`` by ``y`` and return remainder.

   .. cpp:function:: word operator<<(const BigInt& x, size_t n)

      Left shift ``x`` by ``n`` and return result.

   .. cpp:function:: word operator>>(const BigInt& x, size_t n)

      Right shift ``x`` by ``n`` and return result.

   .. cpp:function:: BigInt& operator+=(const BigInt& y)

      Add y to ``*this``

   .. cpp:function:: BigInt& operator+=(word y)

      Add y to ``*this``

   .. cpp:function:: BigInt& operator-=(const BigInt& y)

      Subtract y from ``*this``

   .. cpp:function:: BigInt& operator-=(word y)

      Subtract y from ``*this``

   .. cpp:function:: BigInt& operator*=(const BigInt& y)

      Multiply ``*this`` with y

   .. cpp:function:: BigInt& operator*=(word y)

      Multiply ``*this`` with y

   .. cpp:function:: BigInt& operator/=(const BigInt& y)

      Divide ``*this`` by y

   .. cpp:function:: BigInt& operator%=(const BigInt& y)

      Divide ``*this`` by y and set ``*this`` to the remainder.

   .. cpp:function:: word operator%=(word y)

      Divide ``*this`` by y and set ``*this`` to the remainder.

   .. cpp:function:: word operator<<=(size_t shift)

      Left shift ``*this`` by *shift* bits

   .. cpp:function:: word operator>>=(size_t shift)

      Right shift ``*this`` by *shift* bits

   .. cpp:function:: BigInt& operator++()

      Increment ``*this`` by 1

   .. cpp:function:: BigInt& operator--()

      Decrement ``*this`` by 1

   .. cpp:function:: BigInt operator++(int)

      Postfix increment ``*this`` by 1

   .. cpp:function:: BigInt operator--(int)

      Postfix decrement ``*this`` by 1

   .. cpp:function:: BigInt operator-() const

      Negation operator

   .. cpp:function:: bool operator !() const

      Return true unless ``*this`` is zero

   .. cpp:function:: void clear()

      Set ``*this`` to zero

   .. cpp:function:: size_t bytes() const

      Return number of bytes need to represent value of ``*this``

   .. cpp:function:: size_t bits() const

      Return number of bits need to represent value of ``*this``

   .. cpp:function:: bool is_even() const

      Return true if ``*this`` is even

   .. cpp:function:: bool is_odd() const

      Return true if ``*this`` is odd

   .. cpp:function:: bool is_nonzero() const

      Return true if ``*this`` is not zero

   .. cpp:function:: bool is_zero() const

      Return true if ``*this`` is zero

   .. cpp:function:: void set_bit(size_t n)

      Set bit *n* of ``*this``

   .. cpp:function:: void clear_bit(size_t n)

      Clear bit *n* of ``*this``

   .. cpp:function:: bool get_bit(size_t n) const

      Get bit *n* of ``*this``

   .. cpp:function:: uint32_t to_u32bit() const

      Return value of ``*this`` as a 32-bit integer, if possible.
      If the integer is negative or not in range, an exception is thrown.

   .. cpp:function:: bool is_negative() const

      Return true if ``*this`` is negative

   .. cpp:function:: bool is_positive() const

      Return true if ``*this`` is negative

   .. cpp:function:: BigInt abs() const

      Return absolute value of ``*this``

   .. cpp:function:: void binary_encode(uint8_t buf[]) const

      Encode this BigInt as a big-endian integer. The sign is ignored.

   .. cpp:function:: void binary_encode(uint8_t buf[], size_t len) const

      Encode this BigInt as a big-endian integer. The sign is ignored.
      If ``len`` is less than ``bytes()`` then only the low ``len``
      bytes are output. If ``len`` is greater than ``bytes()`` then
      the output is padded with leading zeros.

   .. cpp:function:: void binary_decode(uint8_t buf[])

      Decode this BigInt as a big-endian integer.

   .. cpp:function:: std::string to_dec_string() const

      Encode the integer as a decimal string.

   .. cpp:function:: std::string to_hex_string() const

      Encode the integer as a hexadecimal string.

Number Theory
----------------------------------------

Number theoretic functions available include:

.. cpp:function:: BigInt gcd(BigInt x, BigInt y)

  Returns the greatest common divisor of x and y

.. cpp:function:: BigInt lcm(BigInt x, BigInt y)

  Returns an integer z which is the smallest integer such that z % x
  == 0 and z % y == 0

.. cpp:function:: BigInt jacobi(BigInt a, BigInt n)

  Return Jacobi symbol of (a|n).

.. cpp:function:: BigInt inverse_mod(BigInt x, BigInt m)

  Returns the modular inverse of x modulo m, that is, an integer
  y such that (x*y) % m == 1. If no such y exists, returns zero.

.. cpp:function:: BigInt power_mod(BigInt b, BigInt x, BigInt m)

  Returns b to the xth power modulo m. If you are doing many
  exponentiations with a single fixed modulus, it is faster to use a
  ``Power_Mod`` implementation.

.. cpp:function:: BigInt ressol(BigInt x, BigInt p)

  Returns the square root modulo a prime, that is, returns a number y
  such that (y*y) % p == x. Returns -1 if no such integer exists.

.. cpp:function:: bool is_prime(BigInt n, RandomNumberGenerator& rng, \
                                size_t prob = 56, double is_random = false)

  Test *n* for primality using a probabilistic algorithm (Miller-Rabin).  With
  this algorithm, there is some non-zero probability that true will be returned
  even if *n* is actually composite. Modifying *prob* allows you to decrease the
  chance of such a false positive, at the cost of increased runtime. Sufficient
  tests will be run such that the chance *n* is composite is no more than 1 in
  2\ :sup:`prob`. Set *is_random* to true if (and only if) *n* was randomly
  chosen (ie, there is no danger it was chosen maliciously) as far fewer tests
  are needed in that case.

.. cpp:function:: BigInt random_prime(RandomNumberGenerator& rng, \
                                      size_t bits, \
                                      BigInt coprime = 1, \
                                      size_t equiv = 1, \
                                      size_t equiv_mod = 2)

  Return a random prime number of ``bits`` bits long that is
  relatively prime to ``coprime``, and equivalent to ``equiv`` modulo
  ``equiv_mod``.