<HTML><HEAD><TITLE>N3542, Proposal for Unbounded-Precision Integer Types</TITLE></HEAD><BODY>

<CENTER>
<H1><A NAME="N3542, 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; N3542</TD>
</TR>
<TR>
<TD ALIGN="RIGHT"><B><I>Date:</I></B></TD>
<TD>&nbsp; 2013-03-18</TD>
</TR>
<TR>
<TD ALIGN="RIGHT"><B><I>Revises:</I></B></TD>
<TD>&nbsp; N3417=12-0107</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="What&rsquo;s New in this Revision">What&rsquo;s New in this Revision</A></H2>

<ul>
<li>removed the number-theoretic functions from <code>unsigned_integer</code>
and <code>integer</code>;</li>
<li>removed the support for random numbers from <code>unsigned_integer</code>;</li>
<li>added <code>integer_data_proxy</code> for manipulating the internal
representation of an <code>integer</code> object to provide advanced users
with hooks for extended operations;</li>
<li>renamed <code>unsigned_integer</code> to <code>bits</code> and gave it
the same interface as <code>std::bitset</code>.
</ul>

<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 use in areas that demand such types. Since
there is a potentially unbounded list of operations that could be useful
in applications that need unbounded-precision integer types, it is not
practical to provide every useful operation. This proposal presents a small
set of required operations and provides a facility for users to write their own
extensions. </p>

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

<p>This paper proposes two unbounded-precision integer types.
The type
<code>integer</code> represents signed integer values.
The type
<code>bits</code> represents an unbounded set of bit values.</p>


<p>To support interoperability, objects of either type 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;

    bits b = 0xFF;
    bits c = b & 0xAA;</pre></code>

<p>Converting a negative number to an object of type
<code>bits</code> sets the number to the complement of
this initializer, so this code just works:</p>

<code><pre>    bits b = -3; // sets <code>b</code> to ...11111100</pre></code>

<p>This is easily implemented by storing a finite set of 1 bits (in this case, 0x03) and using a flag
to indicate whether the actual value is represented by that set of bits or by
its complement.</p>

<p>As currently specified, neither <code>integer</code> nor
<code>bits</code> provides overloaded operators that take standard integer
types. When an operation is applied to a standard integer type and an
<code>integer</code> object or a <code>bits</code> object, 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>integer</code>
or <code>bits</code> object, and using heap storage when needed for larger
values. This greatly simplifies the interface specification.</p>

<p>Objects of these types can 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>Objects of type <code>integer</code> can also be constructed from values of floating-point
types.</p>

<p>Values of type <code>integer</code> and of type <code>bits</code> can be
freely inter-converted.</p>

<p>Bit manipulations on <code>bits</code> objects treat the value as
having an unbounded number of bits above the highest bit stored in the
object. As a result, the usual bit operations, &amp;, |, and ^, can be applied to
values of different sizes. Further, <code>std::seminumeric::bits</code> can be used as
a replacement for <code>std::bitset</code>  when limiting the object
to a fixed number of bits is undesirable.</p>

<H2><A NAME="Issues">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><i>[resolved in N3542]</i> <b>Policy for out-of-bounds subtraction</b> -- subtracting an
<code>bits</code> value from a smaller value doesn&rsquo;t have any specified semantics in
this paper. This should probably throw an exception. <i>Resolution:</i> removed arithmetic operations
on <code>bits</code> objects.</li>

<li><i>[resolved in N3542]</i> <b>Policy for out-of-bounds constructor arguments</b> -- constructing an
<code>bits</code> object from a negative value doesn&rsquo;t have
any specified semantics in this paper. This should probably throw an
exception. <i>Resolution:</i> negative values produce complemented bit sets.</li>

<li><b>Policy for lossy conversions</b> -- converting an
<code>bits</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>

<li><i>[new in N3417]</i> <b>Rvalue overloads for arithmetic operations</b> (Joe Gottman) -- many of the
operations on the unbounded-precision types can be made more efficient by providing
overloaded versions that take rvalue references. For example:

<pre><code>integer operator+(integer&& lhs, const integer& rhs) {
    return std::move(lsh += rhs);
}</code></pre>
</li>

<li><i>[new in N3417]</i> <b>Functions for controlling when and how allocations occur</b> (Joe Gottman) --
just as with <code>std::string</code>, many operations can be made faster by pre-allocating enough
memory to hold the expected result. In some cases the desired capacity is best expressed in bits and
in some cases in decimal digits, so the suggestion is to offer both:

<pre><code>size_t capacity_in_bits() const;   // The number of bits the object can hold without reallocation.
size_t capacity_in_digits() const; // The largest number n such that the object can hold n decimal
                                   // digits without reallocation.
void reserve_bits(size_t n);       // Postcondition: capacity_in_bits() >= n.
void reserve_digits(size_t n);     // Postcondition: capacity_in_digits() >= n.
void shrink_to_fit()();            // A non-binding request to reduce memory usage.</code></pre>
</li>

<li><i>[new in N3417]</i> <b>Support user-defined literals</b> (Alisdair
Meredith, Marc Glisse) -- obviously useful, but users might expect them to be
<code>constexpr</code>, which they cannot, in general, be, because they need
to allocate memory.</li>

<li><i>[new in N3417]</i> <b>Add <code>noexcept</code> specifications as appropriate</b>
(Alisdair Meredith) -- there are several that are obvious. In addition, if we require the
small-object optimization, some or all of the constructors that take integral types can be
<code>noexcept</code>.</li>

<li><i>[new in N3417]</i> <b>Add <code>constexpr</code> specifications as appropriate</b>
(Alisdair Meredith) -- although most functions can allocate memory, there are a few that
could be marked <code>constexpr</code>. It&rsquo;s not clear how useful this would be.</li>

<li><i>[new in N3417]</i> <b>Why do the bitshift operators take an <code>int</code> argument?</b>
(Alisdiar Meredith, Marc Glisse) -- this may be limiting, for example, on a 64-bit OS with a 32-bit
<code>int</code> type. <code>size_t</code> or <code>ptrdiff_t</code> may be a better choice.</li>

