Class template crc_optimal

boost::crc_optimal — Table-driven CRC computer, usable as a function object.

Synopsis

// In header: <boost/crc.hpp>

template<std::size_t Bits, typename ::boost::uint_t< Bits >::fast TruncPoly, 
         typename ::boost::uint_t< Bits >::fast InitRem, 
         typename ::boost::uint_t< Bits >::fast FinalXor, bool ReflectIn, 
         bool ReflectRem> 
class crc_optimal {
public:
  // types
  typedef boost::uint_t< Bits >::fast value_type;

  // construct/copy/destruct
  explicit crc_optimal(value_type = initial_remainder);

  // public member functions
   BOOST_STATIC_CONSTANT(std::size_t, bit_count = Bits);
   BOOST_STATIC_CONSTANT(value_type, truncated_polynominal = TruncPoly);
   BOOST_STATIC_CONSTANT(value_type, initial_remainder = InitRem);
   BOOST_STATIC_CONSTANT(value_type, final_xor_value = FinalXor);
   BOOST_STATIC_CONSTANT(bool, reflect_input = ReflectIn);
   BOOST_STATIC_CONSTANT(bool, reflect_remainder = ReflectRem);
  value_type get_truncated_polynominal() const;
  value_type get_initial_remainder() const;
  value_type get_final_xor_value() const;
  bool get_reflect_input() const;
  bool get_reflect_remainder() const;
  value_type get_interim_remainder() const;
  void reset(value_type = initial_remainder);
  void process_byte(unsigned char);
  void process_block(void const *, void const *);
  void process_bytes(void const *, std::size_t);
  value_type checksum() const;
  void operator()(unsigned char);
  value_type operator()() const;
};

Description

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.

Get rid of the default value for TruncPoly. Choosing a divisor is an important decision with many factors, so a default is never useful, especially a bad one.

</xrefdescription></xrefsect>

Template Parameters

```
std::size_t Bits
```
The order of the modulo-2 polynomial divisor. (Width from the RMCA)
```
typename ::boost::uint_t< Bits >::fast TruncPoly
```
The lowest coefficients of the divisor polynomial. The highest-order coefficient is omitted and always assumed to be 1. Defaults to 0, i.e. the only non-zero term is the implicit one for x^Bits. (Poly from the RMCA)
```
typename ::boost::uint_t< Bits >::fast InitRem
```
The (unaugmented) initial state of the polynomial remainder. Defaults to 0 if omitted. (Init from the RMCA)
```
typename ::boost::uint_t< Bits >::fast FinalXor
```
The (XOR) bit-mask to be applied to the output remainder, after possible reflection but before returning. Defaults to 0 (i.e. no bit changes) if omitted. (XorOut from the RMCA)
```
bool ReflectIn
```
If true, input bytes are read lowest-order bit first, otherwise highest-order bit first. Defaults to false if omitted. (RefIn from the RMCA)
```
bool ReflectRem
```
If true, the output remainder is reflected before the XOR-mask. Defaults to false if omitted. (RefOut from the RMCA)

`crc_optimal` public types

typedef boost::uint_t< Bits >::fast value_type;

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.

`crc_optimal` public construct/copy/destruct

explicit crc_optimal(value_type init_rem = initial_remainder);

Create a computer, giving an initial remainder if desired.

Constructs a crc_optimal object with a particular CRC formula to be processed upon receiving input. The initial remainder may be overridden.

Parameters:

init_rem

The (unaugmented) initial state of the polynomial remainder. Defaults to #initial_remainder if omitted.

Postconditions:

#truncated_polynominal == this->get_truncated_polynominal()

Postconditions:

#initial_remainder == this->get_initial_remainder()

Postconditions:

#final_xor_value == this->get_final_xor_value()

Postconditions:

#reflect_input == this->get_reflect_input()

Postconditions:

#reflect_remainder == this->get_reflect_remainder()

Postconditions:

init_rem == this->get_interim_remainder()

Postconditions:

