<HTML><HEAD><TITLE>N3375=12-0065, Proposal for Unbounded-Precision Integer Types</TITLE></HEAD><BODY>

<CENTER>
<H1><A NAME="N3375=12-0065, Proposal for Unbounded-Precision Integer Types">Proposal for Unbounded-Precision Integer Types</A></H1>
</CENTER>

<TABLE ALIGN="RIGHT" CELLSPACING="0" CELLPADDING="0">
<TR>
<TD ALIGN="RIGHT"><B><I>Document number:</I></B></TD>
<TD>&nbsp; N3375&nbsp;=&nbsp;12-0065</TD>
</TR>
<TR>
<TD ALIGN="RIGHT"><B><I>Date:</I></B></TD>
<TD>&nbsp; 2012-02-24</TD>
</TR>
<TR>
<TD ALIGN="RIGHT"><B><I>Project:</I></B></TD>
<TD>&nbsp; Programming Language C++</TD>
</TR>
<TR>
<TD ALIGN="RIGHT"><B><I>Reference:</I></B></TD>
<TD>&nbsp; ISO/IEC IS 14882:2011(E)</TD>
</TR>
<TR>
<TD ALIGN="RIGHT"><B><I>Reply to:</I></B></TD>
<TD>&nbsp; Pete Becker</TD>
</TR>
<TR>
<TD></TD>
<TD>&nbsp; Roundhouse Consulting, Ltd.</TD>
</TR>
<TR>
<TD></TD>
<TD>&nbsp; pete@versatilecoding.com</TD>
</TR>
</TABLE>
<BR CLEAR="ALL">

<HR>

<H2><A NAME="Overview">Overview</A></H2>

<p>Programmers sometimes need to manipulate integer values that are too large to
repesent with C++&rsquo;s standard integer types. Doing a Google search for
terms that describe large integers produces many hits for libraries that handle
large integers. These libraries vary in quality, from hacks by beginners to
sophisticated, professional implementations. Also, Java has unbounded precision
integers as part of its standard class library.</p>

<p>One important use for unbounded-precision integers is cryptography.
Cryptographic applications typically manipulate integer values of several
hundred digits. If the C++ standard library provides facilities for such values
it will make cryptographic applications easier to write and to port.</p>

<p>There have been two Committee papers proposing unbounded-precision integer
libraries for C++: N1718 (2004) and N2143 (2007), both by M.J. Kronenburg.
Nothing was done with these papers, in part because there was too much else
going on in the Library Working Group at the time. Now that the Committee is
looking to greatly expand the scope of the standard library, it&rsquo;s time to
reconsider unbounded-precision integers.</p>

<H2><A NAME="Design considerations">Design considerations</A></H2>

<p>An <i>unbounded-precision integer type</i> is an integer type that does not
impose pre-defined limits on the precision of the values that it can represent.
Of course, in practice, unbounded precision can&rsquo;t be achieved; sooner or
later the system runs out of resources. So <i>unbounded</i> in this context
means bounded only by the availability of system resources; there is no
hard-coded limit to the number of digits in the value that an
unbounded-precision integer type an represent.</p>

<p>Unbounded-precision integer types should <i>interoperate</i> with C++&rsquo;s
built-in integer types. Applying arithmetic operations to a mix of standard
integer types and unbounded-precision integer types should just work. And to the
extent possible, operations that can be applied to standard integer types should
also be applicable, using the same syntax, to unbounded-precision integer
types.</p>

<p>Unbounded-precision integer types should also provide operations that
facilitate their application in the areas that demand such types. In particular,
to support cryptographic applications, an unbounded-precision integer type must
provide facilities for generating random values (with a user-specified source of
randomness) and for determining whether any particular value is a prime number
(subject to the limitations of number theory; for large values, primality can
only be determined to a degree of certainty in a reasonable amount of time).</p>

<H2><A NAME="Design overview">Design overview</A></H2>

<p>This paper proposes two unbounded-precision integer types. The type
<code>unsigned_integer</code> represents unsigned integer values; the type
<code>integer</code> represents signed integer values. In addition to the basic
arithmetic operations, <code>unsigned_integer</code> supports manipulation of
individual bits. It also provides a function for generating random values, a
function for determining whether a value is prime (within a specified degree of
certainty), and a function for generating prime numbers (again, within a
specified degree of certainty). The type <code>integer</code> is more of a pure
arithmetic type. It does not provide the additional operations that
<code>unsigned_integer</code> provides.</p>

<p>To support interoperability, objects of either types can be constructed from
values of any of the standard integer types. So code like this just works:</p>

<code><pre>    integer i = 30000;
    integer j = 1000 * i;</pre></code>

<p>As currently specified, neither <code>unsigned_integer</code> nor
<code>integer</code> provides overloaded operators that take standard integer
types. When an operation is applied to a standard integer type and an
<code>unsigned_integer</code> or an <code>integer</code>, the standard integer
operand is converted to the appropriate unbounded-precision integer type and the
operation is applied to the result. It is assumed that implementations will make
this kind of mixed operation efficient by implementing a small-integer
optimization, storing small values directly in the <code>unsigned_integer</code>
or <code>integer</code> object, and using heap storage when needed for larger
values. This greatly simplifies the interface specification.</p>

<p>Objects of these types can also be constructed from values of floating-point
types. Conversions from floating-point to integer are inherently lossy, so these
constructors are marked <code>explicit</code>.</p>

<p>Objects of these types can also be constructed from string representations
(with the usual range of possible bases) and from an initializer list that holds
unsigned 32-bit values.</p>

<p>Values of type <code>unsigned_integer</code> can be freely converted to
<code>integer</code> through copy construction and assignment. Values of type
<code>integer</code> cannot be assigned directly to values of type
<code>unsigned_integer</code>, nor can a value of type
<code>unsigned_integer</code> be constructed implicitly from a value of type
<code>integer</code>; this prevents accidentally attempting to convert a
negative value to a positive one. The C and C++ rule that in such assignments the result is reduced modulo <code>2<sup>n</sup></code> should not be applied to unbounded-precision integer types, because <code>n</code> is rather large.</p>

<p>Bit manipulations on <code>unsigned_integer</code> values treat the value as
having an unbounded number of zero bits above the highest non-zero bit in the
value. As a result, the usual bit operations, &amp;, |, and ^, can be applied to
values of different sizes. Further, <code>unsigned_integer</code> can be used as
a replacement for <code>std::bitset</code> (although with a less thorough
interface) when limiting the object to a fixed number of bits is
undesirable.</p>

<H2><A NAME="Open issues">Open issues</A></H2>

<ol>

<li><b>Allocators</b> -- unbounded-precision integer types need to manage memory
on the free store to hold their data. This suggests that users should be able to
specify an allocator. But templatizing these types on an allocator would require
that all of the arithmetic operations provide overloads for all of the standard
integer types, because function template instantiation requires exact type
matches, without conversions.</li>