<li><i>[resolved in N3542]</i> <i>[new in N3417]</i> <b>Why just one string type
for string conversions?</b> (Alisdair Meredith) -- there are four standard
<code>basic_string</code> typedefs. <i>Resolution:</i> string operations are now fully
templated.</li>

<li><i>[new in N3417]</i> <b>Converting to a string could use a mechanism for providing an allocator</b>
(Alisdair Meredith) -- for example,

<pre><code>template&lt;class charT, class Traits, class Alloc&gt;
void bits::load(basic_string&lt;charT, Traits, Alloc&gt;&);</code></pre></li>

<li><i>[resolved in N3542]</i> <i>[new in N3417]</i> <b>Consider extending interface to more
fully support dynamic bitsets</b> (Alisdair Meredith) -- or maybe that should be a separate
class, with shared implementation. <i>Resolution</i>: changed <code>unsigned_integer</code>
to <code>bits</code> with same interface as <code>std::bitset</code>.</li>

<li><i>[resolved in N3542]</i> <i>[resolved in N3542]</i> <i>[new in N3417]</i> <b><code>powmod</code>
should be specified to run in constant time with identical cache access patterns
for arguments of the same size</b> (Jack Lloyd) -- this is important for cryptographic
purposes, to avoid side-channel attacks. <i>Resolution:</i> removed <code>powmod</code>
and provided a do-it-yourself solution.</li>

<li><i>[new in N3417]</i> <b>Need functions to interconvert with byte arrays</b> (Jack Lloyd) --
quite a common need in cryptographic operations.</li>

<li><i>[resolved in N3542]</i> <i>[new in N3417]</i> <b>Add a typedef that gives the
underlying representation type and an accessor that provides a pointer to the internal
representation.</b> (Jack Lloyd) -- some common cryptographic algorithms can&rsquo;t
be implemented with the interface in the proposal; adding these accessors makes it
possible to implement them. <i>Resolution:</i> added class <code>integer_data_proxy</code>.</li>

<li><i>[resolved in N3542]</i> <i>[resolved in N3542]</i> <i>[new in N3417]</i> <b>Is
the <code>unsigned_integer</code> type necessary?</b> (Marc Glisse) -- if this is there
to support bit manipulation, why not just specify those operations as undefined for
negative numbers. <i>Resolution:</i> removed <code>unsigned_integer</code> and added
<code>bits</code>, whose sole purpose is bit manipulation.</li>

<li><i>[new in N3417]</i> <b>Rounding of divisions and right shifts needs to be specified.</b>
(Marc Glisse) -- even if it&rsquo;s obvious. Also, does <code>mod</code> return negative values?</li>

<li><i>[resolved in N3542]</i> <i>[new in N3417]</i> <b>The constructor that takes a
<code>string</code> should be explicit.</b> (Marc Glisse) <i>Resolution:</i> done.</li>

<li><i>[resolved in N3542]</i> <i>[new in N3417]</i> <b>Consider making
<code>to_string()</code> a non-member function.</b> (Daniel Kr&#xFC;gler)
-- this would be a good match with the existing <code>to_string</code> functions.
<i>Resolution:</i> done for <code>integer</code>; <code>bits</code> has it as a
member to match <code>std::bitset</code>.</li>

<li><i>[resolved in N3542]</i> <i>[new in N3417]</i> <b>Consider removing
<code>explicit operator std::string() const</code>.</b> (Daniel Kr&#xFC;gler,
Jens Maurer) -- <code>to_string()</code> is sufficient. <i>Resolution:</i> done.</li>

</ol>

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

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

/* class integer */

    class <A HREF="#class_integer">integer</A>;
    class <A HREF="#class_integer_data_proxy">integer_data_proxy</A>;

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

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

    // arithmetic operations
    integer <A HREF="#integer::operator+">operator+</A>(const integer&amp; lhs, const integer&amp; rhs);
    integer <A HREF="#integer::operator-">operator-</A>(const integer&amp; lhs, const integer&amp; rhs);
    integer <A HREF="#integer::operator*">operator*</A>(const integer&amp; lhs, const integer&amp; rhs);
    integer <A HREF="#integer::operator/">operator/</A>(const integer&amp; lhs, const integer&amp; rhs);
    integer <A HREF="#integer::operator%">operator%</A>(const integer&amp; lhs, const integer&amp; rhs);

    std::pair&lt;integer, integer&gt; <A HREF="#integer::div">div</A>(const integer&amp; lhs, const integer&amp; rhs);

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

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

    // numeric operations
    integer <A HREF="#integer::sqr">sqr</A>(const integer&amp; val);
    integer <A HREF="#integer::sqrt">sqrt</A>(const integer&amp; val);
    integer <A HREF="#integer::pow">pow</A>(const integer&amp; val, const integer&amp; exp);

    // conversions
    std::string <A HREF="#integer::to_string">to_string</A>(const integer& val, int radix = 16);

    // I/O operations
    template &lt;class CharT, class Traits&gt;
        std::basic_ostream&lt;CharT, Traits&gt;&amp; <A HREF="#integer::operator&lt;&lt;">operator&lt;&lt;</A>(
            std::basic_ostream&lt;CharT, Traits&gt;&amp; str, const integer&amp; val);
    template &lt;class CharT, class Traits&gt;
        std::basic_istream&lt;CharT, Traits&gt;&amp; <A HREF="#integer::operator&gt;&gt;">operator&gt;&gt;</A>(
            std::basic_istream&lt;CharT, Traits&gt;&amp; str, integer&amp; val);

/* class bits */

    class <A HREF="#class_bits">bits</A>;

    void <A HREF="#bits::swap">swap</A>(bits&amp; lhs, bits&amp; rhs);

    // logical operations
    bits <A HREF="#bits::operator&amp;">operator&amp;</A>(const bits&amp; lhs, const bits&amp; rhs);
    bits <A HREF="#bits::operator|">operator|</A>(const bits&amp; lhs, const bits&amp; rhs);
    bits <A HREF="#bits::operator^">operator^</A>(const bits&amp; lhs, const bits&amp; rhs);

    // I/O operations
    template &lt;class CharT, class Traits&gt;
        std::basic_ostream&lt;CharT, Traits&gt;&amp; <A HREF="#bits::stream_operator&lt;&lt;">operator&lt;&lt;</A>(
            std::basic_ostream&lt;CharT, Traits&gt;&amp; str, const bits&amp; val);
    template &lt;class CharT, class Traits&gt;
        std::basic_istream&lt;CharT, Traits&gt;&amp; <A HREF="#bits::stream_operator&gt;&gt;">operator&gt;&gt;</A>(
            std::basic_istream&lt;CharT, Traits&gt;&amp; str, bits&amp; val);

} /* namespace seminumeric */

