Subject: [Boost-commit] svn:boost r76102 - trunk/boost
From: dwalker07_at_[hidden]
Date: 2011-12-22 06:51:50
Author: dlwalker
Date: 2011-12-22 06:51:49 EST (Thu, 22 Dec 2011)
New Revision: 76102
URL: http://svn.boost.org/trac/boost/changeset/76102
Log:
Added Doxygen comments; marked some example CRC computer types as not matching their supposed standard.
Text files modified:
trunk/boost/crc.hpp | 494 +++++++++++++++++++++++++++++++++++++++
1 files changed, 492 insertions(+), 2 deletions(-)
Modified: trunk/boost/crc.hpp
==============================================================================
--- trunk/boost/crc.hpp (original)
+++ trunk/boost/crc.hpp 2011-12-22 06:51:49 EST (Thu, 22 Dec 2011)
@@ -7,6 +7,27 @@
// See <http://www.boost.org/libs/crc/> for the library's home page.
+/** \file
+ \brief A collection of function templates and class templates that compute
+ various forms of Cyclic Redundancy Codes (CRCs).
+
+ \author Daryle Walker
+
+ \version 1.5
+
+ \copyright Boost Software License, version 1.0
+
+ Contains the declarations (and definitions) of various kinds of CRC
+ computation functions, function object types, and encapsulated policy types.
+
+ \note There are references to the <i>Rocksoft™ Model CRC
+ Algorithm</i>, as described within \"<cite>A Painless Guide to CRC Error
+ Detection Algorithms</cite>,\" linked from \"<a
+ href="http://www.ross.net/crc/crcpaper.html">CRC: A Paper On CRCs</a>\" by
+ Ross Williams. It will be abbreviated \"RMCA\" in other documentation
+ blocks.
+ */
+
#ifndef BOOST_CRC_HPP
#define BOOST_CRC_HPP
@@ -68,15 +89,18 @@
// Forward declarations ----------------------------------------------------//
+//! Bit-wise CRC computer
template < std::size_t Bits >
class crc_basic;
+//! Table-driven CRC computer, usable as a function object
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly = 0u,
BOOST_CRC_PARM_TYPE InitRem = 0u,
BOOST_CRC_PARM_TYPE FinalXor = 0u, bool ReflectIn = false,
bool ReflectRem = false >
class crc_optimal;
+//! Compute the (unaugmented) CRC of a memory block
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -84,15 +108,21 @@
std::size_t byte_count
BOOST_CRC_DUMMY_PARM_TYPE );
+//! Compute the CRC of a memory block, with any augmentation provided by user
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly >
typename uint_t<Bits>::fast augmented_crc( void const *buffer,
std::size_t byte_count, typename uint_t<Bits>::fast initial_remainder = 0u
BOOST_ACRC_DUMMY_PARM_TYPE );
+//! Computation type for ARC|CRC-16|CRC-IBM|CRC-16/ARC|CRC-16/LHA standard
typedef crc_optimal<16, 0x8005, 0, 0, true, true> crc_16_type;
+//! Computation type for an incorrectly marked standard(!!)
typedef crc_optimal<16, 0x1021, 0xFFFF, 0, false, false> crc_ccitt_type;
+//! Computation type that I mistakenly called the XMODEM standard; it inverts
+//! both reflection parameters and reflects the truncated divisor (Don't use?!)
typedef crc_optimal<16, 0x8408, 0, 0, true, true> crc_xmodem_type;
+//! Computation type for CRC-32|CRC-32/ADCCP|PKZIP standard
typedef crc_optimal<32, 0x04C11DB7, 0xFFFFFFFF, 0xFFFFFFFF, true, true>
crc_32_type;
@@ -100,6 +130,7 @@
// Forward declarations for implementation detail stuff --------------------//
// (Just for the stuff that will be needed for the next two sections)
+//! \cond
namespace detail
{
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly, bool Reflect >
@@ -114,43 +145,77 @@
#endif
} // namespace detail
+//! \endcond
// Simple cyclic redundancy code (CRC) class declaration -------------------//
+/** 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.
+
+ \pre 0 \< \a Bits \<= \c std::numeric_limits<uintmax_t>::digits
+
+ \tparam Bits The order of the modulo-2 polynomial divisor. (\e Width from
+ the RMCA)
+ */
template < std::size_t Bits >
class crc_basic
{
public:
// Type
+ /** \brief The register type used for computations
+
+ 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.
+ */
typedef typename boost::uint_t<Bits>::fast value_type;
// Constant for the template parameter
+ //! A copy of \a Bits provided for meta-programming purposes
BOOST_STATIC_CONSTANT( std::size_t, bit_count = Bits );
- // Constructor
+ // Constructor (use the automatic copy-ctr, move-ctr, and dtr)
+ //! Create a computer, separately listing each needed parameter
explicit crc_basic( value_type truncated_polynominal,
value_type initial_remainder = 0, value_type final_xor_value = 0,
bool reflect_input = false, bool reflect_remainder = false );
// Internal Operations
+ //! Return the (truncated) polynomial divisor
value_type get_truncated_polynominal() const;
+ //! Return what the polynomial remainder was set to during construction
value_type get_initial_remainder() const;
+ //! Return the XOR-mask used during output processing
value_type get_final_xor_value() const;
+ //! Check if input-bytes will be reflected before processing
bool get_reflect_input() const;
+ //! Check if the remainder will be reflected during output processing
bool get_reflect_remainder() const;
+ //! Return the remainder based from already-processed bits
value_type get_interim_remainder() const;
+ //! Change the interim remainder to a new value
void reset( value_type new_rem );
+ //! Change the interim remainder back to the initial value
void reset();
// External Operations
+ //! Submit a single bit for input processing
void process_bit( bool bit );
+ //! Submit the lowest \a bit_count bits of a byte for input processing
void process_bits( unsigned char bits, std::size_t bit_count );
+ //! Submit a single byte for input processing
void process_byte( unsigned char byte );
+ //! Submit a memory block for input processing, iterator-pair style
void process_block( void const *bytes_begin, void const *bytes_end );
+ //! Submit a memory block for input processing, pointer-and-size style
void process_bytes( void const *buffer, std::size_t byte_count );
+ //! Return the checksum of the already-processed bits
value_type checksum() const;
private:
@@ -164,6 +229,35 @@
// Optimized cyclic redundancy code (CRC) class declaration ----------------//
+/** 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.
+
+ \pre 0 \< \a Bits \<= \c std::numeric_limits<uintmax_t>::digits
+
+ \tparam Bits The order of the modulo-2 polynomial divisor. (\e Width from
+ the RMCA)
+ \tparam TruncPoly The lowest coefficients of the divisor polynomial. The
+ highest-order coefficient is omitted and always assumed to be 1. Defaults
+ to \c 0, i.e. the only non-zero term is the implicit one for
+ x<sup><var>Bits</var></sup>. (\e Poly from the RMCA)
+ \tparam InitRem The (unaugmented) initial state of the polynomial
+ remainder. Defaults to \c 0 if omitted. (\e Init from the RMCA)
+ \tparam FinalXor The (XOR) bit-mask to be applied to the output remainder,
+ after possible reflection but before returning. Defaults to \c 0 (i.e. no
+ bit changes) if omitted. (\e XorOut from the RMCA)
+ \tparam ReflectIn If \c true, input bytes are read lowest-order bit first,
+ otherwise highest-order bit first. Defaults to \c false if omitted.
+ (\e RefIn from the RMCA)
+ \tparam ReflectRem If \c true, the output remainder is reflected before the
+ XOR-mask. Defaults to \c false if omitted. (\e RefOut from the RMCA)
+
+ \todo Get rid of the default value for \a TruncPoly. Choosing a divisor is
+ an important decision with many factors, so a default is never useful,
+ especially a bad one.
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -171,38 +265,59 @@
{
public:
// Type
+ //! \copydoc boost::crc_basic::value_type
typedef typename boost::uint_t<Bits>::fast value_type;
// Constants for the template parameters
+ //! \copydoc boost::crc_basic::bit_count
BOOST_STATIC_CONSTANT( std::size_t, bit_count = Bits );
+ //! A copy of \a TruncPoly provided for meta-programming purposes
BOOST_STATIC_CONSTANT( value_type, truncated_polynominal = TruncPoly );
+ //! A copy of \a InitRem provided for meta-programming purposes
BOOST_STATIC_CONSTANT( value_type, initial_remainder = InitRem );
+ //! A copy of \a FinalXor provided for meta-programming purposes
BOOST_STATIC_CONSTANT( value_type, final_xor_value = FinalXor );
+ //! A copy of \a ReflectIn provided for meta-programming purposes
BOOST_STATIC_CONSTANT( bool, reflect_input = ReflectIn );
+ //! A copy of \a ReflectRem provided for meta-programming purposes
BOOST_STATIC_CONSTANT( bool, reflect_remainder = ReflectRem );
- // Constructor
+ // Constructor (use the automatic copy-ctr, move-ctr, and dtr)
+ //! Create a computer, giving an initial remainder if desired
explicit crc_optimal( value_type init_rem = InitRem );
// Internal Operations
+ //! \copybrief boost::crc_basic::get_truncated_polynominal
value_type get_truncated_polynominal() const;
+ //! \copybrief boost::crc_basic::get_initial_remainder
value_type get_initial_remainder() const;
+ //! \copybrief boost::crc_basic::get_final_xor_value
value_type get_final_xor_value() const;
+ //! \copybrief boost::crc_basic::get_reflect_input
bool get_reflect_input() const;
+ //! \copybrief boost::crc_basic::get_reflect_remainder
bool get_reflect_remainder() const;
+ //! \copybrief boost::crc_basic::get_interim_remainder
value_type get_interim_remainder() const;
+ //! Change the interim remainder to either a given value or the initial one
void reset( value_type new_rem = InitRem );
// External Operations
+ //! \copybrief boost::crc_basic::process_byte
void process_byte( unsigned char byte );
+ //! \copybrief boost::crc_basic::process_block
void process_block( void const *bytes_begin, void const *bytes_end );
+ //! \copybrief boost::crc_basic::process_bytes
void process_bytes( void const *buffer, std::size_t byte_count );
+ //! \copybrief boost::crc_basic::checksum
value_type checksum() const;
// Operators
+ //! Submit a single byte for input processing, suitable for the STL
void operator ()( unsigned char byte );
+ //! Return the checksum of the already-processed bits, suitable for the STL
value_type operator ()() const;
private:
@@ -231,6 +346,7 @@
// Implementation detail stuff ---------------------------------------------//
+//! \cond
namespace detail
{
// Single-bit mask constant, MPL-style
@@ -482,10 +598,46 @@
} // namespace detail
+//! \endcond
// Simple CRC class function definitions -----------------------------------//
+/** Constructs a \c crc_basic object with at least the required parameters to a
+ particular CRC formula to be processed upon receiving input.
+
+ \param[in] truncated_polynominal The lowest coefficients of the divisor
+ polynomial. The highest-order coefficient is omitted and always assumed
+ to be 1. (\e Poly from the RMCA)
+ \param[in] initial_remainder The (unaugmented) initial state of the
+ polynomial remainder. Defaults to \c 0 if omitted. (\e Init from the
+ RMCA)
+ \param[in] final_xor_value The (XOR) bit-mask to be applied to the output
+ remainder, after possible reflection but before returning. Defaults to
+ \c 0 (i.e. no bit changes) if omitted. (\e XorOut from the RMCA)
+ \param[in] reflect_input If \c true, input bytes are read lowest-order bit
+ first, otherwise highest-order bit first. Defaults to \c false if
+ omitted. (\e RefIn from the RMCA)
+ \param[in] reflect_remainder If \c true, the output remainder is reflected
+ before the XOR-mask. Defaults to \c false if omitted. (\e RefOut from
+ the RMCA)
+
+ \post <code><var>truncated_polynominal</var> ==
+ this->get_truncated_polynominal()</code>
+ \post <code><var>initial_remainder</var> ==
+ this->get_initial_remainder()</code>
+ \post <code><var>final_xor_value</var> ==
+ this->get_final_xor_value()</code>
+ \post <code><var>reflect_input</var> ==
+ this->get_reflect_input()</code>
+ \post <code><var>reflect_remainder</var> ==
+ this->get_reflect_remainder()</code>
+ \post <code><var>initial_remainder</var> ==
+ this->get_interim_remainder()</code>
+ \post <code>(<var>reflect_remainder</var> ?
+ REFLECT(<var>initial_remainder</var>) : <var>initial_remainder</var>) ^
+ <var>final_xor_value</var> == this->checksum()</code>
+ */
template < std::size_t Bits >
inline
crc_basic<Bits>::crc_basic
@@ -502,6 +654,14 @@
{
}
+/** Returns a representation of the polynomial divisor. The value of the
+ 2<sup>i</sup> bit is the value of the coefficient of the polynomial's
+ x<sup>i</sup> term. The omitted bit for x<sup>#bit_count</sup> is always 1.
+
+ \return 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<sup>#bit_count</sup>) since they're unregulated.
+ */
template < std::size_t Bits >
inline
typename crc_basic<Bits>::value_type
@@ -512,6 +672,14 @@
return poly_;
}
+/** Returns a representation of the polynomial remainder before any input has
+ been submitted. The value of the 2<sup>i</sup> bit is the value of the
+ coefficient of the polynomial's x<sup>i</sup> term.
+
+ \return 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.
+ */
template < std::size_t Bits >
inline
typename crc_basic<Bits>::value_type
@@ -522,6 +690,15 @@
return init_;
}
+/** 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 \c true).
+
+ \return 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.
+ */
template < std::size_t Bits >
inline
typename crc_basic<Bits>::value_type
@@ -532,6 +709,13 @@
return final_;
}
+/** 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.
+
+ \retval true Input bytes will be read starting from the lowest-order bit.
+ \retval false Input bytes will be read starting from the highest-order bit.
+ */
template < std::size_t Bits >
inline
bool
@@ -542,6 +726,12 @@
return rft_in_;
}
+/** Indicates if the interim remainder will be \"reflected\" before it is passed
+ to the XOR-mask stage when returning a checksum.
+
+ \retval true The interim remainder is reflected before further work.
+ \retval false The interim remainder is applied to the XOR-mask as-is.
+ */
template < std::size_t Bits >
inline
bool
@@ -552,6 +742,19 @@
return rft_out_;
}
+/** Returns a representation of the polynomial remainder after all the input
+ submissions since construction or the last #reset call. The value of the
+ 2<sup>i</sup> bit is the value of the coefficient of the polynomial's
+ x<sup>i</sup> 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.
+
+ \return 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.
+ */
template < std::size_t Bits >
inline
typename crc_basic<Bits>::value_type
@@ -562,6 +765,19 @@
return rem_ & detail::low_bits_mask_c<Bits>::value;
}
+/** Changes the interim polynomial remainder to \a new_rem, purging any
+ influence previously submitted input has had. The value of the
+ 2<sup>i</sup> bit is the value of the coefficient of the polynomial's
+ x<sup>i</sup> term.
+
+ \param[in] new_rem The (unaugmented) state of the polynomial remainder
+ starting from this point, with no output processing applied.
+
+ \post <code><var>new_rem</var> == this->get_interim_remainder()</code>
+ \post <code>((this->get_reflect_remainder() ?
+ REFLECT(<var>new_rem</var>) : <var>new_rem</var>) ^
+ this->get_final_xor_value()) == this->checksum()</code>
+ */
template < std::size_t Bits >
inline
void
@@ -573,6 +789,18 @@
rem_ = new_rem;
}
+/** 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<sup>i</sup> bit is the value of the coefficient of
+ the polynomial's x<sup>i</sup> term.
+
+ \post <code>this->get_initial_remainder() ==
+ this->get_interim_remainder()</code>
+ \post <code>((this->get_reflect_remainder() ?
+ REFLECT(this->get_initial_remainder()) :
+ this->get_initial_remainder()) ^ this->get_final_xor_value())
+ == this->checksum()</code>
+ */
template < std::size_t Bits >
inline
void
@@ -583,6 +811,13 @@
this->reset( this->get_initial_remainder() );
}
+/** Updates the interim remainder with a single altered-CRC-division step.
+
+ \param[in] bit The new input bit.
+
+ \post The interim remainder is updated though a modulo-2 polynomial
+ division, where the division steps are altered for unaugmented CRCs.
+ */
template < std::size_t Bits >
inline
void
@@ -594,6 +829,21 @@
detail::crc_modulo_update<Bits>( rem_, bit, poly_ );
}
+/** Updates the interim remainder with several altered-CRC-division steps. Each
+ bit is processed separately, starting from the one at the
+ 2<sup><var>bit_count</var> - 1</sup> place, then proceeding down to the
+ lowest-placed bit. Any order imposed by
+ <code>this->get_reflect_input()</code> is ignored.
+
+ \pre 0 \< \a bit_count \<= \c CHAR_BIT
+
+ \param[in] bits The byte containing the new input bits.
+ \param[in] bit_count The number of bits in the byte to be read.
+
+ \post The interim remainder is updated though \a bit_count modulo-2
+ polynomial divisions, where the division steps are altered for unaugmented
+ CRCs.
+ */
template < std::size_t Bits >
void
crc_basic<Bits>::process_bits
@@ -613,6 +863,17 @@
}
}
+/** 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 <code>this->get_reflect_input()</code> is \c false, and lowest place
+ up otherwise.
+
+ \param[in] byte The new input byte.
+
+ \post The interim remainder is updated though \c CHAR_BIT modulo-2
+ polynomial divisions, where the division steps are altered for unaugmented
+ CRCs.
+ */
template < std::size_t Bits >
inline
void
@@ -624,6 +885,30 @@
process_bits( (rft_in_ ? detail::reflect_byte( byte ) : byte), CHAR_BIT );
}
+/** 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 <code>this->get_reflect_input()</code> is
+ \c false, and lowest place up otherwise. The bytes themselves are processed
+ starting from the one pointed by \a bytes_begin until \a bytes_end is
+ reached through forward iteration, treating the two pointers as if they
+ point to <code>unsigned char</code> objects.
+
+ \pre \a bytes_end has to equal \a bytes_begin if the latter is \c NULL or
+ otherwise doesn't point to a valid buffer.
+ \pre \a bytes_end, if not equal to \a bytes_begin, has to point within or
+ one-byte-past the same buffer \a bytes_begin points into.
+ \pre \a bytes_end has to be reachable from \a bytes_begin through a finite
+ number of forward byte-pointer increments.
+
+ \param[in] bytes_begin The address where the memory block begins.
+ \param[in] bytes_end Points to one-byte past the address of the memory
+ block's last byte, or \a bytes_begin if no bytes are to be read.
+
+ \post The interim remainder is updated though <code>CHAR_BIT * (((unsigned
+ char const *) bytes_end) - ((unsigned char const *) bytes_begin))</code>
+ modulo-2 polynomial divisions, where the division steps are altered for
+ unaugmented CRCs.
+ */
template < std::size_t Bits >
void
crc_basic<Bits>::process_block
@@ -639,6 +924,26 @@
}
}
+/** 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 <code>this->get_reflect_input()</code> is
+ \c false, and lowest place up otherwise. The bytes themselves are processed
+ starting from the one pointed by \a buffer, forward-iterated (as if the
+ pointed-to objects were of <code>unsigned char<code>) until \a byte_count
+ bytes are read.
+
+ \pre \a byte_count has to equal 0 if \a buffer is \c NULL or otherwise
+ doesn't point to valid memory.
+ \pre If \a buffer points within valid memory, then that block has to have
+ at least \a byte_count more valid bytes allocated from that point.
+
+ \param[in] buffer The address where the memory block begins.
+ \param[in] byte_count The number of bytes in the memory block.
+
+ \post The interim remainder is updated though <code>CHAR_BIT *
+ <var>byte_count</var></code> modulo-2 polynomial divisions, where the
+ division steps are altered for unaugmented CRCs.
+ */
template < std::size_t Bits >
inline
void
@@ -654,6 +959,18 @@
process_block( b, b + byte_count );
}
+/** 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.
+
+ \return <code>(this->get_reflect_remainder() ?
+ REFLECT(this->get_interim_remainder()) :
+ this->get_interim_remainder()) ^ this->get_final_xor_value()</code>
+
+ \note 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.
+ */
template < std::size_t Bits >
inline
typename crc_basic<Bits>::value_type
@@ -672,6 +989,22 @@
#define BOOST_CRC_OPTIMAL_NAME crc_optimal<Bits, TruncPoly, InitRem, \
FinalXor, ReflectIn, ReflectRem>
+/** Constructs a \c crc_optimal object with a particular CRC formula to be
+ processed upon receiving input. The initial remainder may be overridden.
+
+ \param[in] init_rem The (unaugmented) initial state of the polynomial
+ remainder. Defaults to #initial_remainder if omitted.
+
+ \post <code>#truncated_polynominal ==
+ this->get_truncated_polynominal()</code>
+ \post <code>#initial_remainder == this->get_initial_remainder()</code>
+ \post <code>#final_xor_value == this->get_final_xor_value()</code>
+ \post <code>#reflect_input == this->get_reflect_input()</code>
+ \post <code>#reflect_remainder == this->get_reflect_remainder()</code>
+ \post <code><var>init_rem</var> == this->get_interim_remainder()</code>
+ \post <code>(#reflect_remainder ? REFLECT(<var>init_rem</var>) :
+ <var>init_rem</var>) ^ #final_xor_value == this->checksum()</code>
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -685,6 +1018,7 @@
crc_table_type::init_table();
}
+//! \copydetails boost::crc_basic::get_truncated_polynominal
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -697,6 +1031,7 @@
return TruncPoly;
}
+//! \copydetails boost::crc_basic::get_initial_remainder
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -709,6 +1044,7 @@
return InitRem;
}
+//! \copydetails boost::crc_basic::get_final_xor_value
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -721,6 +1057,7 @@
return FinalXor;
}
+//! \copydetails boost::crc_basic::get_reflect_input
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -733,6 +1070,7 @@
return ReflectIn;
}
+//! \copydetails boost::crc_basic::get_reflect_remainder
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -745,6 +1083,7 @@
return ReflectRem;
}
+//! \copydetails boost::crc_basic::get_interim_remainder
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -758,6 +1097,20 @@
return helper_type::reflect( rem_ ) & detail::low_bits_mask_c<Bits>::value;
}
+/** Changes the interim polynomial remainder to \a new_rem, purging any
+ influence previously submitted input has had. The value of the
+ 2<sup>i</sup> bit is the value of the coefficient of the polynomial's
+ x<sup>i</sup> term.
+
+ \param[in] new_rem The (unaugmented) state of the polynomial remainder
+ starting from this point, with no output processing applied. Defaults to
+ <code>this->get_initial_remainder()</code> if omitted.
+
+ \post <code><var>new_rem</var> == this->get_interim_remainder()</code>
+ \post <code>((this->get_reflect_remainder() ?
+ REFLECT(<var>new_rem</var>) : <var>new_rem</var>) ^
+ this->get_final_xor_value()) == this->checksum()</code>
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -771,6 +1124,12 @@
rem_ = helper_type::reflect( new_rem );
}
+/** \copydetails boost::crc_basic::process_byte
+
+ \note 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.
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -784,6 +1143,12 @@
process_bytes( &byte, sizeof(byte) );
}
+/** \copydetails boost::crc_basic::process_block
+
+ \note 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.
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -808,6 +1173,12 @@
}
}
+/** \copydetails boost::crc_basic::process_bytes
+
+ \note 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.
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -824,6 +1195,7 @@
process_block( b, b + byte_count );
}
+//! \copydetails boost::crc_basic::checksum
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -837,6 +1209,25 @@
& detail::low_bits_mask_c<Bits>::value;
}
+/** 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 <code>this->get_reflect_input()</code> is \c false, 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
+ <code>std::for_each</code> 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.
+
+ \param[in] byte The new input byte.
+
+ \post The interim remainder is updated though \c CHAR_BIT modulo-2
+ polynomial divisions, where the division steps are altered for unaugmented
+ CRCs.
+
+ \note 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.
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -850,6 +1241,22 @@
process_byte( byte );
}
+/** 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
+ <code>std::generate_n</code> 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.
+
+ \return <code>(this->get_reflect_remainder() ?
+ REFLECT(this->get_interim_remainder()) :
+ this->get_interim_remainder()) ^ this->get_final_xor_value()</code>
+
+ \note 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.
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -865,6 +1272,43 @@
// CRC computation function definition -------------------------------------//
+/** Computes the polynomial remainder of a CRC run, assuming that \a buffer and
+ \a byte_count 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.
+
+ \pre 0 \< \a Bits \<= \c std::numeric_limits<uintmax_t>::digits
+
+ \tparam Bits The order of the modulo-2 polynomial divisor. (\e Width from
+ the RMCA)
+ \tparam TruncPoly The lowest coefficients of the divisor polynomial. The
+ highest-order coefficient is omitted and always assumed to be 1.
+ (\e Poly from the RMCA)
+ \tparam InitRem The (unaugmented) initial state of the polynomial
+ remainder. (\e Init from the RMCA)
+ \tparam FinalXor The (XOR) bit-mask to be applied to the output remainder,
+ after possible reflection but before returning. (\e XorOut from the RMCA)
+ \tparam ReflectIn If \c True, input bytes are read lowest-order bit first,
+ otherwise highest-order bit first. (\e RefIn from the RMCA)
+ \tparam ReflectRem If \c True, the output remainder is reflected before the
+ XOR-mask. (\e RefOut from the RMCA)
+
+ \param[in] buffer The address where the memory block begins.
+ \param[in] byte_count The number of bytes in the memory block.
+
+ \return The checksum, which is the last (interim) remainder plus any output
+ processing.
+
+ \note Unaugmented-style CRC runs perform modulo-2 polynomial division in
+ an altered order. The trailing \a Bits 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.
+
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly,
BOOST_CRC_PARM_TYPE InitRem, BOOST_CRC_PARM_TYPE FinalXor,
bool ReflectIn, bool ReflectRem >
@@ -885,6 +1329,52 @@
// Augmented-message CRC computation function definition -------------------//
+/** Computes the polynomial remainder of a CRC run, assuming that \a buffer and
+ \a byte_count 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
+ \e RefIn = \c False in the RMCA). Check the other parts of this function's
+ documentation to see how a checksum can be gained and/or used.
+
+ \pre 0 \< \a Bits \<= \c std::numeric_limits<uintmax_t>::digits
+
+ \tparam Bits The order of the modulo-2 polynomial divisor. (\e Width from
+ the RMCA)
+ \tparam TruncPoly The lowest coefficients of the divisor polynomial. The
+ highest-order coefficient is omitted and always assumed to be 1.
+ (\e Poly from the RMCA)
+
+ \param[in] buffer The address where the memory block begins.
+ \param[in] byte_count The number of bytes in the memory block.
+ \param[in] initial_remainder 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
+ \e Init, assume that the initial remainder is in its \b unaugmented state,
+ so you would need to convert the value to make it suitable for this
+ function. I currently don't provide a conversion routine.)
+
+ \return 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, \e RefOut is \c False and \e XorOut is \c 0.)
+
+ \note 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.
+ \note Reading just a memory block will yield an interim remainder, and not
+ the final checksum. To get that checksum, allocate \a Bits / \c CHAR_BIT
+ bytes directly after the block and fill them with zero values, then extend
+ \a byte_count to include those extra bytes. A data block is corrupt if
+ the return value doesn't equal your separately given checksum.
+ \note 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.
+ \note 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 \c CHAR_BIT divides \a Bits evenly!
+ */
template < std::size_t Bits, BOOST_CRC_PARM_TYPE TruncPoly >
typename uint_t<Bits>::fast
augmented_crc