EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/crc/doc/autodoc.xml

<?xml version="1.0" standalone="yes"?>
<library-reference><header name="boost/crc.hpp">
<para>A collection of function templates and class templates that compute various forms of Cyclic Redundancy Codes (CRCs). </para><para><para>Daryle Walker</para>

<para>1.5</para>

<para>Boost Software License, version 1.0</para>

Contains the declarations (and definitions) of various kinds of CRC computation functions, function object types, and encapsulated policy types.</para><para><warning><para>The sample CRC-computer types were just checked against the <ulink url="http://regregex.bbcmicro.net/crc-catalogue.htm">Catalogue of parametrised CRC algorithms</ulink>. New type aliases were added where I got a standard wrong. However, the mistaken <computeroutput>typedef</computeroutput>s are still there for backwards compatibility. </para>
</warning>
<note><para>There are references to the <emphasis>Rocksoft<trademark/> Model CRC Algorithm</emphasis>, as described within "A Painless Guide to CRC Error Detection Algorithms," linked from "<ulink url="http://www.ross.net/crc/crcpaper.html">CRC: A Paper On CRCs</ulink>" by Ross Williams. It will be abbreviated "RMCA" in other documentation blocks. </para>
</note>
</para><namespace name="boost">
<class name="crc_basic"><template>
      <template-nontype-parameter name="Bits"><type>std::size_t</type><purpose><para>The order of the modulo-2 polynomial divisor. (<emphasis>Width</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
    </template><purpose>Bit-wise CRC computer. </purpose><description><para>Objects of this type compute the CRC checksum of submitted data, where said data can be entered piecemeal through several different kinds of groupings. Modulo-2 polynomial division steps are always performed bit-wise, without the use of pre-computation tables. Said division uses the altered algorithm, so any data has to be unaugmented.</para><para>

</para></description><typedef name="value_type"><purpose>The register type used for computations. </purpose><description><para>This type is used for CRC calculations and is the type for any returned checksums and returned or submitted remainders, (truncated) divisors, or XOR masks. It is a built-in unsigned integer type. </para></description><type>boost::uint_t&lt; Bits &gt;::fast</type></typedef>
<method-group name="public member functions">
<method name="BOOST_STATIC_CONSTANT"><type/><parameter name=""><paramtype>std::size_t</paramtype></parameter><parameter name=""><paramtype>bit_count</paramtype><default>Bits</default></parameter><purpose>A copy of <emphasis>Bits</emphasis> provided for meta-programming purposes. </purpose></method>
<method name="get_truncated_polynominal" cv="const"><type>value_type</type><purpose>Return the (truncated) polynomial divisor. </purpose><description><para>Returns a representation of the polynomial divisor. The value of the 2<superscript>i</superscript> bit is the value of the coefficient of the polynomial's x<superscript>i</superscript> term. The omitted bit for x<superscript>(#bit_count)</superscript> term is always 1.</para><para>
</para></description><returns><para>The bit-packed list of coefficients. If the bit-length of value_type exceeds #bit_count, the values of higher-placed bits should be ignored (even any for x<superscript>(#bit_count)</superscript>) since they're unregulated. </para>
</returns></method>
<method name="get_initial_remainder" cv="const"><type>value_type</type><purpose>Return what the polynomial remainder was set to during construction. </purpose><description><para>Returns a representation of the polynomial remainder before any input has been submitted. The value of the 2<superscript>i</superscript> bit is the value of the coefficient of the polynomial's x<superscript>i</superscript> term.</para><para>
</para></description><returns><para>The bit-packed list of coefficients. If the bit-length of value_type exceeds #bit_count, the values of higher-placed bits should be ignored since they're unregulated. </para>
</returns></method>
<method name="get_final_xor_value" cv="const"><type>value_type</type><purpose>Return the XOR-mask used during output processing. </purpose><description><para>Returns the mask to be used during creation of a checksum. The mask is used for an exclusive-or (XOR) operation applied bit-wise to the interim remainder representation (after any reflection, if get_reflect_remainder() returns <computeroutput>true</computeroutput>).</para><para>
</para></description><returns><para>The bit-mask. If the bit-length of value_type exceeds #bit_count, the values of higher-placed bits should be ignored since they're unregulated. </para>
</returns></method>
<method name="get_reflect_input" cv="const"><type>bool</type><purpose>Check if input-bytes will be reflected before processing. </purpose><description><para>Returns a whether or not a submitted byte will be "reflected" before it is used to update the interim remainder. Only the byte-wise operations process_byte, process_block, and process_bytes are affected.</para><para>
</para></description></method>
<method name="get_reflect_remainder" cv="const"><type>bool</type><purpose>Check if the remainder will be reflected during output processing. </purpose><description><para>Indicates if the interim remainder will be "reflected" before it is passed to the XOR-mask stage when returning a checksum.</para><para>
</para></description></method>
<method name="get_interim_remainder" cv="const"><type>value_type</type><purpose>Return the remainder based from already-processed bits. </purpose><description><para>Returns a representation of the polynomial remainder after all the input submissions since construction or the last reset call. The value of the 2<superscript>i</superscript> bit is the value of the coefficient of the polynomial's x<superscript>i</superscript> term. If CRC processing gets interrupted here, retain the value returned, and use it to start up the next CRC computer where you left off (with reset(value_type) or construction). The next computer has to have its other parameters compatible with this computer.</para><para>
</para></description><returns><para>The bit-packed list of coefficients. If the bit-length of value_type exceeds #bit_count, the values of higher-placed bits should be ignored since they're unregulated. No output processing (reflection or XOR mask) has been applied to the value. </para>
</returns></method>
<method name="reset"><type>void</type><parameter name="new_rem"><paramtype>value_type</paramtype><description><para>The (unaugmented) state of the polynomial remainder starting from this point, with no output processing applied.</para></description></parameter><purpose>Change the interim remainder to a new value. </purpose><description><para>Changes the interim polynomial remainder to <emphasis>new_rem</emphasis>, purging any influence previously submitted input has had. The value of the 2<superscript>i</superscript> bit is the value of the coefficient of the polynomial's x<superscript>i</superscript> term.</para><para>


</para></description><postconditions><para><computeroutput><emphasis>new_rem</emphasis> == this-&gt;get_interim_remainder()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput>((this-&gt;get_reflect_remainder() ? REFLECT(<emphasis>new_rem</emphasis>) : <emphasis>new_rem</emphasis>) ^ this-&gt;get_final_xor_value()) == this-&gt;checksum()</computeroutput> </para>
</postconditions></method>
<method name="reset"><type>void</type><purpose>Change the interim remainder back to the initial value. </purpose><description><para>Changes the interim polynomial remainder to the initial remainder given during construction, purging any influence previously submitted input has had. The value of the 2<superscript>i</superscript> bit is the value of the coefficient of the polynomial's x<superscript>i</superscript> term.</para><para>

</para></description><postconditions><para><computeroutput>this-&gt;get_initial_remainder() == this-&gt;get_interim_remainder()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput>((this-&gt;get_reflect_remainder() ? REFLECT(this-&gt;get_initial_remainder()) : this-&gt;get_initial_remainder()) ^ this-&gt;get_final_xor_value()) == this-&gt;checksum()</computeroutput> </para>
</postconditions></method>
<method name="process_bit"><type>void</type><parameter name="bit"><paramtype>bool</paramtype><description><para>The new input bit.</para></description></parameter><purpose>Submit a single bit for input processing. </purpose><description><para>Updates the interim remainder with a single altered-CRC-division step.</para><para>

</para></description><postconditions><para>The interim remainder is updated though a modulo-2 polynomial division, where the division steps are altered for unaugmented CRCs. </para>
</postconditions></method>
<method name="process_bits"><type>void</type><parameter name="bits"><paramtype>unsigned char</paramtype><description><para>The byte containing the new input bits. </para></description></parameter><parameter name="bit_length"><paramtype>std::size_t</paramtype><description><para>The number of bits in the byte to be read.</para></description></parameter><purpose>Submit the lowest <emphasis>bit_length</emphasis> bits of a byte for input processing. </purpose><description><para>Updates the interim remainder with several altered-CRC-division steps. Each bit is processed separately, starting from the one at the 2<superscript><emphasis>bit_length</emphasis> - 1</superscript> place, then proceeding down to the lowest-placed bit. Any order imposed by <computeroutput>this-&gt;get_reflect_input()</computeroutput> is ignored.</para><para>


</para></description><requires><para>0 &lt; <emphasis>bit_length</emphasis> &lt;= <computeroutput>CHAR_BIT</computeroutput> </para>
</requires><postconditions><para>The interim remainder is updated though <emphasis>bit_length</emphasis> modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs. </para>
</postconditions></method>
<method name="process_byte"><type>void</type><parameter name="byte"><paramtype>unsigned char</paramtype><description><para>The new input byte.</para></description></parameter><purpose>Submit a single byte for input processing. </purpose><description><para>Updates the interim remainder with a byte's worth of altered-CRC-division steps. The bits within the byte are processed from the highest place down if <computeroutput>this-&gt;get_reflect_input()</computeroutput> is <computeroutput>false</computeroutput>, and lowest place up otherwise.</para><para>

</para></description><postconditions><para>The interim remainder is updated though <computeroutput>CHAR_BIT</computeroutput> modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs. </para>
</postconditions></method>
<method name="process_block"><type>void</type><parameter name="bytes_begin"><paramtype>void const *</paramtype><description><para>The address where the memory block begins. </para></description></parameter><parameter name="bytes_end"><paramtype>void const *</paramtype><description><para>Points to one-byte past the address of the memory block's last byte, or <emphasis>bytes_begin</emphasis> if no bytes are to be read.</para></description></parameter><purpose>Submit a memory block for input processing, iterator-pair style. </purpose><description><para>Updates the interim remainder with several bytes' worth of altered-CRC-division steps. The bits within each byte are processed from the highest place down if <computeroutput>this-&gt;get_reflect_input()</computeroutput> is <computeroutput>false</computeroutput>, and lowest place up otherwise. The bytes themselves are processed starting from the one pointed by <emphasis>bytes_begin</emphasis> until <emphasis>bytes_end</emphasis> is reached through forward iteration, treating the two pointers as if they point to <computeroutput>unsigned char</computeroutput> objects.</para><para>




</para></description><requires><para><emphasis>bytes_end</emphasis> has to equal <emphasis>bytes_begin</emphasis> if the latter is <computeroutput>NULL</computeroutput> or otherwise doesn't point to a valid buffer. </para>
</requires><requires><para><emphasis>bytes_end</emphasis>, if not equal to <emphasis>bytes_begin</emphasis>, has to point within or one-byte-past the same buffer <emphasis>bytes_begin</emphasis> points into. </para>
</requires><requires><para><emphasis>bytes_end</emphasis> has to be reachable from <emphasis>bytes_begin</emphasis> through a finite number of forward byte-pointer increments.</para>
</requires><postconditions><para>The interim remainder is updated though <computeroutput>CHAR_BIT * (((unsigned char const *) bytes_end) - ((unsigned char const *) bytes_begin))</computeroutput> modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs. </para>
</postconditions></method>
<method name="process_bytes"><type>void</type><parameter name="buffer"><paramtype>void const *</paramtype><description><para>The address where the memory block begins. </para></description></parameter><parameter name="byte_count"><paramtype>std::size_t</paramtype><description><para>The number of bytes in the memory block.</para></description></parameter><purpose>Submit a memory block for input processing, pointer-and-size style. </purpose><description><para>Updates the interim remainder with several bytes' worth of altered-CRC-division steps. The bits within each byte are processed from the highest place down if <computeroutput>this-&gt;get_reflect_input()</computeroutput> is <computeroutput>false</computeroutput>, and lowest place up otherwise. The bytes themselves are processed starting from the one pointed by <emphasis>buffer</emphasis>, forward-iterated (as if the pointed-to objects were of <computeroutput>unsigned char</computeroutput>) until <emphasis>byte_count</emphasis> bytes are read.</para><para>



</para></description><requires><para><emphasis>byte_count</emphasis> has to equal 0 if <emphasis>buffer</emphasis> is <computeroutput>NULL</computeroutput> or otherwise doesn't point to valid memory. </para>
</requires><requires><para>If <emphasis>buffer</emphasis> points within valid memory, then that block has to have at least <emphasis>byte_count</emphasis> more valid bytes allocated from that point.</para>
</requires><postconditions><para>The interim remainder is updated though <computeroutput>CHAR_BIT * <emphasis>byte_count</emphasis></computeroutput> modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs. </para>
</postconditions></method>
<method name="checksum" cv="const"><type>value_type</type><purpose>Return the checksum of the already-processed bits. </purpose><description><para>Computes the checksum of all the submitted bits since construction or the last call to reset. The checksum will be the raw checksum, i.e. the (interim) remainder after all the modulo-2 polynomial division, plus any output processing.</para><para>
<note><para>Since checksums are meant to be compared, any higher-placed bits (when the bit-length of value_type exceeds #bit_count) will be set to 0. </para>
</note>
</para></description><returns><para><computeroutput>(this-&gt;get_reflect_remainder() ? REFLECT(this-&gt;get_interim_remainder()) : this-&gt;get_interim_remainder()) ^ this-&gt;get_final_xor_value()</computeroutput></para>
</returns></method>
</method-group>
<constructor specifiers="explicit"><parameter name="truncated_polynomial"><paramtype>value_type</paramtype><description><para>The lowest coefficients of the divisor polynomial. The highest-order coefficient is omitted and always assumed to be 1. (<emphasis>Poly</emphasis> from the RMCA) </para></description></parameter><parameter name="initial_remainder"><paramtype>value_type</paramtype><default>0</default><description><para>The (unaugmented) initial state of the polynomial remainder. Defaults to <computeroutput>0</computeroutput> if omitted. (<emphasis>Init</emphasis> from the RMCA) </para></description></parameter><parameter name="final_xor_value"><paramtype>value_type</paramtype><default>0</default><description><para>The (XOR) bit-mask to be applied to the output remainder, after possible reflection but before returning. Defaults to <computeroutput>0</computeroutput> (i.e. no bit changes) if omitted. (<emphasis>XorOut</emphasis> from the RMCA) </para></description></parameter><parameter name="reflect_input"><paramtype>bool</paramtype><default>false</default><description><para>If <computeroutput>true</computeroutput>, input bytes are read lowest-order bit first, otherwise highest-order bit first. Defaults to <computeroutput>false</computeroutput> if omitted. (<emphasis>RefIn</emphasis> from the RMCA) </para></description></parameter><parameter name="reflect_remainder"><paramtype>bool</paramtype><default>false</default><description><para>If <computeroutput>true</computeroutput>, the output remainder is reflected before the XOR-mask. Defaults to <computeroutput>false</computeroutput> if omitted. (<emphasis>RefOut</emphasis> from the RMCA)</para></description></parameter><purpose>Create a computer, separately listing each needed parameter. </purpose><description><para>Constructs a <computeroutput><classname alt="boost::crc_basic">crc_basic</classname></computeroutput> object with at least the required parameters to a particular CRC formula to be processed upon receiving input.</para><para>







</para></description><postconditions><para><computeroutput><emphasis>truncated_polynomial</emphasis> == this-&gt;get_truncated_polynominal()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput><emphasis>initial_remainder</emphasis> == this-&gt;get_initial_remainder()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput><emphasis>final_xor_value</emphasis> == this-&gt;get_final_xor_value()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput><emphasis>reflect_input</emphasis> == this-&gt;get_reflect_input()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput><emphasis>reflect_remainder</emphasis> == this-&gt;get_reflect_remainder()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput><emphasis>initial_remainder</emphasis> == this-&gt;get_interim_remainder()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput>(<emphasis>reflect_remainder</emphasis> ? REFLECT(<emphasis>initial_remainder</emphasis>) : <emphasis>initial_remainder</emphasis>) ^ <emphasis>final_xor_value</emphasis> == this-&gt;checksum()</computeroutput> </para>
</postconditions></constructor>
</class><class name="crc_optimal"><template>
      <template-nontype-parameter name="Bits"><type>std::size_t</type><purpose><para>The order of the modulo-2 polynomial divisor. (<emphasis>Width</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
      <template-nontype-parameter name="TruncPoly"><type>typename ::boost::uint_t&lt; Bits &gt;::fast</type><purpose><para>The lowest coefficients of the divisor polynomial. The highest-order coefficient is omitted and always assumed to be 1. Defaults to <computeroutput>0</computeroutput>, i.e. the only non-zero term is the implicit one for x<superscript><emphasis>Bits</emphasis></superscript>. (<emphasis>Poly</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
      <template-nontype-parameter name="InitRem"><type>typename ::boost::uint_t&lt; Bits &gt;::fast</type><purpose><para>The (unaugmented) initial state of the polynomial remainder. Defaults to <computeroutput>0</computeroutput> if omitted. (<emphasis>Init</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
      <template-nontype-parameter name="FinalXor"><type>typename ::boost::uint_t&lt; Bits &gt;::fast</type><purpose><para>The (XOR) bit-mask to be applied to the output remainder, after possible reflection but before returning. Defaults to <computeroutput>0</computeroutput> (i.e. no bit changes) if omitted. (<emphasis>XorOut</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
      <template-nontype-parameter name="ReflectIn"><type>bool</type><purpose><para>If <computeroutput>true</computeroutput>, input bytes are read lowest-order bit first, otherwise highest-order bit first. Defaults to <computeroutput>false</computeroutput> if omitted. (<emphasis>RefIn</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
      <template-nontype-parameter name="ReflectRem"><type>bool</type><purpose><para>If <computeroutput>true</computeroutput>, the output remainder is reflected before the XOR-mask. Defaults to <computeroutput>false</computeroutput> if omitted. (<emphasis>RefOut</emphasis> from the RMCA)</para></purpose></template-nontype-parameter>
    </template><purpose>Table-driven CRC computer, usable as a function object. </purpose><description><para>Objects of this type compute the CRC checksum of submitted data, where said data can be entered piecemeal through several different kinds of groupings. Modulo-2 polynomial division steps are performed byte-wise, aided by the use of pre-computation tables. Said division uses the altered algorithm, so any data has to be unaugmented.</para><para>

<xrefsect id="todo_1_todo000001"><xreftitle>Todo</xreftitle><xrefdescription><para>Get rid of the default value for <emphasis>TruncPoly</emphasis>. Choosing a divisor is an important decision with many factors, so a default is never useful, especially a bad one. </para>
</xrefdescription></xrefsect></para></description><typedef name="value_type"><purpose>The register type used for computations. </purpose><description><para>This type is used for CRC calculations and is the type for any returned checksums and returned or submitted remainders, (truncated) divisors, or XOR masks. It is a built-in unsigned integer type. </para></description><type>boost::uint_t&lt; Bits &gt;::fast</type></typedef>
<method-group name="public member functions">
<method name="BOOST_STATIC_CONSTANT"><type/><parameter name=""><paramtype>std::size_t</paramtype></parameter><parameter name=""><paramtype>bit_count</paramtype><default>Bits</default></parameter></method>
<method name="BOOST_STATIC_CONSTANT"><type/><parameter name=""><paramtype>value_type</paramtype></parameter><parameter name=""><paramtype>truncated_polynominal</paramtype><default>TruncPoly</default></parameter><purpose>A copy of <emphasis>TruncPoly</emphasis> provided for meta-programming purposes. </purpose></method>
<method name="BOOST_STATIC_CONSTANT"><type/><parameter name=""><paramtype>value_type</paramtype></parameter><parameter name=""><paramtype>initial_remainder</paramtype><default>InitRem</default></parameter><purpose>A copy of <emphasis>InitRem</emphasis> provided for meta-programming purposes. </purpose></method>
<method name="BOOST_STATIC_CONSTANT"><type/><parameter name=""><paramtype>value_type</paramtype></parameter><parameter name=""><paramtype>final_xor_value</paramtype><default>FinalXor</default></parameter><purpose>A copy of <emphasis>FinalXor</emphasis> provided for meta-programming purposes. </purpose></method>
<method name="BOOST_STATIC_CONSTANT"><type/><parameter name=""><paramtype>bool</paramtype></parameter><parameter name=""><paramtype>reflect_input</paramtype><default>ReflectIn</default></parameter><purpose>A copy of <emphasis>ReflectIn</emphasis> provided for meta-programming purposes. </purpose></method>
<method name="BOOST_STATIC_CONSTANT"><type/><parameter name=""><paramtype>bool</paramtype></parameter><parameter name=""><paramtype>reflect_remainder</paramtype><default>ReflectRem</default></parameter><purpose>A copy of <emphasis>ReflectRem</emphasis> provided for meta-programming purposes. </purpose></method>
<method name="get_truncated_polynominal" cv="const"><type>value_type</type><purpose>Return the (truncated) polynomial divisor. </purpose><description><para>Returns a representation of the polynomial divisor. The value of the 2<superscript>i</superscript> bit is the value of the coefficient of the polynomial's x<superscript>i</superscript> term. The omitted bit for x<superscript>(#bit_count)</superscript> term is always 1.</para><para>
</para></description><returns><para>The bit-packed list of coefficients. If the bit-length of value_type exceeds #bit_count, the values of higher-placed bits should be ignored (even any for x<superscript>(#bit_count)</superscript>) since they're unregulated. </para>
</returns></method>
<method name="get_initial_remainder" cv="const"><type>value_type</type><purpose>Return what the polynomial remainder was set to during construction. </purpose><description><para>Returns a representation of the polynomial remainder before any input has been submitted. The value of the 2<superscript>i</superscript> bit is the value of the coefficient of the polynomial's x<superscript>i</superscript> term.</para><para>
</para></description><returns><para>The bit-packed list of coefficients. If the bit-length of value_type exceeds #bit_count, the values of higher-placed bits should be ignored since they're unregulated. </para>
</returns></method>
<method name="get_final_xor_value" cv="const"><type>value_type</type><purpose>Return the XOR-mask used during output processing. </purpose><description><para>Returns the mask to be used during creation of a checksum. The mask is used for an exclusive-or (XOR) operation applied bit-wise to the interim remainder representation (after any reflection, if get_reflect_remainder() returns <computeroutput>true</computeroutput>).</para><para>
</para></description><returns><para>The bit-mask. If the bit-length of value_type exceeds #bit_count, the values of higher-placed bits should be ignored since they're unregulated. </para>
</returns></method>
<method name="get_reflect_input" cv="const"><type>bool</type><purpose>Check if input-bytes will be reflected before processing. </purpose><description><para>Returns a whether or not a submitted byte will be "reflected" before it is used to update the interim remainder. Only the byte-wise operations process_byte, process_block, and process_bytes are affected.</para><para>
</para></description></method>
<method name="get_reflect_remainder" cv="const"><type>bool</type><purpose>Check if the remainder will be reflected during output processing. </purpose><description><para>Indicates if the interim remainder will be "reflected" before it is passed to the XOR-mask stage when returning a checksum.</para><para>
</para></description></method>
<method name="get_interim_remainder" cv="const"><type>value_type</type><purpose>Return the remainder based from already-processed bits. </purpose><description><para>Returns a representation of the polynomial remainder after all the input submissions since construction or the last reset call. The value of the 2<superscript>i</superscript> bit is the value of the coefficient of the polynomial's x<superscript>i</superscript> term. If CRC processing gets interrupted here, retain the value returned, and use it to start up the next CRC computer where you left off (with reset(value_type) or construction). The next computer has to have its other parameters compatible with this computer.</para><para>
</para></description><returns><para>The bit-packed list of coefficients. If the bit-length of value_type exceeds #bit_count, the values of higher-placed bits should be ignored since they're unregulated. No output processing (reflection or XOR mask) has been applied to the value. </para>
</returns></method>
<method name="reset"><type>void</type><parameter name="new_rem"><paramtype>value_type</paramtype><default>initial_remainder</default><description><para>The (unaugmented) state of the polynomial remainder starting from this point, with no output processing applied. Defaults to <computeroutput>this-&gt;get_initial_remainder()</computeroutput> if omitted.</para></description></parameter><purpose>Change the interim remainder to either a given value or the initial one. </purpose><description><para>Changes the interim polynomial remainder to <emphasis>new_rem</emphasis>, purging any influence previously submitted input has had. The value of the 2<superscript>i</superscript> bit is the value of the coefficient of the polynomial's x<superscript>i</superscript> term.</para><para>


</para></description><postconditions><para><computeroutput><emphasis>new_rem</emphasis> == this-&gt;get_interim_remainder()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput>((this-&gt;get_reflect_remainder() ? REFLECT(<emphasis>new_rem</emphasis>) : <emphasis>new_rem</emphasis>) ^ this-&gt;get_final_xor_value()) == this-&gt;checksum()</computeroutput> </para>
</postconditions></method>
<method name="process_byte"><type>void</type><parameter name="byte"><paramtype>unsigned char</paramtype><description><para>The new input byte.</para></description></parameter><purpose>Submit a single byte for input processing. </purpose><description><para>Updates the interim remainder with a byte's worth of altered-CRC-division steps. The bits within the byte are processed from the highest place down if <computeroutput>this-&gt;get_reflect_input()</computeroutput> is <computeroutput>false</computeroutput>, and lowest place up otherwise.</para><para>

<note><para>Any modulo-2 polynomial divisions may use a table of pre-computed remainder changes (as XOR masks) to speed computation when reading data byte-wise. </para>
</note>
</para></description><postconditions><para>The interim remainder is updated though <computeroutput>CHAR_BIT</computeroutput> modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs.</para>
</postconditions></method>
<method name="process_block"><type>void</type><parameter name="bytes_begin"><paramtype>void const *</paramtype><description><para>The address where the memory block begins. </para></description></parameter><parameter name="bytes_end"><paramtype>void const *</paramtype><description><para>Points to one-byte past the address of the memory block's last byte, or <emphasis>bytes_begin</emphasis> if no bytes are to be read.</para></description></parameter><purpose>Submit a memory block for input processing, iterator-pair style. </purpose><description><para>Updates the interim remainder with several bytes' worth of altered-CRC-division steps. The bits within each byte are processed from the highest place down if <computeroutput>this-&gt;get_reflect_input()</computeroutput> is <computeroutput>false</computeroutput>, and lowest place up otherwise. The bytes themselves are processed starting from the one pointed by <emphasis>bytes_begin</emphasis> until <emphasis>bytes_end</emphasis> is reached through forward iteration, treating the two pointers as if they point to <computeroutput>unsigned char</computeroutput> objects.</para><para>




<note><para>Any modulo-2 polynomial divisions may use a table of pre-computed remainder changes (as XOR masks) to speed computation when reading data byte-wise. </para>
</note>
</para></description><requires><para><emphasis>bytes_end</emphasis> has to equal <emphasis>bytes_begin</emphasis> if the latter is <computeroutput>NULL</computeroutput> or otherwise doesn't point to a valid buffer. </para>
</requires><requires><para><emphasis>bytes_end</emphasis>, if not equal to <emphasis>bytes_begin</emphasis>, has to point within or one-byte-past the same buffer <emphasis>bytes_begin</emphasis> points into. </para>
</requires><requires><para><emphasis>bytes_end</emphasis> has to be reachable from <emphasis>bytes_begin</emphasis> through a finite number of forward byte-pointer increments.</para>
</requires><postconditions><para>The interim remainder is updated though <computeroutput>CHAR_BIT * (((unsigned char const *) bytes_end) - ((unsigned char const *) bytes_begin))</computeroutput> modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs.</para>
</postconditions></method>
<method name="process_bytes"><type>void</type><parameter name="buffer"><paramtype>void const *</paramtype><description><para>The address where the memory block begins. </para></description></parameter><parameter name="byte_count"><paramtype>std::size_t</paramtype><description><para>The number of bytes in the memory block.</para></description></parameter><purpose>Submit a memory block for input processing, pointer-and-size style. </purpose><description><para>Updates the interim remainder with several bytes' worth of altered-CRC-division steps. The bits within each byte are processed from the highest place down if <computeroutput>this-&gt;get_reflect_input()</computeroutput> is <computeroutput>false</computeroutput>, and lowest place up otherwise. The bytes themselves are processed starting from the one pointed by <emphasis>buffer</emphasis>, forward-iterated (as if the pointed-to objects were of <computeroutput>unsigned char</computeroutput>) until <emphasis>byte_count</emphasis> bytes are read.</para><para>



<note><para>Any modulo-2 polynomial divisions may use a table of pre-computed remainder changes (as XOR masks) to speed computation when reading data byte-wise. </para>
</note>
</para></description><requires><para><emphasis>byte_count</emphasis> has to equal 0 if <emphasis>buffer</emphasis> is <computeroutput>NULL</computeroutput> or otherwise doesn't point to valid memory. </para>
</requires><requires><para>If <emphasis>buffer</emphasis> points within valid memory, then that block has to have at least <emphasis>byte_count</emphasis> more valid bytes allocated from that point.</para>
</requires><postconditions><para>The interim remainder is updated though <computeroutput>CHAR_BIT * <emphasis>byte_count</emphasis></computeroutput> modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs.</para>
</postconditions></method>
<method name="checksum" cv="const"><type>value_type</type><purpose>Return the checksum of the already-processed bits. </purpose><description><para>Computes the checksum of all the submitted bits since construction or the last call to reset. The checksum will be the raw checksum, i.e. the (interim) remainder after all the modulo-2 polynomial division, plus any output processing.</para><para>
<note><para>Since checksums are meant to be compared, any higher-placed bits (when the bit-length of value_type exceeds #bit_count) will be set to 0. </para>
</note>
</para></description><returns><para><computeroutput>(this-&gt;get_reflect_remainder() ? REFLECT(this-&gt;get_interim_remainder()) : this-&gt;get_interim_remainder()) ^ this-&gt;get_final_xor_value()</computeroutput></para>
</returns></method>
<method name="operator()"><type>void</type><parameter name="byte"><paramtype>unsigned char</paramtype><description><para>The new input byte.</para></description></parameter><purpose>Submit a single byte for input processing, suitable for the STL. </purpose><description><para>Updates the interim remainder with a byte's worth of altered-CRC-division steps. The bits within the byte are processed from the highest place down if <computeroutput>this-&gt;get_reflect_input()</computeroutput> is <computeroutput>false</computeroutput>, and lowest place up otherwise. This function is meant to present a function-object interface to code that wants to process a stream of bytes with <computeroutput>std::for_each</computeroutput> or similar range-processing algorithms. Since some of these algorithms takes their function object by value, make sure to copy back the result to this object so the updates can be remembered.</para><para>

<note><para>Any modulo-2 polynomial divisions may use a table of pre-computed remainder changes (as XOR masks) to speed computation when reading data byte-wise. </para>
</note>
</para></description><postconditions><para>The interim remainder is updated though <computeroutput>CHAR_BIT</computeroutput> modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs.</para>
</postconditions></method>
<method name="operator()" cv="const"><type>value_type</type><purpose>Return the checksum of the already-processed bits, suitable for the STL. </purpose><description><para>Computes the checksum of all the submitted bits since construction or the last call to reset. The checksum will be the raw checksum, i.e. the (interim) remainder after all the modulo-2 polynomial division, plus any output processing. This function is meant to present a function-object interface to code that wants to receive data like <computeroutput>std::generate_n</computeroutput> or similar data-processing algorithms. Note that if this object is used as a generator multiple times without an intervening mutating operation, the same value will always be returned.</para><para>
<note><para>Since checksums are meant to be compared, any higher-placed bits (when the bit-length of value_type exceeds #bit_count) will be set to 0. </para>
</note>
</para></description><returns><para><computeroutput>(this-&gt;get_reflect_remainder() ? REFLECT(this-&gt;get_interim_remainder()) : this-&gt;get_interim_remainder()) ^ this-&gt;get_final_xor_value()</computeroutput></para>
</returns></method>
</method-group>
<constructor specifiers="explicit"><parameter name="init_rem"><paramtype>value_type</paramtype><default>initial_remainder</default><description><para>The (unaugmented) initial state of the polynomial remainder. Defaults to #initial_remainder if omitted.</para></description></parameter><purpose>Create a computer, giving an initial remainder if desired. </purpose><description><para>Constructs a <computeroutput><classname alt="boost::crc_optimal">crc_optimal</classname></computeroutput> object with a particular CRC formula to be processed upon receiving input. The initial remainder may be overridden.</para><para>







</para></description><postconditions><para><computeroutput>#truncated_polynominal == this-&gt;get_truncated_polynominal()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput>#initial_remainder == this-&gt;get_initial_remainder()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput>#final_xor_value == this-&gt;get_final_xor_value()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput>#reflect_input == this-&gt;get_reflect_input()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput>#reflect_remainder == this-&gt;get_reflect_remainder()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput><emphasis>init_rem</emphasis> == this-&gt;get_interim_remainder()</computeroutput> </para>
</postconditions><postconditions><para><computeroutput>(#reflect_remainder ? REFLECT(<emphasis>init_rem</emphasis>) : <emphasis>init_rem</emphasis>) ^ #final_xor_value == this-&gt;checksum()</computeroutput> </para>
</postconditions></constructor>
</class><typedef name="crc_16_type"><purpose>Computation type for ARC|CRC-16|CRC-IBM|CRC-16/ARC|CRC-16/LHA standard. </purpose><type><classname>crc_optimal</classname>&lt; 16, 0x8005, 0, 0, true, true &gt;</type></typedef>
<typedef name="crc_ccitt_false_t"><purpose>Computation type for CRC-16/CCITT-FALSE standard. </purpose><type><classname>crc_optimal</classname>&lt; 16, 0x1021, 0xFFFF, 0, false, false &gt;</type></typedef>
<typedef name="crc_ccitt_type"><purpose>Computation type for the CRC mistakenly called the CCITT standard. </purpose><type>crc_ccitt_false_t</type></typedef>
<typedef name="crc_ccitt_true_t"><description><para>Computation type for the actual KERMIT|CRC-16/CCITT|CRC-16/CCITT-TRUE|CRC-CCITT standard </para></description><type><classname>crc_optimal</classname>&lt; 16, 0x1021, 0, 0, true, true &gt;</type></typedef>
<typedef name="crc_xmodem_type"><description><para>Computation type that I mistakenly called the XMODEM standard; it inverts both reflection parameters and reflects the truncated divisor (Don't use?!) </para></description><type><classname>crc_optimal</classname>&lt; 16, 0x8408, 0, 0, true, true &gt;</type></typedef>
<typedef name="crc_xmodem_t"><purpose>Computation type for the actual XMODEM|ZMODEM|CRC-16/ACORN standard. </purpose><type><classname>crc_optimal</classname>&lt; 16, 0x1021, 0, 0, false, false &gt;</type></typedef>
<typedef name="crc_32_type"><purpose>Computation type for CRC-32|CRC-32/ADCCP|PKZIP standard. </purpose><type><classname>crc_optimal</classname>&lt; 32, 0x04C11DB7, 0xFFFFFFFF, 0xFFFFFFFF, true, true &gt;</type></typedef>
<function name="crc"><type>uint_t&lt; Bits &gt;::fast</type><template>
          <template-nontype-parameter name="Bits"><type>std::size_t</type><purpose><para>The order of the modulo-2 polynomial divisor. (<emphasis>Width</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
          <template-nontype-parameter name="TruncPoly"><type>typename ::boost::uint_t&lt; Bits &gt;::fast</type><purpose><para>The lowest coefficients of the divisor polynomial. The highest-order coefficient is omitted and always assumed to be 1. (<emphasis>Poly</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
          <template-nontype-parameter name="InitRem"><type>typename ::boost::uint_t&lt; Bits &gt;::fast</type><purpose><para>The (unaugmented) initial state of the polynomial remainder. (<emphasis>Init</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
          <template-nontype-parameter name="FinalXor"><type>typename ::boost::uint_t&lt; Bits &gt;::fast</type><purpose><para>The (XOR) bit-mask to be applied to the output remainder, after possible reflection but before returning. (<emphasis>XorOut</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
          <template-nontype-parameter name="ReflectIn"><type>bool</type><purpose><para>If <computeroutput>True</computeroutput>, input bytes are read lowest-order bit first, otherwise highest-order bit first. (<emphasis>RefIn</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
          <template-nontype-parameter name="ReflectRem"><type>bool</type><purpose><para>If <computeroutput>True</computeroutput>, the output remainder is reflected before the XOR-mask. (<emphasis>RefOut</emphasis> from the RMCA)</para></purpose></template-nontype-parameter>
        </template><parameter name="buffer"><paramtype>void const *</paramtype><description><para>The address where the memory block begins. </para></description></parameter><parameter name="byte_count"><paramtype>std::size_t</paramtype><description><para>The number of bytes in the memory block.</para></description></parameter><purpose>Compute the (unaugmented) CRC of a memory block. </purpose><description><para>Computes the polynomial remainder of a CRC run, assuming that <emphasis>buffer</emphasis> and <emphasis>byte_count</emphasis> describe a memory block representing the polynomial dividend. The division steps are altered so the result directly gives a checksum, without need to augment the memory block with scratch-space bytes. The first byte is considered the highest order, going down for subsequent bytes.</para><para>



<note><para>Unaugmented-style CRC runs perform modulo-2 polynomial division in an altered order. The trailing <emphasis>Bits</emphasis> number of zero-valued bits needed to extracted an (unprocessed) checksum is virtually moved to near the beginning of the message. This is OK since the XOR operation is commutative and associative. It also means that you can get a checksum anytime. Since data is being read byte-wise, a table of pre-computed remainder changes (as XOR masks) can be used to speed computation. </para>
</note>
</para></description><requires><para>0 &lt; <emphasis>Bits</emphasis> &lt;= <computeroutput>std::numeric_limits&lt;uintmax_t&gt;::digits</computeroutput> </para>
</requires><returns><para>The checksum, which is the last (interim) remainder plus any output processing.</para>
</returns></function>
<function name="augmented_crc"><type>uint_t&lt; Bits &gt;::fast</type><template>
          <template-nontype-parameter name="Bits"><type>std::size_t</type><purpose><para>The order of the modulo-2 polynomial divisor. (<emphasis>Width</emphasis> from the RMCA) </para></purpose></template-nontype-parameter>
          <template-nontype-parameter name="TruncPoly"><type>typename ::boost::uint_t&lt; Bits &gt;::fast</type><purpose><para>The lowest coefficients of the divisor polynomial. The highest-order coefficient is omitted and always assumed to be 1. (<emphasis>Poly</emphasis> from the RMCA)</para></purpose></template-nontype-parameter>
        </template><parameter name="buffer"><paramtype>void const *</paramtype><description><para>The address where the memory block begins. </para></description></parameter><parameter name="byte_count"><paramtype>std::size_t</paramtype><description><para>The number of bytes in the memory block. </para></description></parameter><parameter name="initial_remainder"><paramtype>typename uint_t&lt; Bits &gt;::fast</paramtype><default>0u</default><description><para>The initial state of the polynomial remainder, defaulting to zero if omitted. If you are reading a memory block in multiple runs, put the return value of the previous run here. (Note that initial-remainders given by RMCA parameter lists, as <emphasis>Init</emphasis>, assume that the initial remainder is in its <emphasis role="bold">unaugmented</emphasis> state, so you would need to convert the value to make it suitable for this function. I currently don't provide a conversion routine.)</para></description></parameter><purpose>Compute the CRC of a memory block, with any augmentation provided by user. </purpose><description><para>Computes the polynomial remainder of a CRC run, assuming that <emphasis>buffer</emphasis> and <emphasis>byte_count</emphasis> describe a memory block representing the polynomial dividend. The first byte is considered the highest order, going down for subsequent bytes. Within a byte, the highest-order bit is read first (corresponding to <emphasis>RefIn</emphasis> = <computeroutput>False</computeroutput> in the RMCA). Check the other parts of this function's documentation to see how a checksum can be gained and/or used.</para><para>



<note><para>Augmented-style CRC runs use straight-up modulo-2 polynomial division. Since data is being read byte-wise, a table of pre-computed remainder changes (as XOR masks) can be used to speed computation. </para>
</note>
<note><para>Reading just a memory block will yield an interim remainder, and not the final checksum. To get that checksum, allocate <emphasis>Bits</emphasis> / <computeroutput>CHAR_BIT</computeroutput> bytes directly after the block and fill them with zero values, then extend <emphasis>byte_count</emphasis> to include those extra bytes. A data block is corrupt if the return value doesn't equal your separately given checksum. </para>
</note>
<note><para>Another way to perform a check is use the zero-byte extension method, but replace the zero values with your separately-given checksum. The checksum must be loaded in big-endian order. Here corruption, in either the data block or the given checksum, is confirmed if the return value is not zero. </para>
</note>
<note><para>The two checksum techniques assume the CRC-run is performed bit-wise, while this function works byte-wise. That means that the techniques can be used only if <computeroutput>CHAR_BIT</computeroutput> divides <emphasis>Bits</emphasis> evenly! </para>
</note>
</para></description><requires><para>0 &lt; <emphasis>Bits</emphasis> &lt;= <computeroutput>std::numeric_limit&lt;uintmax_t&gt;::digits</computeroutput> </para>
</requires><returns><para>The interim remainder, if no augmentation is used. A special value if augmentation is used (see the notes). No output processing is done on the value. (In RMCA terms, <emphasis>RefOut</emphasis> is <computeroutput>False</computeroutput> and <emphasis>XorOut</emphasis> is <computeroutput>0</computeroutput>.)</para>
</returns></function>
</namespace>
<macro name="BOOST_CRC_PARM_TYPE"/>
<macro name="BOOST_CRC_OPTIMAL_NAME"/>
</header>
</library-reference>