template &lt;&gt; class <b>numeric_limits&lt;seminumeric::integer&gt;</b>;

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

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

<pre><code>class <B>integer</B> {
public:

    // constructors
    <A HREF="#integer::integer">integer</A>();

    <A HREF="#integer::integer">integer</A>(char val);
    <A HREF="#integer::integer">integer</A>(signed char val);
    <A HREF="#integer::integer">integer</A>(unsigned char val);
    <A HREF="#integer::integer">integer</A>(short val);
    <A HREF="#integer::integer">integer</A>(unsigned short val);
    <A HREF="#integer::integer">integer</A>(int val);
    <A HREF="#integer::integer">integer</A>(unsigned val);
    <A HREF="#integer::integer">integer</A>(long val);
    <A HREF="#integer::integer">integer</A>(unsigned long val);
    <A HREF="#integer::integer">integer</A>(long long val);
    <A HREF="#integer::integer">integer</A>(unsigned long long val);

    <A HREF="#integer::integer">integer</A>(float val);
    <A HREF="#integer::integer">integer</A>(double val);
    <A HREF="#integer::integer">integer</A>(long double val);

    <A HREF="#integer::integer">integer</A>(std::initializer_list&lt;uint_least32_t&gt; init);

    template &lt;class CharT, class Traits, class Alloc&gt;
        explicit <A HREF="#integer::integer">integer</A>(const std::basic_string&lt;CharT, Traits, Alloc&gt;&amp; str);

    <A HREF="#integer::integer">integer</A>(const integer&amp; other);
    <A HREF="#integer::integer">integer</A>(integer&amp;&amp; other);
    explicit <A HREF="#integer::integer">integer</A>(const bits&amp; val);
    explicit <A HREF="#integer::integer">integer</A>(bits&amp;&amp; val);

    // assignment and swap
    integer&amp; <A HREF="#integer::operator=">operator=</A>(const integer&amp; rhs);
    integer&amp; <A HREF="#integer::operator=">operator=</A>(integer&amp;&amp; rhs);
    integer&amp; <A HREF="#integer::operator=">operator=</A>(const bits&amp; rhs);
    integer&amp; <A HREF="#integer::operator=">operator=</A>(bits&amp;&amp; rhs);
    void <A HREF="#integer::swap">swap</A>(integer&amp; other);

    // conversions
    explicit <A HREF="#integer::operator long long">operator long long</A>() const;
    explicit <A HREF="#integer::operator unsigned long long">operator unsigned long long</A>() const;
    explicit <A HREF="#integer::operator long double">operator long double</A>() const;
    explicit <A HREF="#integer::operator bool">operator bool</A>() const;

    // comparisons
    int <A HREF="#integer::compare">compare</A>(const integer&amp; rhs) const;

    // arithmetic operations
    integer&amp; <A HREF="#integer::operator+=">operator+=</A>(const integer&amp; rhs);
    integer&amp; <A HREF="#integer::operator-=">operator-=</A>(const integer&amp; rhs);
    integer&amp; <A HREF="#integer::operator*=">operator*=</A>(const integer&amp; rhs);
    integer&amp; <A HREF="#integer::operator/=">operator/=</A>(const integer&amp; rhs);
    integer&amp; <A HREF="#integer::operator%=">operator%=</A>(const integer&amp; rhs);

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

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

    integer&amp; <A HREF="#integer::abs">abs</A>();
    integer&amp; <A HREF="#integer::negate">negate</A>();
    integer <A HREF="#integer::operator+">operator+</A>() const;
    integer <A HREF="#integer::operator-">operator-</A>() const;

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

    // numeric operations
    integer&amp; <A HREF="#integer::sqr">sqr</A>();
    integer&amp; <A HREF="#integer::sqrt">sqrt</A>();
    integer&amp; <A HREF="#integer::pow">pow</A>(const integer&amp; exp);

    // observers
    bool <A HREF="#integer::is_odd">is_odd</A>() const;

    // accessors
    integer_data_proxy <A HREF="#integer::get_data_proxy">get_data_proxy</A>();

};
</code></pre>

<p>The class describes an object that manages an unbounded-precision signed integral type
that can be used in most contexts where an <code>int</code> could be used.</p>

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

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

<p>The first function returns an object that holds the absolute value lf
other<code></code>. The second function sets the stored value of
<code>*this</code> to its absolute value and returns a reference to
<code>*this</code>.</p>

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

<code><pre>int <b>integer::compare</b>(const integer&amp; right) const;</pre></code>

<p>The member function returns a value less than 0 if <code>*this</code> is less than
<code>rhs</code>, 0 if <code>*this</code> is equal to <code>rhs</code>, and greater than 0
if <code>*this</code> is greater than <code>rhs</code>.</p>

<B><A NAME="integer::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;integer, integer&gt; <b>integer::div</b>(const 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="integer::get_data_proxy">get_data_proxy</A></B>

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

