__vic/doc/en/bits.h.xml

<chapter xml:id="bits.h">
<title><tt>__vic/bits.h</tt></title>

<p>Bits and bytes manipulation tools.</p>


<chapter xml:id="lo_nibble">
<title><tt>lo_nibble()</tt>, <tt>hi_nibble()</tt></title>

<code-block lang="C++">
constexpr uint8_t lo_nibble(uint8_t byte);
constexpr uint8_t hi_nibble(uint8_t byte);
</code-block>

<p>Return the value of the low-order/high-order half-byte (tetrad),
respectively.</p>

</chapter>


<chapter xml:id="msb_ones">
<title><tt>msb_ones()</tt>, <tt>lsb_ones()</tt></title>

<code-block lang="C++"><![CDATA[
template<class T> constexpr T lsb_ones(unsigned bits_num);
template<class T> constexpr T msb_ones(unsigned bits_num);
]]></code-block>

<p>Return the value of the type <tt>T</tt> with all least/most significant
<tt>bits_num</tt> bits filled with <tt>1</tt>, respectively. All other bits
are set to <tt>0</tt>.</p>

</chapter>


<chapter xml:id="get_lsbs">
<title><tt>get_lsbs()</tt></title>

<code-block lang="C++">
template&lt;class T> constexpr T get_lsbs(T v, unsigned bits_num);
</code-block>

<p>Returns <tt>bits_num</tt> least significant bits of <tt>v</tt>. In other
words, zeroes all but <tt>bits_num</tt> least significant bits.</p>

</chapter>


<chapter xml:id="ord">
<title><tt>ord()</tt></title>

<code-block lang="C++">
constexpr int ord(char ch);
</code-block>

<p>Returns the character code from 0 to 255.</p>
<postcondition>ord(ch) >= 0</postcondition>

</chapter>


<chapter xml:id="popcount">
<title><tt>popcount()</tt></title>

<code-block lang="C++">
unsigned popcount(unsigned v);
unsigned popcount(unsigned long v);
unsigned popcount(unsigned long long v);
unsigned popcount(unsigned short v);
unsigned popcount(unsigned char v);
</code-block>

<p>Returns the number of one bits in the given value.</p>

</chapter>


<chapter xml:id="msb_position">
<title><tt>msb_position()</tt></title>

<code-block lang="C++">
unsigned msb_position(unsigned v)
unsigned msb_position(unsigned long v);
unsigned msb_position(unsigned long long v);
unsigned msb_position(unsigned short v);
unsigned msb_position(unsigned char v);
</code-block>

<precondition><tt>v != 0</tt></precondition>

<p>Returns the position of the most significant 1-bit. The result is unspecified
if <tt>v == 0</tt>.</p>

</chapter>


<chapter xml:id="ispow2">
<title><tt>ispow2()</tt></title>

<code-block lang="C++"><![CDATA[
template<class UInt>
bool ispow2(UInt n);
]]></code-block>

<precondition><tt>UInt</tt> is an unsigned integer type</precondition>

<p>Returns <tt>true</tt> if <tt>n</tt> is an integral power of 2.</p>

</chapter>


<chapter xml:id="ceil2">
<title><tt>ceil2()</tt></title>

<code-block lang="C++"><![CDATA[
template<class UInt>
UInt ceil2(UInt n);
]]></code-block>

<precondition><tt>UInt</tt> is an unsigned integer type</precondition>

<p>Returns the minimal value <tt>m</tt> such that <tt>ispow2(m) &amp;&amp;
m >= n</tt>. If <tt>m</tt> is not representable as a value of type
<tt>UInt</tt>, the result is an unspecified value.</p>

</chapter>


<chapter xml:id="floor2">
<title><tt>floor2()</tt></title>

<code-block lang="C++"><![CDATA[
template<class UInt>
UInt floor2(UInt n);
]]></code-block>

<precondition><tt>UInt</tt> is an unsigned integer type</precondition>

<p>If <tt>n != 0</tt> returns the maximal value <tt>m</tt> such that
<tt>ispow2(m) &amp;&amp; m &lt;= n</tt>. Otherwise <tt>0</tt> is returned.</p>

</chapter>


<chapter xml:id="ceil_log2">
<title><tt>ceil_log2()</tt></title>

<code-block lang="C++"><![CDATA[
template<class UInt>
unsigned ceil_log2(UInt n);
]]></code-block>

<precondition><tt>UInt</tt> is an unsigned integer type</precondition>

<p>Returns <tt>ceil(log2(n))</tt> if <tt>n != 0</tt> or 0 otherwise.</p>

</chapter>


<chapter xml:id="floor_log2">
<title><tt>floor_log2()</tt></title>

<code-block lang="C++"><![CDATA[
template<class UInt>
unsigned floor_log2(UInt n);
]]></code-block>

<precondition><tt>UInt</tt> is an unsigned integer type</precondition>

<p>Returns <tt>floor(log2(n))</tt> if <tt>n != 0</tt> or 0 otherwise.</p>

</chapter>


<chapter xml:id="rotl">
<title><tt>rotl()</tt>, <tt>rotr()</tt></title>

<code-block lang="C++">
unsigned long long rotl(unsigned long long v, int shift);
unsigned long      rotl(unsigned long v, int shift);
unsigned           rotl(unsigned v, int shift);
unsigned short     rotl(unsigned short v, int shift);
unsigned char      rotl(unsigned char v, int shift);

unsigned long long rotr(unsigned long long v, int shift);
unsigned long      rotr(unsigned long v, int shift);
unsigned           rotr(unsigned v, int shift);
unsigned short     rotr(unsigned short v, int shift);
unsigned char      rotr(unsigned char v, int shift);
</code-block>

<p>The functions perform circular left (<tt>rotl</tt>) or right
(<tt>rotr</tt>) bitwise shift (rotation).</p>
<precondition><tt>0 &lt;= shift &amp;&amp; shift &lt; sizeof(v)*CHAR_BIT</tt></precondition>

</chapter>


<chapter xml:id="swapped_nibbles">
<title><tt>swapped_nibbles()</tt></title>

<code-block lang="C++">
constexpr uint8_t swapped_nibbles(uint8_t b);
</code-block>

<p>Swaps a low-order half-byte with a high-order one and returns the value.</p>

</chapter>


</chapter>