[/
  Copyright 2011 - 2020 John Maddock.
  Copyright 2013 - 2019 Paul A. Bristow.
  Copyright 2013 Christopher Kormanyos.

  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]

[section:cpp_int cpp_int]

`#include <boost/multiprecision/cpp_int.hpp>`

   namespace boost{ namespace multiprecision{

   typedef unspecified-type limb_type;

   enum cpp_integer_type    { signed_magnitude, unsigned_magnitude };
   enum cpp_int_check_type  { checked, unchecked };

   template <std::size_t MinBits = 0,
             std::size_t MaxBits = 0,
             cpp_integer_type SignType = signed_magnitude,
             cpp_int_check_type Checked = unchecked,
             class Allocator = std::allocator<limb_type> >
   class cpp_int_backend;
   //
   // Expression templates default to et_off if there is no allocator:
   //
   template <std::size_t MinBits, std::size_t MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked>
   struct expression_template_default<cpp_int_backend<MinBits, MaxBits, SignType, Checked, void> >
   { static const expression_template_option value = et_off; };

   typedef number<cpp_int_backend<> >              cpp_int;    // arbitrary precision integer
   typedef rational_adaptor<cpp_int_backend<> >    cpp_rational_backend;
   typedef number<cpp_rational_backend>            cpp_rational; // arbitrary precision rational number

   // Fixed precision unsigned types:
   typedef number<cpp_int_backend<128, 128, unsigned_magnitude, unchecked, void> >   uint128_t;
   typedef number<cpp_int_backend<256, 256, unsigned_magnitude, unchecked, void> >   uint256_t;
   typedef number<cpp_int_backend<512, 512, unsigned_magnitude, unchecked, void> >   uint512_t;
   typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, unchecked, void> > uint1024_t;

   // Fixed precision signed types:
   typedef number<cpp_int_backend<128, 128, signed_magnitude, unchecked, void> >     int128_t;
   typedef number<cpp_int_backend<256, 256, signed_magnitude, unchecked, void> >     int256_t;
   typedef number<cpp_int_backend<512, 512, signed_magnitude, unchecked, void> >     int512_t;
   typedef number<cpp_int_backend<1024, 1024, signed_magnitude, unchecked, void> >   int1024_t;

   // Over again, but with checking enabled this time:
   typedef number<cpp_int_backend<0, 0, signed_magnitude, checked> >                 checked_cpp_int;
   typedef rational_adaptor<cpp_int_backend<0, 0, signed_magnitude, checked> >       checked_cpp_rational_backend;
   typedef number<cpp_rational_backend>                                              checked_cpp_rational;

   // Checked fixed precision unsigned types:
   typedef number<cpp_int_backend<128, 128, unsigned_magnitude, checked, void> >     checked_uint128_t;
   typedef number<cpp_int_backend<256, 256, unsigned_magnitude, checked, void> >     checked_uint256_t;
   typedef number<cpp_int_backend<512, 512, unsigned_magnitude, checked, void> >     checked_uint512_t;
   typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, checked, void> >   checked_uint1024_t;

   // Fixed precision signed types:
   typedef number<cpp_int_backend<128, 128, signed_magnitude, checked, void> >       checked_int128_t;
   typedef number<cpp_int_backend<256, 256, signed_magnitude, checked, void> >       checked_int256_t;
   typedef number<cpp_int_backend<512, 512, signed_magnitude, checked, void> >       checked_int512_t;
   typedef number<cpp_int_backend<1024, 1024, signed_magnitude, checked, void> >     checked_int1024_t;

   }} // namespaces

The `cpp_int_backend` type is normally used via one of the convenience typedefs given above.

This back-end is the "Swiss Army Knife" of integer types as it can represent both fixed and
[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision]
integer types, and both signed and unsigned types.  There are five template arguments:

[variablelist
[[MinBits][Determines the number of Bits to store directly within the object before resorting to dynamic memory
           allocation.  When zero, this field is determined automatically based on how many bits can be stored
           in union with the dynamic storage header: setting a larger value may improve performance as larger integer
           values will be stored internally before memory allocation is required.]]
[[MaxBits][Determines the maximum number of bits to be stored in the type: resulting in a fixed precision type.
           When this value is the same as MinBits, then the Allocator parameter is ignored, as no dynamic
           memory allocation will ever be performed: in this situation the Allocator parameter should be set to
           type `void`.  Note that this parameter should not be used simply to prevent large memory
           allocations, not only is that role better performed by the allocator, but fixed precision
           integers have a tendency to allocate all of MaxBits of storage more often than one would expect.]]
[[SignType][Determines whether the resulting type is signed or not.  Note that for
[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] types
          this parameter must be `signed_magnitude`.  For fixed precision
          types then this type may be either `signed_magnitude` or `unsigned_magnitude`.]]
[[Checked][This parameter has two values: `checked` or `unchecked`.  See below.]]
[[Allocator][The allocator to use for dynamic memory allocation, or type `void` if MaxBits == MinBits.]]
]