<p>The member function returns an object of type
<A HREF="#class_integer_data_proxy">integer_data_proxy</A>
that can be used to examine and modify the internal storage of
<code>*this</code>. If an object of type <code>integer_data_proxy</code> that refers
to <code>*this</code> exists at the time of a call to this function, the function
throws an exception object of type <code>std::runtime_error</code>.</p>

<B><A NAME="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);

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

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

template&lt;class CharT, class Traits, class Alloc&gt;
    explicit <b>integer::integer</b>(const std::basic_string&lt;CharT, Traits, Alloc&gt;&amp; str);

<b>integer::integer</b>(const integer&amp; other);
<b>integer::integer</b>(integer&amp;&amp; other);
<b>integer::integer</b>(const bits&amp; other);
<b>integer::integer</b>(bits&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="integer::is_odd">is_odd</A></B>

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

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

<B><A NAME="integer::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="integer::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 bits&amp; right);
integer&amp; <b>integer::operator=</b>(bits&amp;&amp; right);</pre></code>

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

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

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

<p>The first operator returns an object whose value is the sum of the values of
<code>left</code> and <code>right</code>. The second operator returns a copy of
<code>*this</code>.</p>

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

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

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

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

<code><pre>integer&amp; <b>integer::operator++</b>();
integer <b>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 operator returns <code>*this</code>. The
second operator returns an object whose value is the value stored in
<code>*this</code> prior to the increment.</p>

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

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

<p>The first operator returns an object whose value is the difference between the
values of <code>left</code> and <code>right</code>. The second operator returns
an object whose value is the negation of the value of <code>*this</code>.</p>

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

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

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

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

<code><pre>integer&amp; <b>integer::operator--</b>();
integer <b>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 operator returns <code>*this</code>. The
second operator returns an object whose value is the value stored in
<code>*this</code> prior to the decrement.</p>

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

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

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

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

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

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

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

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

<p>The operator returns 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="integer::operator/=">operator/=</A></B>

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

<p>The member operator sets 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 returns a reference to
<code>*this</code>.</p>

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

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

<p>The operator returns 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="integer::operator%=">operator%=</A></B>

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

<p>The member operator sets the stored value of <code>*this</code> to the
remainder of <code>*this</code> divided by the value of <code>right</code> and
returns a reference to <code>*this</code>.</p>

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

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

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

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

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

<p>If the value of <code>shift</code> is negative, the operator has the
effect of <code>*this &lt;&lt;= -shift</code>. Otherwise, the operator
sets the value of <code>*this</code> to <code>*this / 2<sup>shift</sup></code>.
The operator returns a reference to <code>*this</code>.</p>

<B><A NAME="integer::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);</pre></code>

<p>The operator has the effect of <code>{ std::string temp; strm &gt;&gt;
temp; val = temp; }</code>. It returns a reference to <code>strm</code>.</p>

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

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

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

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

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

<p>If the value of <code>shift</code> is negative, the operator has the effect
of <code>*this &gt;&gt;= -shift</code>. Otherwise, the operator sets the value
of <code>*this</code> to <code>*this * 2<sup>shift</sup></code>. The operator
returns a reference to <code>*this</code>.</p>

<B><A NAME="integer::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);</pre></code>

<p>The operator has the effect of <code>strm &lt;&lt; val.to_string()</code>.
It returns a reference to <code>strm</code>.</p>

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

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

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

<B><A NAME="integer::operator long double">operator long double</A></B>

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

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

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

<code><pre>explicit <b>bits::operator long long</b>() const;</pre></code>

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

<B><A NAME="integer::operator unsigned long long">operator unsigned long long</A></B>

<code><pre>explicit <b>bits::operator unsigned long long</b>() const;</pre></code>

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

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

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

<p>The operator returns <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="integer::operator!=">operator!=</A></B>

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

<p>The operator returns <code>!(left == right)</code>.</p>

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

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

<p>The operator returns <code>right &lt; left</code>.</p>

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

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

<p>The operator returns <code>!(left &lt; right)</code>.</p>

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

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

<p>The operator return <code>true</code> only if <code>left.compare(right)</code> returns -1.</p>

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

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

<p>The operator returns <code>!(right &lt; left)</code>.</p>

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

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

<p>The non-member function returns an object whose value is
<code>val<sup>exp</sup></code>. The member function sets the value of
<code>*this</code> to <code>*this<sup>exp</sup></code> and returns
<code>*this</code>. <i>Requires</i>: <code>0 <= exp</code>.</p>

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

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

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

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

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

<p>The non-member function returns an object whose value is the square root of
the value held by <code>val</code>, discarding any fractional part. The member
function sets the value of <code>*this</code> to the square root of the value
held by <code>*this</code>, discarding any fractional part, and returns a
reference to <code>*this</code>. <i>Requires</i>: <code>0 <= exp</code>.</p>

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

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

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

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

<code><pre>std::string <b>integer::to_string</b>(int radix = 16) const;</pre></code>

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

<H2><A NAME="class_integer_data_proxy">Class <code>integer_data_proxy</code></A></H2>

