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. You can find most of them in
``botan/bigint.h`` and ``botan/numthry.h``.

Probably the most important are the encoding/decoding functions, which
transform the normal representation of a ``BigInt`` into some other
form, such as a decimal string.

.. cpp:function:: SecureVector<byte> BigInt::encode(const BigInt& n, Encoding enc = Binary)

  This function encodes the BigInt n into a memory
  vector. ``Encoding`` is an enum that has values ``Binary``,
  ``Octal``, ``Decimal``, and ``Hexadecimal``.

.. cpp:function:: BigInt BigInt::decode(const MemoryRegion<byte>& vec, Encoding enc)

  Decode the integer from ``vec`` using the encoding specified.

These functions are static member functions, so they would be called
like this::

  BigInt n1 = ...; // some number
  SecureVector<byte> n1_encoded = BigInt::encode(n1);
  BigInt n2 = BigInt::decode(n1_encoded);
  assert(n1 == n2);

There are also C++-style I/O operators defined for use with
``BigInt``. The input operator understands negative numbers,
hexadecimal numbers (marked with a leading "0x"), and octal numbers
(marked with a leading '0'). The '-' must come before the "0x" or '0'
marker. The output operator will never adorn the output; for example,
when printing a hexadecimal number, there will not be a leading "0x"
(though a leading '-' will be printed if the number is negative). If
you want such things, you'll have to do them yourself.

``BigInt`` has constructors that can create a ``BigInt`` from an
unsigned integer or a string. You can also decode an array (a ``byte``
pointer plus a length) into a ``BigInt`` using a constructor.

Efficiency Hints
----------------------------------------

If you can, always use expressions of the form ``a += b`` over
``a = a + b``. The difference can be *very* substantial,
because the first form prevents at least one needless memory
allocation, and possibly as many as three.

If you're doing repeated modular exponentiations with the same modulus, create
a ``BarrettReducer`` ahead of time. If the exponent or base is a constant,
use the classes in ``mod_exp.h``. This stuff is all handled for you by
the normal high-level interfaces, of course.

Never use the low-level MPI functions (those that begin with
``bigint_``). These are completely internal to the library, and
may make arbitrarily strange and undocumented assumptions about their
inputs, and don't check to see if they are true, on the assumption
that only the library itself calls them, and that the library knows
what the assumptions are. The interfaces for these functions can
change completely without notice.