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``.