<pre><code>class <B>integer_data_proxy</B> {

    // type names
    typedef <i>unspecified</i> <A HREF="#integer_data_proxy::data_type">data_type</A>;
    typedef <i>unspecified</i> <A HREF="#integer_data_proxy::arithmetic_type">arithmetic_type</A>;
    typedef <i>unspecified</i> <A HREF="#integer_data_proxy::uarithmetic_type">uarithmetic_type</A>;
    typedef <i>unspecified</i> <A HREF="#integer_data_proxy::size_type">size_type</A>;
    typedef <i>unspecified</i> <A HREF="#integer_data_proxy::iterator">iterator</A>;
    typedef <i>unspecified</i> <A HREF="#integer_data_proxy::const_iterator">const_iterator</A>;
    typedef <i>unspecified</i> <A HREF="#integer_data_proxy::reverse_iterator">reverse_iterator</A>;
    typedef <i>unspecified</i> <A HREF="#integer_data_proxy::const_reverse_iterator">const_reverse_iterator</A>;

    // constructors
    <A HREF="#integer_data_proxy::integer_data_proxy">integer_data_proxy</A>(const integer_data_proxy&amp; other) = delete;
    <A HREF="#integer_data_proxy::integer_data_proxy">integer_data_proxy</A>(integer_data_proxy&amp;&amp; other) = default;

    // assignment
    integer_data_proxy&amp; <A HREF="#integer_data_proxy::operator=">operator=</A>(const integer_data_proxy&amp; rhs) = delete;
    integer_data_proxy&amp; <A HREF="#integer_data_proxy::operator=">operator=</A>(integer_data_proxy&amp;&amp; rhs) = default;

    // iterators
    iterator <A HREF="#integer_data_proxy::begin">begin</A>();
    const_iterator <A HREF="#integer_data_proxy::begin">begin</A>() const;
    iterator <A HREF="#integer_data_proxy::end">end</A>();
    const_iterator <A HREF="#integer_data_proxy::end">end</A>() const;
    reverse_iterator <A HREF="#integer_data_proxy::rbegin">rbegin</A>();
    const_reverse_iterator <A HREF="#integer_data_proxy::rbegin">rbegin</A>() const;
    reverse_iterator <A HREF="#integer_data_proxy::rend">rend</A>();
    const_reverse_iterator <A HREF="#integer_data_proxy::rend">rend</A>() const;
    const_iterator <A HREF="#integer_data_proxy::cbegin">cbegin</A>() const;
    const_iterator <A HREF="#integer_data_proxy::cend">cend</A>() const;
    const_reverse_iterator <A HREF="#integer_data_proxy::crbegin">crbegin</A>() const;
    const_reverse_iterator <A HREF="#integer_data_proxy::crend">crend</A>() const;

    // capacity
    size_type <A HREF="#integer_data_proxy::size">size</A>() const;
    void <A HREF="#integer_data_proxy::resize">resize</A>(size_type sz);

    // element access
    data_type <A HREF="#integer_data_proxy::operator[]">operator[]</A>(size_type n) const;
    data_type&amp; <A HREF="#integer_data_proxy::operator[]">operator[]</A>(size_type n);

};
</code></pre>

<p>The class describes an object that can be used to examine and
modify the internal representation of an object of type
<code>integer</code>. This allows advanced users to portably implement
algorithms that are not provided natively.</p>

<p>There can be only one <code>integer_data_proxy</code> object
associated with a particular <code>integer</code> object at any given
time; that object is obtained by calling the <code>get_data_proxy</code> member
function on the <code>integer</code> object. The resulting object can
be moved but not copied.</p>

<B><A NAME="integer_data_proxy::arithmetic_type">arithmetic_type</A></B>

<code><pre>typedef <i>unspecified</i> <b>integer_data:proxy::arithmetic_type</b>;</pre></code>

<p>The typedef defines a synonym for a signed arithmetic type with at least twice
as many bits as the internal storage type.</p>

<B><A NAME="integer_data_proxy::begin">begin</A></B>

<code><pre>iterator <b>integer_data_proxy::begin</b>();</pre></code>

<p>The member function returns an iterator object such that the iterators <code>[begin(), end())</code>
point to the internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::cbegin">cbegin</A></B>

<code><pre>const_iterator <b>integer_data_proxy::cbegin</b>() const;</pre></code>

<p>The member function returns an iterator object such that the iterators <code>[cbegin(), cend())</code>
point to the internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::cend">cend</A></B>

<code><pre>const_iterator <b>integer_data_proxy::cend</b>() const;</pre></code>

<p>The member function returns an iterator object such that the iterators <code>[cbegin(), cend())</code>
point to the internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::const_iterator">const_iterator</A></B>

<code><pre>typedef <i>unspecified</i> <b>integer_data_proxy::const_iterator</b>;</pre></code>

<p>The typedef defines a synonym for an iterator that can be used to access but not
modify internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::const_reverse_iterator">const_reverse_iterator</A></B>

<code><pre>typedef <i>unspecified</i> <b>integer_data_proxy::const_reverse_iterator</b>;</pre></code>

<p>The typedef defines a synonym for a reverse iterator that can be used to access but not
modify internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::crbegin">crbegin</A></B>

<code><pre>const_reverse_iterator <b>integer_data_proxy::crbegin</b>() const;</pre></code>

<p>The member function returns a reverse iterator object such that the iterators <code>[crbegin(), crend())</code>
point to the internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::crend">crend</A></B>

<code><pre>const_reverse_iterator <b>integer_data_proxy::crend</b>() const;</pre></code>

<p>The member function returns a reverse iterator object such that the iterators <code>[crbegin(), crend())</code>
point to the internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::data_type">data_type</A></B>

<code><pre>typedef <i>unspecified</i> <b>integer_data_proxy::data_type</b>;</pre></code>

<p>The typedef defines a synonym for the type of the <code>integer</code> object's internal data elements.</p>

<B><A NAME="integer_data_proxy::end">end</A></B>

<code><pre>iterator <b>integer_data_proxy::end</b>();</pre></code>

<p>The member function returns an iterator object such that the iterators <code>[begin(), end())</code>
point to the internal data elements of the <code>integer</code> object.</p>

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

<code><pre>integer_data_proxy::integer_data_proxy(const integer_data_proxy&amp;) = delete; 
integer_data_proxy::integer_data_proxy(integer_data_proxy&amp;&amp;) = delete;</pre></code>

<p>The copy constructor and move constructor are deleted.</p>

<B><A NAME="integer_data_proxy::iterator">iterator</A></B>

<code><pre>typedef <i>unspecified</i> <b>integer_data_proxy::iterator</b>;</pre></code>

<p>The typedef defines a synonym for an iterator that can be used to access
internal data elements of the <code>integer</code> object.</p>

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

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

<p>The copy assignment and move assignment operators are deleted.</p>