(#reflect_remainder ? REFLECT(init_rem) : init_rem) ^ #final_xor_value == this->checksum()

`crc_optimal` public member functions

 BOOST_STATIC_CONSTANT(std::size_t, bit_count = Bits);

 BOOST_STATIC_CONSTANT(value_type, truncated_polynominal = TruncPoly);

A copy of TruncPoly provided for meta-programming purposes.

 BOOST_STATIC_CONSTANT(value_type, initial_remainder = InitRem);

A copy of InitRem provided for meta-programming purposes.

 BOOST_STATIC_CONSTANT(value_type, final_xor_value = FinalXor);

A copy of FinalXor provided for meta-programming purposes.

 BOOST_STATIC_CONSTANT(bool, reflect_input = ReflectIn);

A copy of ReflectIn provided for meta-programming purposes.

 BOOST_STATIC_CONSTANT(bool, reflect_remainder = ReflectRem);

A copy of ReflectRem provided for meta-programming purposes.

value_type get_truncated_polynominal() const;

Return the (truncated) polynomial divisor.

Returns a representation of the polynomial divisor. The value of the 2ⁱ bit is the value of the coefficient of the polynomial's xⁱ term. The omitted bit for x^(#bit_count) term is always 1.

Returns:

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^(#bit_count)) since they're unregulated.

```
value_type get_initial_remainder() const;
```
Return what the polynomial remainder was set to during construction.
Returns a representation of the polynomial remainder before any input has been submitted. The value of the 2ⁱ bit is the value of the coefficient of the polynomial's xⁱ term.

Returns:

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.
```
value_type get_final_xor_value() const;
```
Return the XOR-mask used during output processing.
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 true).

Returns:

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.
```
bool get_reflect_input() const;
```
Check if input-bytes will be reflected before processing.
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.
```
bool get_reflect_remainder() const;
```
Check if the remainder will be reflected during output processing.
Indicates if the interim remainder will be "reflected" before it is passed to the XOR-mask stage when returning a checksum.

value_type get_interim_remainder() const;

Return the remainder based from already-processed bits.

Returns a representation of the polynomial remainder after all the input submissions since construction or the last reset call. The value of the 2ⁱ bit is the value of the coefficient of the polynomial's xⁱ 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.

Returns:

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.

void reset(value_type new_rem = initial_remainder);

Change the interim remainder to either a given value or the initial one.

Changes the interim polynomial remainder to new_rem, purging any influence previously submitted input has had. The value of the 2ⁱ bit is the value of the coefficient of the polynomial's xⁱ term.

Parameters:

new_rem

The (unaugmented) state of the polynomial remainder starting from this point, with no output processing applied. Defaults to this->get_initial_remainder() if omitted.

Postconditions:

new_rem == this->get_interim_remainder()

Postconditions:

((this->get_reflect_remainder() ? REFLECT(new_rem) : new_rem) ^ this->get_final_xor_value()) == this->checksum()

void process_byte(unsigned char byte);

Submit a single byte for input processing.

	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.

Parameters:

byte

The new input byte.

Postconditions:

The interim remainder is updated though CHAR_BIT modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs.

void process_block(void const * bytes_begin, void const * bytes_end);

Submit a memory block for input processing, iterator-pair style.

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 this->get_reflect_input() is false, and lowest place up otherwise. The bytes themselves are processed starting from the one pointed by bytes_begin until bytes_end is reached through forward iteration, treating the two pointers as if they point to unsigned char objects.

	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.

Parameters:

`bytes_begin`	The address where the memory block begins.
`bytes_end`	Points to one-byte past the address of the memory block's last byte, or bytes_begin if no bytes are to be read.

Requires:

bytes_end has to equal bytes_begin if the latter is NULL or otherwise doesn't point to a valid buffer.

Requires:

bytes_end, if not equal to bytes_begin, has to point within or one-byte-past the same buffer bytes_begin points into.

Requires:

bytes_end has to be reachable from bytes_begin through a finite number of forward byte-pointer increments.

Postconditions:

The interim remainder is updated though CHAR_BIT * (((unsigned char const *) bytes_end) - ((unsigned char const *) bytes_begin)) modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs.

void process_bytes(void const * buffer, std::size_t byte_count);

Submit a memory block for input processing, pointer-and-size style.

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 this->get_reflect_input() is false, and lowest place up otherwise. The bytes themselves are processed starting from the one pointed by buffer, forward-iterated (as if the pointed-to objects were of unsigned char) until byte_count bytes are read.

	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.

Parameters:

`buffer`	The address where the memory block begins.
`byte_count`	The number of bytes in the memory block.

Requires:

byte_count has to equal 0 if buffer is NULL or otherwise doesn't point to valid memory.

Requires:

If buffer points within valid memory, then that block has to have at least byte_count more valid bytes allocated from that point.

Postconditions:

The interim remainder is updated though CHAR_BIT * byte_count modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs.

```
value_type checksum() const;
```
Return the checksum of the already-processed bits.
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.

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.

Returns:

(this->get_reflect_remainder() ? REFLECT(this->get_interim_remainder()) : this->get_interim_remainder()) ^ this->get_final_xor_value()

void operator()(unsigned char byte);

Submit a single byte for input processing, suitable for the STL.

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 this->get_reflect_input() is 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 std::for_each 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.

	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.

Parameters:

byte

The new input byte.

Postconditions:

The interim remainder is updated though CHAR_BIT modulo-2 polynomial divisions, where the division steps are altered for unaugmented CRCs.

```
value_type operator()() const;
```
Return the checksum of the already-processed bits, suitable for the STL.
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 std::generate_n 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.

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.

Returns:

(this->get_reflect_remainder() ? REFLECT(this->get_interim_remainder()) : this->get_interim_remainder()) ^ this->get_final_xor_value()

	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.

Boost C++ Libraries