<h1>Strongly Typed Bitset</h1>

<ul>
<li>Document Number: N4202</li>
<li>Date: 2014-08-20</li>
<li>Programming Language C++, Library Evolution Working Group</li>
<li>Reply-to: Matthew Fioravante <a href="&#109;&#97;&#x69;&#108;&#116;&#111;:f&#x6D;&#x61;&#x74;&#x74;&#x68;&#101;w&#x35;&#56;&#x37;&#54;&#64;&#103;&#109;&#x61;i&#108;&#46;&#x63;&#x6F;&#x6D;">f&#x6D;&#x61;&#x74;&#x74;&#x68;&#101;w&#x35;&#56;&#x37;&#54;&#64;&#103;&#109;&#x61;i&#108;&#46;&#x63;&#x6F;&#x6D;</a></li>
</ul>

<p>The latest draft, reference header, and links to past discussions on Github: </p>

<ul>
<li><a href="https://github.com/fmatthew5876/stdcxx-bitset">https://github.com/fmatthew5876/stdcxx-bitset</a></li>
</ul>

<h1>Introduction</h1>

<p>The proposal enhances <code>std::bitset</code> by adding a new template parameter which 
allows the programmer to control the size and alignment of the underlying representation
along with a few additional public members.</p>

<p>This proposal is aimed for a C++ Technical Specification.</p>

<h1>Impact on the standard</h1>

<p>This proposal is a pure library extension. It changes the
template signature of <code>std::bitset</code> by adding a new template parameter.
It also adds 2 new aliases <code>std::fast_bitset</code> and <code>std::small_bitset</code>,
3 new public members, a new constructor overload and a new assignment operator overload.</p>

<h1>Impact on Implementations</h1>

<p>Implementation of this proposal will likely break the ABI of all standard library
implementations of <code>std::bitset</code>. Adding a new template parameter may change the mangled
name of the type. If accepted, the deployment date of this proposal into the standard should
be carefully considered to avoid too many ABI breaks.</p>

<h1>Motivation and Design</h1>

<p>When dealing with bits, the classical method of implementation is to use
an unsigned integral type and perform bit operations using logical operations, shifts, and masks.</p>

<p>With C++11, we have <code>std::bitset</code> which is a nice abstraction for acting on the individual
bits of a fixed size quantity.  The objective
of <code>std::bitset</code> should be to entirely replace unsigned integers for implementing small collections of
bit flags. </p>

<p>Often times, sets of bits or flags are included in binary protocols or
other tightly packed small objects in memory. Due to the precise
size and alignment requirements of such domains, <code>std::bitset</code> is
unusable because the programmer has no control over the alignment or
size of <code>std::bitset</code>. Indeed it appears that <code>std::bitset</code> on
x86_64 linux gcc is always at least 8 bytes.
In some situations, the
overhead of the extra space makes bitset unusable.</p>

<p>In addition, sometimes users may want a <code>bitset</code> object whose underlying representation
has been automatically optimize for speed or space on a given platform. For this we provide
<code>fast_bitset</code> and <code>small_bitset</code>.</p>

<h1>Technical Specification</h1>

<p>We will now describe the additions to the <code>&lt;experimental/bitset&gt;</code> header.</p>

<h2>std::bitset&lt;N,T&gt;</h2>

<p>This new declaration is aimed to eventually replace the current <code>std::bitset</code>.</p>

<pre><code>namespace std {
namespace experimental {
template &lt;size_t N, typename T = /* Implementation defined */&gt;
  class bitset;
} //namespace experimental
} // namespace std
</code></pre>

<p><code>std::bitset&lt;N,T&gt;</code> shall have the following constraints:</p>