<B><A NAME="integer_data_proxy::operator[]">operator[]</A></B>

<code><pre>data_type <b>integer_data_proxy::operator[]</b>(size_type n) const;
data_type&amp; <b>integer_data_proxy::operator[]</b>(size_type n);</pre></code>

<p>The first member function returns the value of the internal data element at
index <code>n</code>. The second member function returns a reference to the
value of the internal data element at index <code>n</code>.</p>

<B><A NAME="integer_data_proxy::rbegin">rbegin</A></B>

<code><pre>const_reverse_iterator <b>integer_data_proxy::rbegin</b>() const;
reverse_iterator <b>integer_data_proxy::rbegin</b>();</pre></code>

<p>The member functions return a reverse iterator object such that the iterators <code>[crbegin(), crend())</code>
point to the internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::rend">rend</A></B>

<code><pre>const_reverse_iterator <b>integer_data_proxy::rend</b>() const;
reverse_iterator <b>integer_data_proxy::rend</b>();</pre></code>

<p>The member functions return a reverse iterator object such that the iterators <code>[crbegin(), crend())</code>
point to the internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::resize">resize</A></B>

<code><pre>void <b>integer_data_proxy::resize</b>(size_type sz);</pre></code>

<p>The member function ensures that the <code>integer</code> object holds
at least <code>sz</code> internal data elements.</p>

<B><A NAME="integer_data_proxy::reverse_iterator">reverse_iterator</A></B>

<code><pre>typedef <i>unspecified</i> <b>integer_data_proxy::reverse_iterator</b>;</pre></code>

<p>The typedef defines a synonym for a reverse iterator that can be used to access
internal data elements of the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::size">size</A></B>

<code><pre>size_type <b>integer_data_proxy::size</b>() const;</pre></code>

<p>The member function returns the number of internal data elements in the
<code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::size_type">size_type</A></B>

<code><pre>typedef <i>unspecified</i> <b>integer_data_proxy::size_type</b>;</pre></code>

<p>The typedef defines a synonym for an unsigned arithmetic type that can hold a
count of the number of internal data elements in the <code>integer</code> object.</p>

<B><A NAME="integer_data_proxy::uarithmetic_type">uarithmetic_type</A></B>

<code><pre>typedef <i>unspecified</i> <b>integer_data:proxy::uarithmetic_type</b>;</pre></code>

<p>The typedef defines a synonym for an unsigned arithmetic type with at least twice
as many bits as the internal storage type.</p>

<H2><A NAME="class_bits">Class <code>bits</code></A></H2>

<pre><code>class <B><A NAME="#bits">bits</A></B> {
public:

    class <A HREF="#class_bits_reference">reference</A>;

    // constructors
    <A HREF="#bits::bits">bits</A>();

    <A HREF="#bits::bits">bits</A>(char val);
    <A HREF="#bits::bits">bits</A>(signed char val);
    <A HREF="#bits::bits">bits</A>(unsigned char val);
    <A HREF="#bits::bits">bits</A>(short val);
    <A HREF="#bits::bits">bits</A>(unsigned short val);
    <A HREF="#bits::bits">bits</A>(int val);
    <A HREF="#bits::bits">bits</A>(unsigned val);
    <A HREF="#bits::bits">bits</A>(long val);
    <A HREF="#bits::bits">bits</A>(unsigned long val);
    <A HREF="#bits::bits">bits</A>(long long val);
    <A HREF="#bits::bits">bits</A>(unsigned long long val);

    <A HREF="#bits::bits">bits</A>(const char *str);
    template &lt;class CharT, class Traits, class Alloc&gt;
    explicit <A HREF="#bits::bits">bits</A>(const basic_string&lt;CharT, Traits, Alloc&gt;&amp; str,
        typename basic_string&lt;CharT, Traits, Alloc&gt;::size_type pos = 0,
        typename basic_string&lt;CharT, Traits, Alloc&gt;::size_type count = std::basic_string&lt;CharT&gt;::npos,
        CharT digit0 = CharT('0'),
        CharT digit1 = CharT('1'));
    template &lt;class CharT&gt;
    explicit <A HREF="#bits::bits">bits</A>(const CharT *ptr,
        typename basic_string&lt;CharT&gt;::size_type count = std::basic_string&lt;CharT&gt;::npos,
        CharT digit0 = CharT('0'),
        CharT digit1 = CharT('1'));

    <A HREF="#bits::bits">bits</A>(std::initializer_list&lt;uint_least32_t&gt; list);

    <A HREF="#bits::bits">bits</A>(const bits&amp; other);
    <A HREF="#bits::bits">bits</A>(bits&amp;&amp; other);
    <A HREF="#bits::bits">bits</A>(const integer&amp; val);
    <A HREF="#bits::bits">bits</A>(integer&amp;&amp; val);

    // assignment and swap
    bits&amp; <A HREF="#bits::operator=">operator=</A>(const bits&amp; rhs);
    bits&amp; <A HREF="#bits::operator=">operator=</A>(bits&amp;&amp; rhs);
    bits&amp; <A HREF="#bits::operator=">operator=</A>(const integer&amp; rhs);
    bits&amp; <A HREF="#bits::operator=">operator=</A>(integer&amp;&amp; rhs);
    void <A HREF="#bits::swap">swap</A>(bits&amp; rhs);

    // conversions
    unsigned long <A HREF="#bits::to_ulong">to_ulong</A>() const;
    unsigned long long <A HREF="#bits::to_ullong">to_ullong</A>() const;
    template &lt;class CharT = char, class Traits = std::char_traits&lt;CharT&gt;, class Alloc = std::allocator&lt;CharT&gt; &gt;
        std::basic_string&lt;CharT, Traits, Alloc&gt; <A HREF="#bits::to_string">to_string</A>(CharT zero = CharT('0'), CharT one = CharT('1'));

    // logical operations
    bits&amp; <A HREF="#bits::operator&amp;=">operator&amp;=</A>(const bits&amp; rhs);
    bits&amp; <A HREF="#bits::operator|=">operator|=</A>(const bits&amp; rhs);
    bits&amp; <A HREF="#bits::operator^=">operator^=</A>(const bits&amp; rhs);
    bits <A HREF="#bits::operator~">operator~</A>() const;
    
    bits&amp; <A HREF="#bits::operator&lt;&lt;=">operator&lt;&lt;=</A>(size_type shift);
    bits&amp; <A HREF="#bits::operator&gt;&gt;=">operator&gt;&gt;=</A>(size_type shift);
    bits&amp; <A HREF="#bits::operator&lt;&lt;">operator&lt;&lt;</A>(size_type shift) const;
    bits&amp; <A HREF="#bits::operator&gt;&gt;">operator&gt;&gt;</A>(size_type shift) const;

    // element access and modification
    bits&amp; <A HREF="#bits::set">set</A>();
    bits&amp; <A HREF="#bits::set">set</A>(size_type pos, bool val = true);
    bits&amp; <A HREF="#bits::reset">reset</A>();
    bits&amp; <A HREF="#bits::reset">reset</A>(size_type pos);
    bits&amp; <A HREF="#bits::flip">flip</A>();
    bits&amp; <A HREF="#bits::flip">flip</A>(size_type pos);
    bool <A HREF="#bits::operator[]">operator[]</A>(size_type pos) const;
    reference <A HREF="#bits::operator[]">operator[]</A>(size_type pos);
    bool <A HREF="#bits::test">test</A>(size_type pos) const;
    bool <A HREF="#bits::all">all</A>() const;
    bool <A HREF="#bits::any">any</A>() const;
    bool <A HREF="#bits::none">none</A>() const;
    size_type <A HREF="#bits::lowest_bit">lowest_bit</A>() const;
    size_type <A HREF="#bits::highest_bit">highest_bit</A>() const;
    size_type <A HREF="#bits::count">count</A>() const;

    // capacity
    size_type <A HREF="#bits::size">size</A>() const;
    void <A HREF="#bits::resize">resize</A>(size_type sz);

};
</code></pre>

