280 lines
8.0 KiB
ReStructuredText
280 lines
8.0 KiB
ReStructuredText
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``.
|