<pre><code>static_assert(is_integral&lt;T&gt;::value);
static_assert(alignof(bitset&lt;N,T&gt;) == alignof(T[N / (sizeof(T) * CHAR_BIT) + (n % (sizeof(T) * CHAR_BIT) != 0)];
static_assert(sizeof(bitset&lt;N,T&gt;) == sizeof(T[N / (sizeof(T) * CHAR_BIT) + (n % (sizeof(T) * CHAR_BIT) != 0)];
</code></pre>

<p>There are no changes being proposed to the current set of members of <code>std::bitset</code>.</p>

<p>[<em>Note</em>: <code>bitset&lt;N,T&gt;</code> is not required to actually be implemented using an array of type <code>T</code>, it only needs to satisfy the size and alignment constraints. --<em>end node</em>]</p>

<h3>Implementation guidance for the default <code>T</code></h3>

<p>The default type <code>T</code> used for <code>std::bitset&lt;N,T&gt;</code> is implementation defined. This behavior is provided
for backwards source compatibility with C++14. We offer the following recommendations for
platforms in choosing which type to use.</p>

<ul>
<li>Most general platforms should choose <code>T</code> as to optimize for speed (see below: <code>fast_bitset&lt;N&gt;</code>)</li>
<li>Memory constrained platforms should choose <code>T</code> as to optimize for space (see below: <code>small_bitset&lt;N&gt;</code>)</li>
<li>If backwards compatibility is of primary concern, platforms can continue to use the same type used in C++14.
Note that changing the template arguments of bitset will already break ABI compatibility on most platforms.
Implementors may choose to take this opportunity to change default <code>T</code> to optimize for speed or space.</li>
</ul>

<h3>Conceptual implementation</h3>

<p>A conforming implementation could be constructed using the following data model.</p>

<pre><code>template &lt;size_t N, typename T&gt;
  struct alignas(T) bitset {
    array&lt;T, N / (sizeof(T) * CHAR_BIT) + (n % (sizeof(T) * CHAR_BIT) != 0)&gt; data;
  };
</code></pre>

<p>Note that this implementation also works on Linux i386 where <code>sizeof(long long) == 8</code> but <code>struct t { long long x; }; alignof(t) == 4</code>.</p>

<h2>Accessing the underlying storage</h2>

<p>We propose to add the following public members to <code>std::bitset</code>:</p>

<pre><code>template &lt;size_t N, typename T&gt;
  using bitset&lt;N,T&gt;::underlying_type = std::array&lt;T, N / (sizeof(T) * CHAR_BIT) + (n % (sizeof(T) * CHAR_BIT) != 0)&gt;;
</code></pre>

<p>The <code>underlying_type</code> typedef is present to inform the programmer what kind of storage is being used by the <code>bitset</code>.
The <code>bitset</code> must have the same size and alignment as this type.</p>

<pre><code>template &lt;size_t N, typename T&gt;
  underlying_type&amp; bitset&lt;N,T&gt;::underlying() noexcept;
template &lt;size_t N, typename T&gt;
  const underlying_type&amp; bitset&lt;N,T&gt;::underlying() const noexcept;
</code></pre>

<p>These 2 accessors allow the programmer manual access to the underlying storage.
The values of the bits from <code>0</code> to <code>N-1</code> in the returned reference will be the same as the corresponding bits in the bitset.
The values of the bits <code>&gt;= N</code> in the returned reference are implementation defined.</p>

<p>Any modifications performed on bits <code>0</code> to <code>N-1</code>
of the returned reference will also be performed on the <code>bitset</code> object. Likewise modifying the bits in the bitset
will also modify the bits of the reference.
Modifying any bits <code>&gt;= N</code> will have no effect on the underlying bitset and their state is not guaranteed to remain
consistent after calling any member function of <code>bitset</code> or any free function which modifies <code>bitset</code>.</p>

<p>Note that while we do not require implementations to actually use <code>underlying_type</code> to implement <code>bitset</code>, we do require them to
match the size and alignment constraints of <code>underlying_type</code>. Therefore if bitset is implemented using a different type, the
implementation can internally perform a cast to <code>underlying_type</code> to implement these methods.</p>

<h2>Copying bitsets of different types.</h2>

<p>A bitset using one representation <code>T</code> may be copied from another bitset using a different representation <code>U</code>. We add the following
constructor and assignment operator overloads.</p>

<pre><code>template &lt;size_t N, typename T&gt; template &lt;typename U&gt;
  constexpr bitset&lt;N,T&gt;::bitset(const bitset&lt;N,U&gt;&amp; other) noexcept;
template &lt;size_t N, typename T&gt; template &lt;typename U&gt;
  constexpr bitset&lt;N,T&gt;&amp; bitset&lt;N,T&gt;::operator=(const bitset&lt;N,U&gt;&amp; other) noexcept;
</code></pre>

<h2>std::fast_bitset&lt;N&gt;</h2>

<p>The type <code>fast_bitset&lt;N&gt;</code> shall be an alias for <code>std::bitset&lt;N,T&gt;</code>, where <code>T</code> is chosen to be the fastest underlying representation for <code>N</code> bits.</p>

<h3>Possible implementation</h3>

<pre><code>template &lt;size_t N&gt;
struct __fast_bitset_type : public
  std::conditional&lt;N &gt; 32, uint_fast64_t,
    std::conditional&lt;N &gt; 16, uint_fast32_t,
      std::conditional&lt;N &gt; 8, uint_fast16_t,
        uint_fast8_t
      &gt;
    &gt;
  &gt; {};

template &lt;size_t N&gt; using fast_bitset = bitset&lt;N,typename __fast_bitset_type&lt;N&gt;::type&gt;;
</code></pre>

<h2>std::small_bitset&lt;N&gt;</h2>

<p>The type <code>fast_bitset&lt;N&gt;</code> shall be an alias for <code>std::bitset&lt;N,T&gt;</code>, where <code>T</code> is chosen to be the smallest underlying representation for <code>N</code> bits.
Note that there are no restrictions on alignment.</p>

<h3>Possible implementation</h3>

<pre><code>template &lt;size_t N&gt;
struct __small_bitset_type : public
  std::conditional&lt;N % 64 &gt; 32 || N % 64 == 0, uint_least64_t,
    std::conditional&lt;N % 64 &gt; 16, uint_least32_t,
      std::conditional&lt;N % 64 &gt; 8, uint_least16_t,
        uint_least8_t
      &gt;
    &gt;
  &gt; {};

template &lt;size_t N&gt; using small_bitset = bitset&lt;N,typename __small_bitset_type&lt;N&gt;::type&gt;;
</code></pre>

<h1>Use Cases</h1>

<ul>
<li>Binary protocols</li>
<li>CPU emulation, modeling instruction sets with flags</li>
<li>Tightly packing data into small blocks of memory.</li>
<li>Bit flags</li>
</ul>

<h1>Acknowledgments</h1>

<ul>
<li>Thank you to everyone one the std-proposals forum.</li>
</ul>

<!--
References
==================

* <a name="N3864"></a>[N3864] Fioravante, Matthew *N3864 - A constexpr bitwise operations library for C++*, Available online at <https://github.com/fmatthew5876/stdcxx-bitops>
* <a name="LXR"></a>[LXR] *Linux/include/linux/kernel.h* Available online at <http://lxr.free-electrons.com/source/include/linux/kernel.h#L50>
* <a name="IsoCpp"></a>[IsoCpp] *ISO C++ standard*
* <a name="clang"></a> *"clang" C Language Family Frontend for LLVM* Available online at <http://clang.llvm.org/>
-->