<p>The class describes an object that represents an unbounded set of bits.</p>

<B><A NAME="bits::all">all</A></B>

<code><pre>bool <b>all</b>() const</pre></code>

<p>The member function returns true only if all the bits in
<code>*this</code> are set.</p>

<B><A NAME="bits::any">any</A></B>

<code><pre>bool <b>any</b>() const</pre></code>

<p>The member function returns true if at least one of the
bits in <code>*this</code> is set.</p>

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

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

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

<b>bits::bits</b>(const char *str);
template &lt;class CharT, class Traits, class Alloc&gt;
explicit <b>bits::bits</b>(const basic_string&lt;CharT, Traits, Alloc&gt;&amp; str,
    typename basic_string&lt;CharT, Traits, Alloc&gt;::size_type pos = 0,
    typename basic_string&lt;CharT, Traits, Alloc&gt;::size_type count = std::basic_string&lt;CharT&gt;::npos,
    CharT digit0 = CharT('0'),
    CharT digit1 = CharT('1'));
template &lt;class CharT&gt;
explicit <b>bits::bits</b>(const CharT *ptr,
    typename basic_string&lt;CharT&gt;::size_type count = std::basic_string&lt;CharT&gt;::npos,
    CharT digit0 = CharT('0'),
    CharT digit1 = CharT('1'));

<b>bits::bits</b>(std::initializer_list&lt;uint_least32_t&gt; list);

<b>bits::bits</b>(const bits&amp; other);
<b>bits::bits</b>(bits&amp;&amp; other);
explicit <b>bits::bits</b>(const integer&amp; other);
explicit <b>bits::bits</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>; negative values
construct an object whose value is the complement of <code>bits(abs(val))</code>.</p>

<p>The constructors that take <code>string</code> and <code>const char*</code>
objects construct an object whose value is the value represented by their argument,
treating <code>zero</code> as 0 and <code>one</code> as 1.</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>; the move constructors leave <code>other</code> in an unspecified
valid state. Construction from a negative <code>integer</code> value constructs
an object whose value is the complement of <code>bits(abs(val))</code>.</p>

<B><A NAME="bits::count">count</A></B>

<code><pre>size_type <b>count</b>() const;</pre></code>

<p>The member function returns the number of bits in <code>*this</code>
that are set.</p>

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

<code><pre>void <b>bits::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="bits::highest_bit">highest_bit</A></B>

<code><pre>int <b>bits::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="bits::lowest_bit">lowest_bit</A></B>

<code><pre>int <b>bits::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="bits::none">none</A></B>

<code><pre>bool <b>none</b>() const;</pre></code>

<p>The member function returns true only if none of the bits in <code>*this</code>
is set.</p>

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

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

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

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