<li><b>Policy for out-of-bounds subtraction</b> -- subtracting an
<code>unsigned_integer</code> value from a smaller value doesn&rsquo;t have any specified semanticas in ths paper. This should probably throw an
exception.</li>

<li><b>Policy for out-of-bounds constructor arguments</b> -- constructing an
<code>unsigned_integer</code> object from a negative value doesn&rsquo;t have
any specified semantics in this paper. This should probably throw an
exception.</li>

<li><b>Policy for lossy conversions</b> -- converting an
<code>unsigned_integer</code> or <code>integer</code> object to an integral type
that cannot represent its value doesn&rsquo;t have any specified semantics in
this paper. Should this throw an exception?</li>

</ol>

<H2><A NAME="header_seminumeric">Header <code>&lt;seminumeric&gt;</code> 
synopsis</A></H2>

<pre><code>namespace std {
namespace seminumeric {

/* class unsigned_integer */

    class <B><A HREF="#unsigned_integer">unsigned_integer</A></B>;
    template &lt;&gt; class numeric_limits&lt;unsigned_integer&gt;;
    
    void <B><A HREF="#swap">swap</A></B>(unsigned_integer&amp;, unsigned_integer&amp;);

    // arithmetic operations
    unsigned_integer <B><A HREF="#operator+">operator+</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#operator-">operator-</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#operator*">operator*</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#operator/">operator/</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#operator%">operator%</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    std::pair&lt;unsigned_integer, unsigned_integer&gt; <B><A HREF="#div">div</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);

    unsigned_integer <B><A HREF="#operator&lt;&lt;">operator&lt;&lt;</A></B>(const unsigned_integer&amp;, int);
    unsigned_integer <B><A HREF="#operator&gt;&gt;">operator&gt;&gt;</A></B>(const unsigned_integer&amp;, int);

    // logical operations
    unsigned_integer <B><A HREF="#operator&amp;">operator&amp;</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#operator|">operator|</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#operator^">operator^</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);

    // comparisons
    bool <B><A HREF="#operator==">operator==</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    bool <B><A HREF="#operator!=">operator!=</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    bool <B><A HREF="#operator&lt;">operator&lt;</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    bool <B><A HREF="#operator&lt;=">operator&lt;=</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    bool <B><A HREF="#operator&gt;">operator&gt;</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    bool <B><A HREF="#operator&gt;=">operator&gt;=</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);

    // numeric operations
    unsigned_integer <B><A HREF="#sqr">sqr</A></B>(const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#sqrt">sqrt</A></B>(const unsigned_integer&amp;);
    std::pair&lt;unsigned_integer, unsigned_integer&gt; <B><A HREF="#sqrtrem">sqrtrem</A></B>(const unsigned_integer&amp;);

    unsigned_integer <B><A HREF="#pow">pow</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#mod">mod</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#powmod">powmod</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#invmod">invmod</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);

    unsigned_integer <B><A HREF="#gcd">gcd</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer <B><A HREF="#lcm">lcm</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);

    // randomness and primality
    template &lt;class Engine&gt;
        unsigned_integer <B><A HREF="#random">random</A></B>(unsigned, Engine);
    template &lt;class Engine&gt;
        bool <B><A HREF="#is_probable_prime">is_probable_prime</A></B>(const unsigned_integer&amp;, int, Engine);
    template &lt;class Engine&gt;
        unsigned_integer <B><A HREF="#probable_prime">probable_prime</A></B>(unsigned, int, Engine);

    // stream inserter and extractor
    template &lt;class Elem, class Traits&gt;
        std::basic_istream&lt;Elem, Traits&gt;&amp; <B><A HREF="#stream_operator&gt;&gt;">operator&gt;&gt;</A></B>(std::basic_istream&lt;Elem, Traits&gt;&amp;, unsigned_integer&amp;);
    template &lt;class Elem, class Traits&gt;
        std::basic_ostream&lt;Elem, Traits&gt;&amp; <B><A HREF="#stream_operator&lt;&lt;">operator&lt;&lt;</A></B>(std::basic_ostream&lt;Elem, Traits&gt;&amp;, const unsigned_integer&amp;);
    void swap(integer&amp;, integer&amp;);


/* class integer */

    class <B><A HREF="#integer">integer</A></B>;
    template &lt;&gt; class numeric_limits&lt;integer&gt;;

    void <B><A HREF="#swap">swap</A></B>(integer&amp;, integer&amp;);

    // arithmetic operations
    integer <B><A HREF="#operator+">operator+</A></B>(const integer&amp;, const integer&amp;);
    integer <B><A HREF="#operator-">operator-</A></B>(const integer&amp;, const integer&amp;);
    integer <B><A HREF="#operator*">operator*</A></B>(const integer&amp;, const integer&amp;);
    integer <B><A HREF="#operator/">operator/</A></B>(const integer&amp;, const integer&amp;);
    integer <B><A HREF="#operator%">operator%</A></B>(const integer&amp;, const integer&amp;);
    std::pair&lt;integer, integer&gt; <B><A HREF="#div">div</A></B>(const integer&amp;, const integer&amp;);

    integer <B><A HREF="#operator&lt;&lt;">operator&lt;&lt;</A></B>(const integer&amp;, int);
    integer <B><A HREF="#operator&gt;&gt;">operator&gt;&gt;</A></B>(const integer&amp;, int);

    // comparisons
    bool <B><A HREF="#operator==">operator==</A></B>(const integer&amp;, const integer&amp;);
    bool <B><A HREF="#operator!=">operator!=</A></B>(const integer&amp;, const integer&amp;);
    bool <B><A HREF="#operator&lt;">operator&lt;</A></B>(const integer&amp;, const integer&amp;);
    bool <B><A HREF="#operator&lt;=">operator&lt;=</A></B>(const integer&amp;, const integer&amp;);
    bool <B><A HREF="#operator&gt;">operator&gt;</A></B>(const integer&amp;, const integer&amp;);
    bool <B><A HREF="#operator&gt;=">operator&gt;=</A></B>(const integer&amp;, const integer&amp;);

    // numeric operations
    integer <B><A HREF="#sqr">sqr</A></B>(const integer&amp;);
    integer <B><A HREF="#sqrt">sqrt</A></B>(const integer&amp;);
    std::pair&lt;integer, integer&gt; <B><A HREF="#sqrtrem">sqrtrem</A></B>(const integer&amp;);

    integer <B><A HREF="#pow">pow</A></B>(const integer&amp;, const unsigned_integer&amp;);
    integer <B><A HREF="#mod">mod</A></B>(const integer&amp;, const unsigned_integer&amp;);
    integer <B><A HREF="#powmod">powmod</A></B>(const integer&amp;, const unsigned_integer&amp;, const unsigned_integer&amp;);
    integer <B><A HREF="#invmod">invmod</A></B>(const integer&amp;, const unsigned_integer&amp;);

    integer <B><A HREF="#gcd">gcd</A></B>(const integer&amp;, const integer&amp;);
    integer <B><A HREF="#lcm">lcm</A></B>(const integer&amp;, const integer&amp;);

    // stream inserter and extractor
    template &lt;class Elem, class Traits&gt;
        std::basic_istream&lt;Elem, Traits&gt;&amp; <B><A HREF="#stream_operator&gt;&gt;">operator&gt;&gt;</A></B>(std::basic_istream&lt;Elem, Traits&gt;&amp;, integer&amp;);
    template &lt;class Elem, class Traits&gt;
        std::basic_ostream&lt;Elem, Traits&gt;&amp; <B><A HREF="#stream_operator&lt;&lt;">operator&lt;&lt;</A></B>(std::basic_ostream&lt;Elem, Traits&gt;&amp;, const integer&amp;);

}   /* namespace seminumeric */
}   /* namespace std */</code></pre>

