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

``BigInt``, in ``bigint.h``, is an implementation of a signed magnitude
multiple-precision integer, which is used to implement certain older public key
algorithms such as RSA. It also appears in other contexts, for example X.509
certificate serial numbers are technically integer values and can be quite
large, and so are represented using a ``BigInt``.

A ``BigInt`` is a sequence of smaller integers of type ``word``; this type is
defined to be either ``uint32_t`` or ``uint64_t``, depending on the word size of
the processor.

.. warning::

   While it is possible to use the APIs provided by ``BigInt`` as a general
   calculation facility, it is **extremely inadvisable** that you attempt to
   implement a cryptographic scheme of any kind directly using ``BigInt``.
   Botan internally has many facilities for fast and side channel safe
   arithmetic which are not exposed to callers.

   In general, as a library user, avoid doing anything with ``BigInt`` besides
   serializing or deserializing them as required to call other interfaces.
   Some of the general calculation facilities of ``BigInt`` may be made internal
   to the library in a future major release.

.. cpp:class:: BigInt

   .. cpp:function:: static BigInt BigInt::from_string(std::string_view str)

      Create a BigInt from a string. By default decimal is expected. With an 0x
      prefix, instead it is treated as hexadecimal. A ``-`` prefix to indicate
      negative numbers is also accepted.

   .. cpp:function:: static BigInt::from_bytes(std::span<const uint8_t> buf)

      Create a BigInt from a binary array (big-endian encoding). The result of
      this function will always be positive; there is no support for a sign bit,
      2s complement encoding, or similar methods for indicating a negative value.

   .. cpp:function:: void serialize_to(std::span<uint8_t> buf)

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

      There must be sufficient space to encode the entire integer in ``buf``.
      If ``buf`` is larger than required, sufficient zero bytes will be
      prefixed.

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

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

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

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

   .. 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, with "0x" prefix

   .. cpp:function:: BigInt::zero()

      Create a BigInt with value zero

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

      Create a BigInt with value *n*

   .. 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:: 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_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:: bool is_negative() const

      Return true if ``*this`` is less than zero

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

      Return true if ``*this`` is greater than or equal to zero

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

      Return absolute value of ``*this``