<code><pre>bits <b>operator&amp;</b>(const bits&amp; left, const bits&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="bits::operator&amp;=">operator&amp;=</A></B>

<code><pre>bits&amp; <b>bits::operator&amp;=</b>(const bits&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="bits::operator|">operator|</A></B>

<code><pre>bits <b>operator|</b>(const bits&amp; left, const bits&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="bits::operator|=">operator|=</A></B>

<code><pre>bits&amp; <b>bits::operator|=</b>(const bits&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="bits::operator^">operator^</A></B>

<code><pre>bits <b>operator^</b>(const bits&amp; left, const bits&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="bits::operator^=">operator^=</A></B>

<code><pre>bits&amp; <b>bits::operator^=</b>(const bits&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="bits::operator~">operator~</A></B>

<code><pre>bits <b>operator~</b>() const;</pre></code>

<p>The member function returns an object that holds the complement
of the set of bits held by <code>*this</code>.</p>

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

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

<p>If the value of <code>shift</code> is negative, the operator
returns <code>operator&lt;&lt;(val, -shift)</code>. Otherwise,
the operator returns a new object whose stored value is the value of
the bits in <code>*this</code> shifted right <code>shift</code> positions.</p>

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

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

<p>If the value of <code>shift</code> is negative, the operator
returns <code>val &lt;&lt; -shift</code>. Otherwise,
the operator sets the stored value in <code>*this</code> to the value of
the bits in <code>*this</code> shifted right <code>shift</code> positions.</p>

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

<code><pre>template &lt;class CharT, class Traits&gt;
    std::basic_istream&lt;CharT, Traits&gt;&amp; <A HREF="#bits::operator&gt;&gt;">operator&gt;&gt;</A>(
        std::basic_istream&lt;CharT, Traits&gt;&amp; str, bits&amp; val);</pre></code>

<p>The operator has the effect of <code>{ std::string temp; strm &gt;&gt;
temp; val = temp; }</code> and returns a reference to <code>strm</code>.</p>

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

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

<p>If the value of <code>shift</code> is negative, the operator
returns <code>operator&gt;&gt;(val, -shift)</code>. Otherwise,
the operator returns a new object whose stored value is the value of
the bits in <code>*this</code> shifted left <code>shift</code> positions.</p>

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

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

<p>If the value of <code>shift</code> is negative, the operator
returns <code>val &gt;&gt; -shift</code>. Otherwise,
the operator sets the stored value in <code>*this</code> to the value of
the bits in <code>*this</code> shifted left <code>shift</code> positions.</p>

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

<pre><code>template &lt;class CharT, class Traits&gt;
    std::basic_ostream&lt;CharT, Traits&gt;&amp; <A HREF="#bits::operator&lt;&lt;">operator&lt;&lt;</A>(
        std::basic_ostream&lt;CharT, Traits&gt;&amp; str, const bits&amp; val);</pre></code>

<p>The operator has the effect of <code>strm &lt;&lt; val.to_string()</code>
and returns a reference to <code>strm</code>.</p>

<B><A NAME="bits::operator[]">operator[]</A></B>

<code><pre>bool <b>operator[]</b>(size_type pos) const;
reference <b>operator[]</b>(size_type pos);</pre></code>

<p>The first member function returns the value of the bit at position <code>pos</code>.
The second member function returns an object of type <code>bits::reference</code>
that refers to the bit at position <code>pos</code>.</p>

<B><A NAME="bits::reset">reset</A></B>

<code><pre>bits&amp; <b>reset</b>();
bits&amp; <b>reset</b>(size_type pos);</pre></code>

<p>The first member function clears all the bits of <code>*this</code>.
The second member function clears the bit as position <code>pos</code>.</p>

<B><A NAME="bits::resize">resize</A></B>

<code><pre>void <b>resize</b>(size_type sz);</pre></code>

<p>The member function adjusts the storage capacity of<code>*this</code>
so that it can hold at least <code>sz</code> bits without reallocating.</p>

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

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

<p>The first member function sets all the bits of <code>*this</code>.
The second member function sets the bit at position <code>pos</code> in the stored
value to <code>val</code>.</p>

<B><A NAME="bits::size">size</A></B>

<code><pre>size_type size() const;</pre></code>

<p>The member function returns the maximum number of bits that can be held in
<code>*this</code> without reallocating.</p>

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

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

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

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

<code><pre>bool <b>bits::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="bits::to_string">to_string</A></B>

<code><pre>template &lt;class CharT = char, class Traits = std::char_traits&lt;CharT&gt;, class Alloc = std::allocator&lt;CharT&gt; &gt;
    std::basic_string&lt;CharT, Traits, Alloc&gt; <b>bits::to_string</b>(
        CharT zero = CharT('0'), CharT one = CharT('1'));</code></pre>

<p>The member function returns a string representation of the value stored in
<code>*this</code>, using <code>zero</code> to represent 0 and <code>one</code> to represent 1.</p>

<B><A NAME="bits::to_ullong">to_ullong</A></B>

<code><pre>unsigned long long <b>bits::to_ullong</b>() const;</pre></code>

<p>The member function returns a value equal to the stored value of
<code>*this</code>.</p>

<B><A NAME="bits::to_ulong">to_ulong</A></B>

<code><pre>unsigned long <b>bits::to_ulong</b>() const;</pre></code>

<p>The member function returns a value equal to the stored value of
<code>*this</code>.</p>

<H2><A NAME="class_bits_reference">Class <code>bits::reference</code></A></H2>

<code><pre>class <b>bits</b> {
    class <A HREF="#bits::reference">reference</A> {
    public:
        reference&amp; <A HREF="#bits::reference::operator=">operator=</A>(bool val);
        reference&amp; <A HREF="#bits::reference::operator=">operator=</A>(const reference&amp; rhs);
        bool <A HREF="#bits::reference::operator~">operator~</A>() const;
        <A HREF="#bits::reference::operator bool">operator bool</A>() const;
        reference&amp; <A HREF="#bits::reference::flip">flip</A>();
    };
};</pre></code>

<p>The nested class <code>bits::reference</code> describes an object that
can be used to manage a particular bit in an object of type <code>bits</code>.</p>

<B><A NAME="bits::reference::flip">flip</A></B>

<code><pre>reference&amp; <b>bits::reference::flip</b>();</pre></code>

<p>The member function toggles the bit that the object manages.</p>

<B><A NAME="bits::reference::operator=">operator=</A></B>

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

<p>The first member operator sets the bit that the object manages to the
value of <code>right</code>. The second member operator sets the bit that
the object manages to the value managed by <code>right</code>.</p>

<B><A NAME="bits::reference::operator~">operator~</A></B>

<code><pre>bool <b>bits::reference::operator~</b>() const;</pre></code>

<p>The member operator returns <code>true</code> if the bit managed by the
object is set, otherwise <code>false</code>.</p>

<B><A NAME="bits::reference::operator bool">operator bool</A></B>

<code><pre><b>bits::reference::operator bool</b>() const;</pre></code>

<p>The member operator returns true if the bit that the object manages is set.</p>

</BODY></HTML>