<H2><A NAME="class_unsigned_integer">Class 
<code>unsigned_integer</code></A></H2>

<pre><code>class <B><A NAME="unsigned_integer">unsigned_integer</A></B> {
public:
    // construct, copy
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>();
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(char);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(signed char);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(unsigned char);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(short);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(unsigned short);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(int);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(unsigned int);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(long);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(unsigned long);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(long long);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(unsigned long long);
    explicit <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(float);
    explicit <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(double);
    explicit <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(long double);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(const std::string&amp;, int base = 10);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(std::initializer_list&lt;<i>unspecified</i>&gt;);

    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(const unsigned_integer&amp;);
    <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(unsigned_integer&amp;&amp;);
    explicit <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(const integer&amp;);
    explicit <B><A HREF="#unsigned_integer::unsigned_integer">unsigned_integer</A></B>(integer&amp;&amp;);

    unsigned_integer&amp; <B><A HREF="#operator=">operator=</A></B>(const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#operator=">operator=</A></B>(unsigned_integer&amp;&amp;);

    void <B><A HREF="#swap">swap</A></B>(unsigned_integer&amp;);

    // conversions
    explicit <B><A HREF="#operator int">operator int</A></B>() const;
    explicit <B><A HREF="#operator int">operator unsigned</A></B>() const;
    explicit <B><A HREF="#operator int">operator long</A></B>() const;
    explicit <B><A HREF="#operator int">operator unsigned long</A></B>() const;
    explicit <B><A HREF="#operator int">operator long long</A></B>() const;
    explicit <B><A HREF="#operator int">operator unsigned long long</A></B>() const;
    explicit <B><A HREF="#operator float">operator float</A></B>() const;
    explicit <B><A HREF="#operator float">operator double</A></B>() const;
    explicit <B><A HREF="#operator float">operator long double</A></B>() const;
    explicit <B><A HREF="#operator string">operator std::string</A></B>() const;
    explicit <B><A HREF="#operator bool">operator bool</A></B>() const;

    // arithmetic operations
    unsigned_integer&amp; <B><A HREF="#operator+=">operator+=</A></B>(const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#operator-=">operator-=</A></B>(const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#operator*=">operator*=</A></B>(const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#operator/=">operator/=</A></B>(const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#operator%=">operator%=</A></B>(const unsigned_integer&amp;);
    std::pair&lt;unsigned_integer, unsigned_integer&gt; <B><A HREF="#div">div</A></B>(const unsigned_integer&amp;) const;

    unsigned_integer&amp; <B><A HREF="#operator++">operator++</A></B>();
    unsigned_integer <B><A HREF="#operator++">operator++</A></B>(int);
    unsigned_integer&amp; <B><A HREF="#operator--">operator--</A></B>();
    unsigned_integer <B><A HREF="#operator--">operator--</A></B>(int);

    unsigned_integer&amp; <B><A HREF="#operator&lt;&lt;=">operator&lt;&lt;=</A></B>(int);
    unsigned_integer&amp; <B><A HREF="#operator&gt;&gt;=">operator&gt;&gt;=</A></B>(int);

    // logical operations
    unsigned_integer&amp; <B><A HREF="#operator&amp;=">operator&amp;=</A></B>(const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#operator|=">operator|=</A></B>(const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#operator^=">operator^=</A></B>(const unsigned_integer&amp;);

    // numeric operations
    unsigned_integer&amp; <B><A HREF="#sqr">sqr</A></B>();
    unsigned_integer&amp; <B><A HREF="#sqrt">sqrt</A></B>();
    unsigned_integer <B><A HREF="#sqrtrem">sqrtrem</A></B>();

    unsigned_integer&amp; <B><A HREF="#pow">pow</A></B>(const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#mod">mod</A></B>(const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#powmod">powmod</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    unsigned_integer&amp; <B><A HREF="#invmod">invmod</A></B>(const unsigned_integer&amp;);

    // bit twiddling
    void <B><A HREF="#set">set</A></B>(size_t, bool val = true);
    void <B><A HREF="#flip">flip</A></B>(size_t);
    bool <B><A HREF="#test">test</A></B>(size_t) const;

    int <B><A HREF="#lowest_bit">lowest_bit</A></B>() const;
    int <B><A HREF="#highest_bit">highest_bit</A></B>() const;

    // observers
    bool <B><A HREF="#is_odd">is_odd</A></B>() const;
    std::string <B><A HREF="#to_string">to_string</A></B>(int base = 10) const;
};
</code></pre>

<H2><A NAME="class_integer">Class <code>integer</code></A></H2>

<pre><code>class <B><A NAME="integer">integer</A></B> {
public:
    // construct, copy
    <B><A HREF="#integer::integer">integer</A></B>();
    <B><A HREF="#integer::integer">integer</A></B>(char);
    <B><A HREF="#integer::integer">integer</A></B>(signed char);
    <B><A HREF="#integer::integer">integer</A></B>(unsigned char);
    <B><A HREF="#integer::integer">integer</A></B>(short);
    <B><A HREF="#integer::integer">integer</A></B>(unsigned short);
    <B><A HREF="#integer::integer">integer</A></B>(int);
    <B><A HREF="#integer::integer">integer</A></B>(unsigned int);
    <B><A HREF="#integer::integer">integer</A></B>(long);
    <B><A HREF="#integer::integer">integer</A></B>(unsigned long);
    <B><A HREF="#integer::integer">integer</A></B>(long long);
    <B><A HREF="#integer::integer">integer</A></B>(unsigned long long);
    explicit <B><A HREF="#integer::integer">integer</A></B>(float);
    explicit <B><A HREF="#integer::integer">integer</A></B>(double);
    explicit <B><A HREF="#integer::integer">integer</A></B>(long double);
    <B><A HREF="#integer::integer">integer</A></B>(const std::string&amp;, int base = 10);
    <B><A HREF="#integer::integer">integer</A></B>(std::initializer_list&lt;<i>unspecified</i>&gt;);

    <B><A HREF="#integer::integer">integer</A></B>(const integer&amp;);
    <B><A HREF="#integer::integer">integer</A></B>(integer&amp;&amp;);
    <B><A HREF="#integer::integer">integer</A></B>(const unsigned_integer&amp;);
    <B><A HREF="#integer::integer">integer</A></B>(unsigned_integer&amp;&amp;);

    integer&amp; <B><A HREF="#operator=">operator=</A></B>(const integer&amp;);
    integer&amp; <B><A HREF="#operator=">operator=</A></B>(integer&amp;&amp;);
    integer&amp; <B><A HREF="#operator=">operator=</A></B>(const unsigned_integer&amp;);
    integer&amp; <B><A HREF="#operator=">operator=</A></B>(unsigned_integer&amp;&amp;);

    void <B><A HREF="#swap">swap</A></B>(integer&amp;);

    // conversions
    explicit <B><A HREF="#operator int">operator int</A></B>() const;
    explicit <B><A HREF="#operator int">operator unsigned</A></B>() const;
    explicit <B><A HREF="#operator int">operator long</A></B>() const;
    explicit <B><A HREF="#operator int">operator unsigned long</A></B>() const;
    explicit <B><A HREF="#operator int">operator long long</A></B>() const;
    explicit <B><A HREF="#operator int">operator unsigned long long</A></B>() const;
    explicit <B><A HREF="#operator float">operator float</A></B>() const;
    explicit <B><A HREF="#operator float">operator double</A></B>() const;
    explicit <B><A HREF="#operator float">operator long double</A></B>() const;
    explicit <B><A HREF="#operator string">operator std::string</A></B>() const;
    explicit <B><A HREF="#operator bool">operator bool</A></B>() const;

    // arithmetic operations
    integer&amp; <B><A HREF="#operator+=">operator+=</A></B>(const integer&amp;);
    integer&amp; <B><A HREF="#operator-=">operator-=</A></B>(const integer&amp;);
    integer&amp; <B><A HREF="#operator*=">operator*=</A></B>(const integer&amp;);
    integer&amp; <B><A HREF="#operator/=">operator/=</A></B>(const integer&amp;);
    integer&amp; <B><A HREF="#operator%=">operator%=</A></B>(const integer&amp;);
    std::pair&lt;integer, integer&gt; <B><A HREF="#div">div</A></B>(const integer&amp;) const;

    integer&amp; <B><A HREF="#operator++">operator++</A></B>();
    integer <B><A HREF="#operator++">operator++</A></B>(int);
    integer&amp; <B><A HREF="#operator--">operator--</A></B>();
    integer <B><A HREF="#operator--">operator--</A></B>(int);
    
    integer <B><A HREF="#unary_operator+">operator+</A></B>();
    integer <B><A HREF="#unary_operator-">operator-</A></B>();
    integer&amp; negate();

    integer&amp; <B><A HREF="#operator&lt;&lt;=">operator&lt;&lt;=</A></B>(int);
    integer&amp; <B><A HREF="#operator&gt;&gt;=">operator&gt;&gt;=</A></B>(int);

    // numeric operations
    integer&amp; <B><A HREF="#sqr">sqr</A></B>();
    integer&amp; <B><A HREF="#sqrt">sqrt</A></B>();
    integer <B><A HREF="#sqrtrem">sqrtrem</A></B>();

    integer&amp; <B><A HREF="#pow">pow</A></B>(const unsigned_integer&amp;);
    integer&amp; <B><A HREF="#mod">mod</A></B>(const unsigned_integer&amp;);
    integer&amp; <B><A HREF="#powmod">powmod</A></B>(const unsigned_integer&amp;, const unsigned_integer&amp;);
    integer&amp; <B><A HREF="#invmod">invmod</A></B>(const unsigned_integer&amp;);

    // observers
    bool <B><A HREF="#is_odd">is_odd</A></B>() const;
    std::string <B><A HREF="#to_string">to_string</A></B>(int base = 10) const;
};
</code></pre><hr>

<B><A NAME="div">div</A></B>

<code><pre>std::pair&lt;integer, integer&gt; <b>div</b>(const integer&amp; left, const integer&amp; right);
std::pair&lt;unsigned_integer, unsigned_integer&gt; <b>div</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);

std::pair&lt;integer, integer&gt; <b>integer::div</b>(const integer&amp; right) const;
std::pair&lt;unsigned_integer, unsigned_integer&gt; <b>unsigned_integer::div</b>(const unsigned_integer&amp; right) const;</pre></code>

<p>The functions return an object that is an instantiation of
<code>std::pair</code>; its <code>first</code> field holds the quotient,
<code>left / right</code> or <code>*this / right</code>, and its
<code>second</code> field holds the remainder, <code>left % right</code> or
<code>*this % right</code>.</p>

<B><A NAME="flip">flip</A></B>

<code><pre>void <b>unsigned_integer::flip</b>(size_t pos);</pre></code>

<p>The member function toggles the bit at position <code>pos</code> in the
stored value.</p>

<B><A NAME="gcd">gcd</A></B>

<code><pre>integer <b>gcd</b>(const integer&amp; a, const integer&amp; b);
unsigned_integer <b>gcd</b>(const unsigned_integer&amp; a, const unsigned_integer&amp; b);</pre></code>

<p>The functions return return an object whose value is the greatest common
denominator of <code>a</code> and <code>b</code>.</p>

<B><A NAME="highest_bit">highest_bit</A></B>

<code><pre>int <b>unsigned_integer::highest_bit</b>() const;</pre></code>

<p>The member function returns the zero-based position of the highest non-zero
bit in the stored value, or -1 if there are no non-zero bits.</p>

<B><A NAME="invmod">invmod</A></B>

<code><pre>integer <b>invmod</b>(const integer&amp; val, const unsigned_integer&amp; m);
unsigned_integer <b>invmod</b>(const unsigned_integer&amp; val, const unsigned_integer&amp; m);

integer&amp; <b>integer::invmod</b>(const unsigned_integer&amp; m);
unsigned_integer&amp; <b>unsigned_integer::invmod</b>(const unsigned_integer&amp; m);</pre></code>

<p>The non-member functions return an object whose value is
<code>val<sup>-1</sup> mod m</code>. The member functions set the stored value
of <code>*this</code> to <code>*this<sup>-1</sup> mod m</code> and return
<code>*this</code>.</p>

<B><A NAME="lcm">lcm</A></B>

<code><pre>integer <b>lcm</b>(const integer&amp; a, const integer&amp; b);
unsigned_integer <b>lcm</b>(const unsigned_integer&amp; a, const unsigned_integer&amp; b);</pre></code>

<p>The functions return an object whose value is the least common multiple of
<code>a</code> and <code>b</code>.</p>

<B><A NAME="integer::integer">integer::integer</A></B>

<code><pre><b>integer::integer</b>();

<b>integer::integer</b>(char val);
<b>integer::integer</b>(signed char val);
<b>integer::integer</b>(unsigned char val);
<b>integer::integer</b>(short val);
<b>integer::integer</b>(unsigned short val);
<b>integer::integer</b>(int val);
<b>integer::integer</b>(unsigned int val);
<b>integer::integer</b>(long val);
<b>integer::integer</b>(unsigned long val);
<b>integer::integer</b>(long long val);
<b>integer::integer</b>(unsigned long long val);

explicit <b>integer::integer</b>(float val);
explicit <b>integer::integer</b>(double val);
explicit <b>integer::integer</b>(long double val);

<b>integer::integer</b>(const std::string&amp; str, int base = 10);

<b>integer::integer</b>(std::initializer_list&lt;<i>unspecified</i>&gt; list);

<b>integer::integer</b>(const integer&amp; other);
<b>integer::integer</b>(integer&amp;&amp; other);
<b>integer::integer</b>(const unsigned_integer&amp; other);
<b>integer::integer</b>(unsigned_integer&amp;&amp; other);</pre></code>

<p>The default constructor constructs an object whose value is
<code>0</code>.</p>

<p>The constructors that take integral arguments construct objects whose value
is <code>val</code>.</p>

<p>The constructors that take floating-point arguments construct objects whose
value is an approximation to <code>val</code>, accurate to at least
<code>std::numeric_limits<floating-point-type>::digits</code>.</p>

<p>The constructor that takes a <code>string</code> constructs an object whose
value is the value represented by the string object. The string object shall
have the form required for the string argument to the function
<code>std::strtol</code> with a radix of <code>base</code>, and shall be
interpreted as if by <code>std::strtol(str.c_str(), 0, base)</code>, except that
the resulting value can never be outside the range of representable values.</p>

<p>The constructor that takes an initializer_list constructs an object whose
stored value is equal to the elements of the initializer_list treated as a
series of unsigned 32-bit digits with the leftmost digit being most significant.
For example, the initializer list <code>{ 0xFE, 0xF0, 0xAA, 0x31 }</code>
represents the value <code>0xFE * 32<sup>3</sup> + 0xF0 * 32<sup>2</sup> + 0xAA
* 32<sup>1</sup> + 0x31 * 32<sup>0</sup></code>.</p>

<p>The copy and move constructors construct objects with the same value as
<code>other</code>.</p>

<B><A NAME="is_odd">is_odd</A></B>

<code><pre>bool <b>integer::is_odd</b>() const;
bool <b>unsigned_integer::is_odd</b>() const;</pre></code>

<p>The member functions return <code>true</code> only if the stored value
represents an odd number.</p>

<B><A NAME="is_probable_prime">is_probable_prime</A></B>

<code><pre>template &lt;class Engine&gt;
    bool <b>is_probable_prime</b>(const unsigned_integer&amp; val, int certainty, Engine eng);</pre></code>

<p>The template function returns <code>true</code> only if the value
<code>val</code> can be determined to be a prime number with probability greater
than <code>1 - 2<sup>-certainty/2</sup></code>. It uses <code>eng</code> as a
source of randomness for this evaluation.</p>

<B><A NAME="lowest_bit">lowest_bit</A></B>

<code><pre>int <b>unsigned_integer::lowest_bit</b>() const;</pre></code>

<p>The member function returns the zero-based position of the lowest non-zero
bit in the stored value, or -1 if there are no non-zero bits.</p>

<B><A NAME="mod">mod</A></B>

<code><pre>integer <b>mod</b>(const integer&amp; val, const unsigned_integer&amp; m);
unsigned_integer <b>mod</b>(const unsigned_integer&amp; val, const unsigned_integer&amp; m);

integer&amp; <b>integer::mod</b>(const unsigned_integer&amp; m);
unsigned_integer&amp; <b>unsigned_integer::mod</b>(const unsigned_integer&amp; m);</pre></code>

<p>The non-member functions return an object whose value is <code>val mod
m</code>. The member functions set the stored value in <code>*this</code> to
<code>*this mod m</code> and return a reference to <code>*this</code>.</p>

<B><A NAME="negate">negate</A></B>

<code><pre>integer&amp; <b>integer::negate</b>();</pre></code>

<p>The member function sets the stored value of <code>*this</code> to the
negation of its previous vaue and returns a reference to <code>*this</code>.</p>

<B><A NAME="operator+">operator+</A></B>

<code><pre>integer <b>operator+</b>(const integer&amp; left, const integer&amp; right);
unsigned_integer <b>operator+</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return an object whose value is the sum of the values of
<code>left</code> and <code>right</code>.</p>

<B><A NAME="operator+=">operator+=</A></B>

<code><pre>integer&amp; <b>integer::operator+=</b>(const integer&amp; right);
unsigned_integer&amp; <b>unsigned_integer::operator+=</b>(const unsigned_integer&amp; right);</pre></code>

<p>The member operators set the stored value of <code>*this</code> to the sum of
the values of <code>*this</code> and <code>right</code> and return a reference
to <code>*this</code>.</p>

<B><A NAME="operator++">operator++</A></B>

<code><pre>integer&amp; <b>integer::operator++</b>();
unsigned_integer&amp; <b>unsigned_integer::operator++</b>();

integer <b>integer::operator++</b>(int);
unsigned_integer <b>unsigned_integer::operator++</b>(int);</pre></code>

<p>The member operators set the value stored in <code>*this</code> to
<code>*this + 1</code>. The first two operators return <code>*this</code>. The
last two operators return an object whose value is the value stored in
<code>*this</code> prior to the increment.</p>

<B><A NAME="unary_operator+">operator+</A></B>

<code><pre>integer <b>integer::operator+</b>();</pre></code>

<p>The member function returns an object whose value is equal to the value of
<code>*this</code>.</p>

<B><A NAME="operator-">operator-</A></B>

<code><pre>integer <b>operator-</b>(const integer&amp; left, const integer&amp; right);
unsigned_integer <b>operator-</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return an object whose value is the difference between the
values of <code>left</code> and <code>right</code>.</p>

<B><A NAME="operator-=">operator-=</A></B>

<code><pre>integer&amp; <b>integer::operator-=</b>(const integer&amp;);
unsigned_integer&amp; <b>unsigned_integer::operator-=</b>(const unsigned_integer&amp;);</pre></code>

<p>The member operators set the stored value of <code>*this</code> to the
difference between the values of <code>*this</code> and <code>right</code> and
return a reference to <code>*this</code>.</p>

<B><A NAME="operator--">operator--</A></B>

<code><pre>integer&amp; <b>integer::operator--</b>();
unsigned_integer&amp; <b>unsigned_integer::operator--</b>();

integer <b>integer::operator--</b>(int);
unsigned_integer <b>unsigned_integer::operator--</b>(int);</pre></code>

<p>The member operators set the value stored in <code>*this</code> to
<code>*this - 1</code>. The first two operators return <code>*this</code>. The
last two operators return an object whose value is the value stored in
<code>*this</code> prior to the decrement.</p>


<B><A NAME="unary_operator-">operator-</A></B>

<code><pre>integer <b>integer::operator-</b>();</pre></code>

<p>The member operator returns an object whose value is the negation of the
value of <code>*this</code>.</p>

<B><A NAME="operator*">operator*</A></B>

<code><pre>integer <b>operator*</b>(const integer&amp; left, const integer&amp; right);
unsigned_integer <b>operator*</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return an object whose value is the product of the values of
<code>left</code> and <code>right</code>.</p>

<B><A NAME="operator*=">operator*=</A></B>

<code><pre>integer&amp; <b>integer::operator*=</b>(const integer&amp; right);
unsigned_integer&amp; <b>unsigned_integer::operator*=</b>(const unsigned_integer&amp; right);</pre></code>

<p>The member operators set the stored value of <code>*this</code> to the
product of the values of <code>*this</code> and <code>right</code> and return a
reference to <code>*this</code>.</p>

<B><A NAME="operator/">operator/</A></B>

<code><pre>integer <b>operator/</b>(const integer&amp; left, const integer&amp; right);
unsigned_integer <b>operator/</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return an object whose value is the quotient of the value of
<code>left</code> divided by the value of <code>right</code>, discarding any
fractional part.</p>

<B><A NAME="operator/=">operator/=</A></B>

<code><pre>integer&amp; <b>integer::operator/=</b>(const integer&amp; right);
unsigned_integer&amp; <b>unsigned_integer::operator/=</b>(const unsigned_integer&amp; right);</pre></code>

<p>The member operators set the stored value of <code>*this</code> to the
quotient of the value of <code>*this</code> divided by the value of
<code>right</code>, discarding any fractional part, and return a reference to
<code>*this</code>.</p>

<B><A NAME="operator%">operator%</A></B>

<code><pre>integer <b>operator%</b>(const integer&amp;, const integer&amp;);
unsigned_integer <b>operator%</b>(const unsigned_integer&amp;, const unsigned_integer&amp;);</pre></code>

<p>The operators return an object whose value is the remainder of the value of
<code>left</code> divided by the value of <code>right</code>. The remainder is
the value such that <code>(left / right) * right + left % right</code> is equal
to <code>left</code>.</p>

<B><A NAME="operator%=">operator%=</A></B>

<code><pre>integer&amp; <b>integer::operator%=</b>(const integer&amp;);
unsigned_integer&amp; <b>unsigned_integer::operator%=</b>(const unsigned_integer&amp;);</pre></code>

<p>The member operators set the stored value of <code>*this</code> to the
remainder of <code>*this</code> divided by the value of <code>right</code> and
return a reference to <code>*this</code>.</p>

<B><A NAME="operator&lt;&lt;">operator&lt;&lt;</A></B>

<code><pre>integer <b>operator&lt;&lt;</b>(const integer&amp; val, int shift);
unsigned_integer <b>operator&lt;&lt;</b>(const unsigned_integer&amp; val, int shift);</pre></code>

<p>If the value of <code>shift</code> is negative, the operators returns <code>
operator&gt;&gt;(val, -shift)</code>. Otherwise, the operators return a new
object whose value is <code>val * 2<sup>shift</sup></code>.</p>

<B><A NAME="operator&lt;&lt;=">operator&lt;&lt;=</A></B>

<code><pre>integer&amp; <b>integer::operator&lt;&lt;=</b>(int);
unsigned_integer&amp; <b>unsigned_integer::operator&lt;&lt;=</b>(int shift);</pre></code>

<p>If the value of <code>shift</code> is negative, the operators have the effect of <code>*this &gt;&gt;= -shift</code>. Otherwise, the operators set the value of <code>*this</code> to <code>*this * 2<sup>shift</sup></code>. The operators return a reference to <code>*this</code>.</p>

<B><A NAME="stream_operator&lt;&lt;">operator&lt;&lt;</A></B>

<code><pre>template &lt;class Elem, class Traits&gt;
    std::basic_ostream&lt;Elem, Traits&gt;&amp; <b>operator&lt;&lt;</b>(std::basic_ostream&lt;Elem, Traits&gt;&amp; strm, const integer&amp; val);
template &lt;class Elem, class Traits&gt;
    std::basic_ostream&lt;Elem, Traits&gt;&amp; <b>operator&lt;&lt;</b>(std::basic_ostream&lt;Elem, Traits&gt;&amp; strm, const unsigned_integer&amp; val);</pre></code>

<p>The operators have the effect of <code>strm &lt;&lt; val.to_string()</code>,
and return a reference to <code>strm</code>.</p>

<B><A NAME="operator&gt;&gt;">operator&gt;&gt;</A></B>

<code><pre>integer <b>operator&gt;&gt;</b>(const integer&amp; val, int shift);
unsigned_integer <b>operator&gt;&gt;</b>(const unsigned_integer&amp; val, int shift);</pre></code>

<p>If the value of <code>shift</code> is negative, the operators returns <code>
operator&lt;&lt;(val, -shift)</code>. Otherwise, the operators return a new
object whose value is <code>val / 2<sup>shift</sup></code>.</p>

<B><A NAME="operator&gt;&gt;=">operator&gt;&gt;=</A></B>

<code><pre>unsigned_integer&amp; <b>unsigned_integer::operator&gt;&gt;=</b>(int);
integer&amp; <b>integer::operator&gt;&gt;=(int);</b></pre></code>

<p>If the value of <code>shift</code> is negative, the operators have the effect of <code>*this &lt;&lt;= -shift</code>. Otherwise, the operators set the value of <code>*this</code> to <code>*this / 2<sup>shift</sup></code>. The operators return a reference to <code>*this</code>.</p>

<B><A NAME="stream_operator&gt;&gt;">operator&gt;&gt;</A></B>

<code><pre>template &lt;class Elem, class Traits&gt;
    std::basic_istream&lt;Elem, Traits&gt;&amp; <b>operator&gt;&gt;</b>(std::basic_istream&lt;Elem, Traits&gt;&amp; strm, integer&amp; val);
template &lt;class Elem, class Traits&gt;
    std::basic_istream&lt;Elem, Traits&gt;&amp; <b>operator&gt;&gt;</b>(std::basic_istream&lt;Elem, Traits&gt;&amp; strm, unsigned_integer&amp; val);</pre></code>

<p>The operators have the effect of <code>{ std::string temp; strm &gt;&gt;
temp; val = temp; }</code>, and return a reference to <code>strm</code>.</p>

<B><A NAME="operator&amp;">operator&amp;</A></B>

<code><pre>unsigned_integer <b>operator&amp;</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operator returns an object whose value is the bitwise AND of the values
of <code>left</code> and <code>right</code>.</p>

<B><A NAME="operator&amp;=">operator&amp;=</A></B>

<code><pre>unsigned_integer&amp; <b>unsigned_integer::operator&amp;=</b>(const unsigned_integer&amp; right);</pre></code>

<p>The member operator sets the value of <code>*this</code> to the bitwise AND
of the values of <code>*this</code> and <code>right</code> and returns a
reference to <code>*this</code>.</p>

<B><A NAME="operator|">operator|</A></B>

<code><pre>unsigned_integer <b>operator|</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operator returns an object whose value is the bitwise inclusive OR of the
values of <code>left</code> and <code>right</code>.</p>

<B><A NAME="operator|=">operator|=</A></B>

<code><pre>unsigned_integer&amp; <b>unsigned_integer::operator|=</b>(const unsigned_integer&amp; right);</pre></code>

<p>The member operator sets the value of <code>*this</code> to the bitwise
inclusive OR of the values of <code>*this</code> and <code>right</code> and
returns a reference to <code>*this</code>.</p>

<B><A NAME="operator^">operator^</A></B>

<code><pre>unsigned_integer <b>operator^</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operator returns an object whose value is the bitwise exclusive OR of
the values of <code>left</code> and <code>right</code>.</p>

<B><A NAME="operator^=">operator^=</A></B>

<code><pre>unsigned_integer&amp; <b>unsigned_integer::operator^=</b>(const unsigned_integer&amp; right);</pre></code>

<p>The member operator sets the value of <code>*this</code> to the bitwise
exclusive OR of the values of <code>*this</code> and <code>right</code> and
returns a reference to <code>*this</code>.</p>

<B><A NAME="operator int">integral conversion operators</A></B>

<code><pre>explicit <b>integer::operator int</b>() const;
explicit <b>unsigned_integer::operator int</b>() const;
explicit <b>integer::operator unsigned</b>() const;
explicit <b>unsigned_integer::operator unsigned</b>() const;
explicit <b>integer::operator long</b>() const;
explicit <b>unsigned_integer::operator long</b>() const;
explicit <b>integer::operator unsigned long</b>() const;
explicit <b>unsigned_integer::operator unsigned long</b>() const;
explicit <b>integer::operator long long</b>() const;
explicit <b>unsigned_integer::operator long long</b>() const;
explicit <b>integer::operator unsigned long long</b>() const;
explicit <b>unsigned_integer::operator unsigned long long</b>() const;</pre></code>

<p>The operators return a value equal to the stored value of
<code>*this</code>.</p>

<B><A NAME="operator float">floating-point conversion operators</A></B>

<code><pre>explicit <b>integer::operator float</b>() const;
explicit <b>unsigned_integer::operator float</b>() const;
explicit <b>integer::operator double</b>() const;
explicit <b>unsigned_integer::operator double</b>() const;
explicit <b>integer::operator long double</b>() const;
explicit <b>unsigned_integer::operator long double</b>() const;</pre></code>

<p>The operators return a value that approximates the value stored in
<code>*this</code>.</p>

<B><A NAME="operator string">operator std::string</A></B>

<code><pre>explicit <b>integer::operator std::string</b>() const;
explicit <b>unsigned_integer::operator std::string</b>() const;</pre></code>

<p>The operator return <code>this->to_string()</code>.</p>

<B><A NAME="operator bool">operator bool</A></B>

<code><pre>explicit <b>integer::operator bool</b>() const;
explicit <b>unsigned_integer::operator bool</b>() const;</pre></code>

<p>The operator returns false only if <code>*this</code> is equal to
<code>0</code>.</p>

<B><A NAME="operator=">operator=</A></B>

<code><pre>integer&amp; <b>integer::operator=</b>(const integer&amp; right);
integer&amp; <b>integer::operator=</b>(integer&amp;&amp; right);
integer&amp; <b>integer::operator=</b>(const unsigned_integer&amp; right);
integer&amp; <b>integer::operator=</b>(unsigned_integer&amp;&amp; right);

unsigned_integer&amp; <b>unsigned_integer::operator=</b>(const unsigned_integer&amp; right);
unsigned_integer&amp; <b>unsigned_integer::operator=</b>(unsigned_integer&amp;&amp; right);</pre></code>

<p>The operators store the value of <code>right</code> into
<code>*this</code>.</p>

<B><A NAME="operator==">operator==</A></B>

<code><pre>bool <b>operator==</b>(const integer&amp; left, const integer&amp; right);
bool <b>operator==</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return <code>true</code> only if the value stored in <code>left</code> is equal to the value stored in <code>right</code>.</p>

<B><A NAME="operator!=">operator!=</A></B>

<code><pre>bool <b>operator!=</b>(const integer&amp; left, const integer&amp; right);
bool <b>operator!=</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return <code>!(left == right)</code>.</p>

<B><A NAME="operator&lt;">operator&lt;</A></B>

<code><pre>bool <b>operator&lt;</b>(const integer&amp; left, const integer&amp; right);
bool <b>operator&lt;</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return <code>true</code> if the value stored in <code>left</code> is less than the value stored in <code>right</code>.</p>

<B><A NAME="operator&lt;=">operator&lt;=</A></B>

<code><pre>bool <b>operator&lt;=</b>(const integer&amp; left, const integer&amp; right);
bool <b>operator&lt;=</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return <code>!(right &lt; left)</code>.</p>

<B><A NAME="operator&gt;">operator&gt;</A></B>

<code><pre>bool <b>operator&gt;</b>(const integer&amp; left, const integer&amp; right);
bool <b>operator&gt;</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return <code>right &lt; left</code>.</p>

<B><A NAME="operator&gt;=">operator&gt;=</A></B>

<code><pre>bool <b>operator&gt;=</b>(const integer&amp; left, const integer&amp; right);
bool <b>operator&gt;=</b>(const unsigned_integer&amp; left, const unsigned_integer&amp; right);</pre></code>

<p>The operators return <code>!(left &lt; right)</code>.</p>

<B><A NAME="pow">pow</A></B>

<code><pre>integer <b>pow</b>(const integer&amp; val, const unsigned_integer&amp; exp);
unsigned_integer <b>pow</b>(const unsigned_integer&amp; val, const unsigned_integer&amp; exp);

integer&amp; <b>integer::pow</b>(const unsigned_integer&amp; exp);
unsigned_integer&amp; <b>unsigned_integer::pow</b>(const unsigned_integer&amp; exp);</pre></code>

<p>The non-member functions return an object whose value is
<code>val<sup>exp</sup></code>. The member functions set the value of
<code>*this</code> to <code>*this<sup>exp</sup></code> and return
<code>*this</code>.</p>

<B><A NAME="powmod">powmod</A></B>

<code><pre>integer <b>powmod</b>(const integer&amp; val, const unsigned_integer&amp; exp, const unsigned_integer&amp; m);
unsigned_integer <b>powmod</b>(const unsigned_integer&amp; val, const unsigned_integer&amp; exp, const unsigned_integer&amp; m);

integer&amp; <b>integer::powmod</b>(const unsigned_integer&amp; exp, const unsigned_integer&amp; m);
unsigned_integer&amp; <b>unsigned_integer::powmod</b>(const unsigned_integer&amp; exp, const unsigned_integer&amp; m);</pre></code>

<p>The non-member functions return an object whose value is
<code>val<sup>exp</sup> mod m</code>. The member functions set the value of
<code>*this</code> to <code>*this<sup>exp</sup> mod m</code> and return
<code>*this</code>.</p>

<B><A NAME="probable_prime">probable_prime</A></B>

<code><pre>template &lt;class Engine&gt;
    unsigned_integer <b>probable_prime</b>(unsigned length, int certainty, Engine eng);</pre></code>

<p>The template function returns an object that holds a random value of <code>length</code> bits that is probably prime with a probability of <code>1 - 2<sup>-certainty/2</sup></code> using <code>eng</code> as a source of randomness.</p>

<B><A NAME="random">random</A></B>

<code><pre>template &lt;class Engine&gt;
    unsigned_integer <b>random</b>(unsigned, Engine);</code></pre>

<p>The template function returns an object that holds a random value of <code>length</code> bits using <code>eng</code> as a source of randomness.</p>

<B><A NAME="set">set</A></B>

<code><pre>void <b>unsigned_integer::set</b>(size_t pos, bool val = true);</pre></code>

<p>The member function sets the bit at position <code>pos</code> in the stored
value to <code>val</code>.</p>

<B><A NAME="sqr">sqr</A></B>

<code><pre>integer <b>sqr</b>(const integer&amp; val);
unsigned_integer <b>sqr</b>(const unsigned_integer&amp; val);

integer&amp; <b>integer::sqr</b>();
unsigned_integer&amp; <b>unsigned_integer::sqr</b>();</pre></code>

<p>The non-member functions return an object whose value is <code>val *
val</code>. The member functions set the value of <code>*this</code> to
<code>*this * *this</code> and return a reference to <code>*this</code>.</p>

<B><A NAME="sqrt">sqrt</A></B>

<code><pre>integer <b>sqrt</b>(const integer&amp;);
unsigned_integer <b>sqrt</b>(const unsigned_integer&amp;);

integer&amp; <b>integer::sqrt</b>();
unsigned_integer&amp; <b>unsigned_integer::sqrt</b>();</pre></code>

<p>The non-member functions return an object whose value is the square root of
the value held by <code>val</code>, discarding any fractional part. The member
functions set the value of <code>*this</code> to the square root of the value
held by <code>*this</code>, discarding any fractional part, and return a
reference to <code>*this</code>.</p>

<B><A NAME="sqrtrem">sqrtrem</A></B>

<code><pre>std::pair&lt;integer, integer&gt; <b>sqrtrem</b>(const integer&amp; val);
std::pair&lt;unsigned_integer, unsigned_integer&gt; <b>sqrtrem</b>(const unsigned_integer&amp; val);

integer <b>integer::sqrtrem</b>();
unsigned_integer <b>unsigned_integer::sqrtrem</b>();</pre></code>

<p>The non-member functions return an instantiation of <code>std::pair</code>;
its <code>first</code> field holds a value equal to the square root of
<code>val</code>, discarding any fractional part; its <code>second</code> field
holds the difference between <code>val</code> and the square of the value stored
in <code>first</code>. The member functions set <code>*this</code> to the square
root of <code>*this</code>, discarding any fractional part; the functions return
an object whose value is the difference between the original value of
<code>*this</code> and the square of the new value of <code>*this</code>.</p>

<B><A NAME="swap">swap</A></B>

<code><pre>void <b>swap</b>(integer&amp; left, integer&amp; right);
void <b>swap</b>(unsigned_integer&amp; left, unsigned_integer&amp; right);

void <b>integer::swap</b>(integer&amp; right);
void <b>unsigned_integer::swap</b>(unsigned_integer&amp; right);</pre></code>

<p>The non-member functions swap the stored values of <code>left</code> and <code>right</code>. The non-member functions swap the stored values of <code>*this</code> and <code>right</code>.</p>

<B><A NAME="test">test</A></B>

<code><pre>bool <b>unsigned_integer::test</b>(size_t pos) const;</pre></code>

<p>The member function returns <code>true</code> only if the bit at position <code>pos</code> in the stored value is non-zero.</p>

<B><A NAME="to_string">to_string</A></B>

<code><pre>std::string <b>integer::to_string</b>(int base = 10) const;
std::string <b>unsigned_integer::to_string</b>(int base = 10) const;</pre></code>

<p>The member functions return a string representation of the value stored in
<code>*this</code>, using <code>base</code> as the radix.</p>

<B><A NAME="unsigned_integer::unsigned_integer">unsigned_integer::unsigned_integer</A></B>

<code><pre><b>unsigned_integer::unsigned_integer</b>();

<b>unsigned_integer::unsigned_integer</b>(char val);
<b>unsigned_integer::unsigned_integer</b>(signed char val);
<b>unsigned_integer::unsigned_integer</b>(unsigned char val);
<b>unsigned_integer::unsigned_integer</b>(short val);
<b>unsigned_integer::unsigned_integer</b>(unsigned short val);
<b>unsigned_integer::unsigned_integer</b>(int val);
<b>unsigned_integer::unsigned_integer</b>(unsigned int val);
<b>unsigned_integer::unsigned_integer</b>(long val);
<b>unsigned_integer::unsigned_integer</b>(unsigned long val);
<b>unsigned_integer::unsigned_integer</b>(long long val);
<b>unsigned_integer::unsigned_integer</b>(unsigned long long val);

explicit <b>unsigned_integer::unsigned_integer</b>(float val);
explicit <b>unsigned_integer::unsigned_integer</b>(double val);
explicit <b>unsigned_integer::unsigned_integer</b>(long double val);

<b>unsigned_integer::unsigned_integer</b>(const std::string&amp; val, int base = 10);
<b>unsigned_integer::unsigned_integer</b>(std::initializer_list&lt;<i>unspecified</i>&gt; list);

<b>unsigned_integer::unsigned_integer</b>(const unsigned_integer&amp; other);
<b>unsigned_integer::unsigned_integer</b>(unsigned_integer&amp;&amp; other);
explicit <b>unsigned_integer::unsigned_integer</b>(const integer&amp; other);
explicit <b>unsigned_integer::unsigned_integer</b>(integer&amp;&amp; other);</pre></code>

<p>The default constructor constructs an object whose value is
<code>0</code>.</p>

<p>The constructors that take integral arguments construct objects whose value
is <code>val</code>.</p>

<p>The constructors that take floating-point arguments construct objects whose
value is an approximation to <code>val</code>, accurate to at least
<code>std::numeric_limits<floating-point-type>::digits</code>.</p>

<p>The constructor that takes a <code>string</code> constructs an object whose
value is the value represented by the string object. The string object shall
have the form required for the string argument to the function
<code>std::strtol</code> with a radix of <code>base</code>, and shall be
interpreted as if by <code>std::strtol(str.c_str(), 0, base)</code>, except that
the resulting value can never be outside the range of representable values.</p>

<p>The constructor that takes an initializer_list constructs an object whose
stored value is equal to the elements of the initializer_list treated as a
series of unsigned 32-bit digits with the leftmost digit being most significant.
For example, the initializer list <code>{ 0xFE, 0xF0, 0xAA, 0x31 }</code>
represents the value <code>0xFE * 32<sup>3</sup> + 0xF0 * 32<sup>2</sup> + 0xAA
* 32<sup>1</sup> + 0x31 * 32<sup>0</sup></code>.</p>

<p>The copy and move constructors construct objects with the same value as
<code>other</code>.</p>

</BODY></HTML>