When the template parameter Checked is set to `checked` then the result is a ['checked-integer], checked
and unchecked integers have the following properties:

[table
[[Condition][Checked-Integer][Unchecked-Integer]]
[[Numeric overflow in fixed precision arithmetic][Throws a `std::overflow_error`.][Performs arithmetic modulo 2[super MaxBits]]]
[[Constructing an integer from a value that can not be represented in the target type][Throws a `std::range_error`.]
[Converts the value modulo 2[super MaxBits], signed to unsigned conversions extract the last MaxBits bits of the
2's complement representation of the input value.]]
[[Unsigned subtraction yielding a negative value.][Throws a `std::range_error`.][Yields the value that would
result from treating the unsigned type as a 2's complement signed type.]]
[[Attempting a bitwise operation on a negative value.][Throws a `std::range_error`][Yields the value, but not the bit pattern,
that would result from performing the operation on a 2's complement integer type.]]
]

Things you should know when using this type:

* Default constructed `cpp_int_backend`s have the value zero.
* Division by zero results in a `std::overflow_error` being thrown.
* Construction from a string that contains invalid non-numeric characters results in a `std::runtime_error` being thrown.
* Since the precision of `cpp_int_backend` is necessarily limited when the allocator parameter is void,
care should be taken to avoid numeric overflow when using this type
unless you actually want modulo-arithmetic behavior.
* The type uses a sign-magnitude representation internally, so type `int128_t` has 128-bits of precision plus an extra sign bit.
In this respect the behaviour of these types differs from __fundamental 2's complement types.  In might be tempting to use a
127-bit type instead, and indeed this does work, but behaviour is still slightly different from a 2's complement __fundamental type
as the minimum and maximum values are identical (apart from the sign), where as they differ by one for a true 2's complement type.
That said it should be noted that there's no requirement for fundamental_types to be 2's complement either - it's simply that this
is the most common format by far.
* Attempting to print negative values as either an Octal or Hexadecimal string results in a `std::runtime_error` being thrown,
this is a direct consequence of the sign-magnitude representation.
* The fixed precision types `[checked_][u]intXXX_t` have expression template support turned off - it seems to make little
difference to the performance of these types either way - so we may as well have the faster compile times by turning
the feature off.
* Unsigned types support subtraction - the result is "as if" a 2's complement operation had been performed as long as they are not
 ['checked-integers] (see above).
 In other words they behave pretty much as a __fundamental integer type would in this situation.  So for example if we were using
 `uint128_t` then `uint128_t(1)-4` would result in the value `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD`
 of type `uint128_t`.  However, had this operation been performed on `checked_uint128_t` then a `std::range_error` would have
 been thrown.
* Unary negation of unsigned types results in a compiler error (static assertion).
* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
* When used at fixed precision, the size of this type is always one machine word (plus any compiler-applied alignment padding) 
larger than you would expect for an N-bit integer:
the extra word stores both the sign, and how many machine words in the integer are actually in use.
The latter is an optimisation for larger fixed precision integers, so that a 1024-bit integer has almost the same performance
characteristics as a 128-bit integer, rather than being 4 times slower for addition and 16 times slower for multiplication
 (assuming the values involved would always fit in 128 bits).
Typically this means you can use
an integer type wide enough for the "worst case scenario" with only minor performance degradation even if most of the time
the arithmetic could in fact be done with a narrower type.
Also note that unsigned fixed precision types small enough to fit inside the largest native integer become a simple wrapper around that type,
this includes the "checked" variants.  Small signed types will always have an extra sign word and so be larger than their native equivalent.
* When used at fixed precision and MaxBits is smaller than the number of bits in the largest native integer type, then
internally `cpp_int_backend` switches to a "trivial" implementation where it is just a thin wrapper around a single
integer.  Note that it will still be slightly slower than a bare native integer, as it emulates a
signed-magnitude representation rather than simply using the platforms native sign representation: this ensures
there is no step change in behavior as a cpp_int grows in size.
* Fixed precision `cpp_int`'s have some support for `constexpr` values and user-defined literals, see
[link boost_multiprecision.tut.lits here] for the full description.  For example `0xfffff_cppi1024`
specifies a 1024-bit integer with the value 0xffff.  This can be used to generate compile-time constants that are
too large to fit into any __fundamental number type.
* The __cpp_int types support constexpr arithmetic, provided it is a fixed-precision type with no allocator.  It may also
be a checked integer: in which case a compiler error will be generated on overflow or undefined behaviour.  In addition
the free functions `abs`, `swap`, `multiply`, `add`, `subtract`, `divide_qr`, `integer_modulus`, `powm`, `lsb`, `msb`, 
`bit_test`, `bit_set`, `bit_unset`, `bit_flip`, `sqrt`, `gcd`, `lcm` are all supported.  Use of __cpp_int in this way
requires either a C++2a compiler (one which supports `std::is_constant_evaluated()`), or GCC-6 or later in C++14 mode.
Compilers other than GCC and without `std::is_constant_evaluated()` will support a very limited set of operations:
expect to hit roadblocks rather easily.
* You can import/export the raw bits of a __cpp_int to and from external storage via the `import_bits` and `export_bits`
functions.  More information is in the [link boost_multiprecision.tut.import_export section on import/export].

[h5:cpp_int_eg Example:]

[cpp_int_eg]

[endsect] [/section:cpp_int cpp_int]
