|
|
Boost-Commit : |
From: dwalker07_at_[hidden]
Date: 2008-08-01 02:37:11
Author: dlwalker
Date: 2008-08-01 02:37:10 EDT (Fri, 01 Aug 2008)
New Revision: 47925
URL: http://svn.boost.org/trac/boost/changeset/47925
Log:
Moved around some Doxygen comments; added Doxygen comments to coding-shell class templates; moved coding-shell public member functions to outside the corresponding class definition; made size-type fixed
Text files modified:
sandbox/md5/boost/coding/coding_shell.hpp | 848 ++++++++++++++++++++++++++++++++++-----
sandbox/md5/boost/coding/md5.hpp | 131 +++--
sandbox/md5/boost/coding_fwd.hpp | 20
sandbox/md5/libs/coding/src/md5.cpp | 55 ++
4 files changed, 849 insertions(+), 205 deletions(-)
Modified: sandbox/md5/boost/coding/coding_shell.hpp
==============================================================================
--- sandbox/md5/boost/coding/coding_shell.hpp (original)
+++ sandbox/md5/boost/coding/coding_shell.hpp 2008-08-01 02:37:10 EDT (Fri, 01 Aug 2008)
@@ -1,30 +1,32 @@
// Boost coding/coding_shell.hpp header file --------------------------------//
-
-// (C) Copyright Daryle Walker 2008. Distributed under the Boost Software
-// License, Version 1.0. (See the accompanying file LICENSE_1_0.txt or a copy
-// at <http://www.boost.org/LICENSE_1_0.txt>.)
-
-// See <http://www.boost.org/libs/coding> for documentation.
-
/** \file
- \brief Definitions of coding shell helper class templates
+ \brief Definitions of the coding shell helper class templates.
+
+ \author Daryle Walker
Contains the definition of templates that encapsulate bit- and byte-encoding
computer types, given a coding kernel.
+
+ (C) Copyright Daryle Walker 2008. Distributed under the Boost Software
+ License, Version 1.0. (See the accompanying file LICENSE_1_0.txt or a copy
+ at <http://www.boost.org/LICENSE_1_0.txt>.)
*/
+// See <http://www.boost.org/libs/coding> for documentation.
#ifndef BOOST_CODING_CODING_SHELL_HPP
#define BOOST_CODING_CODING_SHELL_HPP
#include <boost/coding_fwd.hpp>
-#include <boost/assert.hpp> // for BOOST_ASSERT
-#include <boost/mpl/if.hpp> // for boost::mpl::if_c
-#include <boost/mpl/int.hpp> // for boost::mpl::int_
-#include <boost/typeof/typeof.hpp> // for BOOST_AUTO
+#include <boost/assert.hpp> // for BOOST_ASSERT
+#include <boost/mpl/if.hpp> // for boost::mpl::if_c
+#include <boost/mpl/int.hpp> // for boost::mpl::int_
+#include <boost/serialization/access.hpp> // for boost::serialization::access
+#include <boost/typeof/typeof.hpp> // for BOOST_AUTO
#include <algorithm> // for std::copy, equal
#include <climits> // for CHAR_BIT
+#include <cstddef> // for std::size_t
namespace boost
@@ -35,9 +37,39 @@
// Byte-processing coding shell class template declaration -----------------//
-template < class ByteProcessor, typename SizeType >
+/** \brief A presentation layer for encapsulating byte-processing.
+
+ This class template can wrap a byte-computation class type. This template
+ can provide an easy interface for a computation type, or a family of
+ computation types can share an already-implemented interface. The
+ separation of concerns between presentation and computation can ease
+ debugging, since the two families of methods are in different types.
+
+ \pre <i>(Move \p ByteProcessor support list here)</i>.
+
+ \tparam ByteProcessor The byte-processing class type, where all of this
+ class template's functionality is routed to. It must
+ support:
+ - copying (either through assignment operator or
+ constructor); default construction recommended.
+ - a memeber type \c consumed_type that compatible
+ with a byte, like <code>unsigned char</code>.
+ - a member type \c product_type (that's "normal")
+ - a (non-<code>const</code>) member <code>operator
+ ()</code> that takes a single \c consumed_type
+ argument.
+ - equality operators (at least <code>==</code>),
+ member or free.
+ - a (<code>const</code>) member <code>operator
+ ()</code> that takes nothing and returns a
+ \c product_type value.
+ - serialization (through Boost.Serialization).
+ */
+template < class ByteProcessor >
class byte_coding_shell
{
+ typedef byte_coding_shell self_type;
+
class applicator
{
friend class byte_coding_shell;
@@ -54,106 +86,249 @@
public:
// Types
- typedef ByteProcessor processor_type;
- typedef SizeType size_type;
- typedef typename ByteProcessor::value_type value_type;
+ /** \brief Type of the byte-processing engine
+
+ Represents the type check-summing bytes.
+ */
+ typedef ByteProcessor processor_type;
+ /** \brief Type of size values
+
+ Represents the type used for sizing parameters.
+ */
+ typedef std::size_t size_type;
+ /** \brief Type of the byte-processing result
+
+ Represents the type of hashes generated.
+ */
+ typedef typename ByteProcessor::product_type value_type;
// Member data
+ /** \brief Proxy for byte-oriented application interface
+
+ Accesses an interface where <code>this->bytes</code> can be used as a
+ function object that can take a single <code>unsigned char</code> value
+ as input. It cannot be reseated from <code>*this</code>, but assignment
+ to it will copy the other's owner's state to <code>*this</code>,
+ enabling algorithms that return updated function objects to work.
+ */
applicator bytes;
// Lifetime management (use automatic copy constructor and destructor)
- explicit byte_coding_shell( processor_type const &p = processor_type() )
- : bytes( p ) {}
+ //! Default and member-initialization construction
+ explicit byte_coding_shell( processor_type const &p = processor_type() );
+ /*! \name Access */ //@{
// Accessors
- processor_type const & context() const { return this->bytes.source; }
- processor_type & context() { return this->bytes.source; }
+ //! Non-mutable access to byte-processing engine
+ processor_type const & context() const;
+ //! Mutable access to byte-processing engine
+ processor_type & context();//@}
+ /*! \name Input reading */ //@{
// Processors
- void process_byte( unsigned char byte ) { this->bytes( byte ); }
- void process_byte_copies( unsigned char value, size_type byte_count )
- { while ( byte_count-- ) this->bytes( value ); }
- void process_block( void const *bytes_begin, void const *bytes_end )
- {
- BOOST_ASSERT( !bytes_begin == !bytes_end );
-
- for ( BOOST_AUTO(p, static_cast<unsigned char const *>( bytes_begin )) ;
- p != bytes_end ; ++p )
- this->bytes( *p );
- }
- void process_bytes( void const *buffer, size_type byte_count )
- {
- BOOST_ASSERT( buffer || !byte_count );
-
- for ( BOOST_AUTO(p, static_cast<unsigned char const *>( buffer )) ;
- byte_count-- ; ++p )
- this->bytes( *p );
- }
+ //! Enters a whole byte
+ void process_byte( unsigned char byte );
+ //! Enters several bytes, all of the same value
+ void process_byte_copies( unsigned char value, size_type byte_count );
+ //! Enters a range of bytes in memory
+ void process_block( void const *bytes_begin, void const *bytes_end );
+ //! Enters a byte buffer in memory
+ void process_bytes( void const *buffer, size_type byte_count );//@}
+ /*! \name Output writing */ //@{
// Finishers
- value_type checksum() const { return this->context()(); }
+ //! Returns a completed hash
+ value_type checksum() const;//@}
+ /*! \name Operators */ //@{
// Operators (use automatic copy-assignment)
- bool operator ==( byte_coding_shell const &o ) const
- { return this->bytes == o.bytes; }
- bool operator !=( byte_coding_shell const &o ) const
- { return !this->operator ==( o ); }
-
- value_type operator ()() const { return this->checksum(); }
+ //! Equals
+ bool operator ==( self_type const &o ) const;
+ //! Not-equals
+ bool operator !=( self_type const &o ) const;
+
+ //! Application
+ value_type operator ()() const;//@} // remove?
+
+private:
+ /*! \name Persistence */ //@{
+ // Serialization
+ friend class boost::serialization::access;
+
+ //! Enables persistence with Boost.Serialization-compatible archives
+ template < class Archive >
+ void serialize( Archive &ar, const unsigned int version );//@} // not defined yet
}; // byte_coding_shell
// Bit-processing coding shell class template declarations -----------------//
+/** \brief A conversion layer: a byte-processor from a bit-processor.
+
+ This class template can represent a byte-level computation class type built
+ around a bit-level computation class type. For each byte submitted to this
+ template, \c CHAR_BIT calls to the inner bit-submission routine are done.
+ This template enables using a bit-processing object in an interface that
+ takes byte-processing objects.
+
+ \pre <i>(Move \p BitProcessor support list here)</i>.
+
+ \tparam BitProcessor The bit-processing class type, where all of this
+ class template's functionality is routed to. It must
+ support:
+ - copying (either through assignment operator or
+ constructor); default construction recommended.
+ - a memeber type \c consumed_type that compatible
+ with a Boolean, like <code>bool</code>.
+ - a member type \c product_type (that's "normal")
+ - a (non-<code>const</code>) member <code>operator
+ ()</code> that takes a single \c consumed_type
+ argument.
+ - equality operators (at least <code>==</code>),
+ member or free.
+ - a (<code>const</code>) member <code>operator
+ ()</code> that takes nothing and returns a
+ \c product_type value.
+ - serialization (through Boost.Serialization).
+ \tparam BigEndian The order the bits within a byte are processed. If
+ \c true, the most-significant bit of the byte is
+ processed first, going down to the least-significant
+ bit. If \p BigEndian is set to \c false, iteration
+ goes from least- to most-significant bit.
+ */
template < class BitProcessor, bool BigEndian >
class bit_to_byte_processor
{
+ typedef bit_to_byte_processor self_type;
+
public:
// Types
- typedef BitProcessor processor_type;
- typedef typename BitProcessor::value_type value_type;
+ /** \brief Type of the bit-processing engine
+
+ Represents the type check-summing byte-packed bits.
+ */
+ typedef BitProcessor processor_type;
+ /** \brief Type of the bit-to-byte-processing output
+
+ Represents the result type passed to the byte-processing client.
+ */
+ typedef typename BitProcessor::product_type product_type;
+ /** \brief Type of the byte-to-bit-processing input
+
+ Represents the data type passed from the byte-processing client, i.e.
+ bytes.
+ */
+ typedef unsigned char consumed_type;
// Constants
- static bool const reads_start_from_high_order_bit = BigEndian;
+ //! The bit-wise endian setting
+ static bool const reads_start_highest = BigEndian;
// Member data
+ /** \brief The wrapped bit-processing engine
+
+ Since this is a basic helper class, the wrapped object is fully exposed.
+ */
processor_type inner;
// Lifetime management (use automatic copy constructor and destructor)
- explicit bit_to_byte_processor( processor_type const &p = processor_type() )
- : inner( p ) {}
+ //! Default and member-initialization construction
+ explicit bit_to_byte_processor(processor_type const &p = processor_type() );
+ /*! \name Operators */ //@{
// Operators (use automatic copy-assignment)
- void operator ()( unsigned char byte )
+ //! Application, consumer
+ void operator ()( consumed_type byte );
+
+ //! Equals
+ bool operator ==( self_type const &o ) const;
+ //! Not-equals
+ bool operator !=( self_type const &o ) const;
+
+ //! Application, producer
+ product_type operator ()() const;//@}
+
+private:
+ /*! \name Persistence */ //@{
+ // Serialization
+ friend class boost::serialization::access;
+
+ //! Enables persistence with Boost.Serialization-compatible archives
+ template < class Archive >
+ void serialize( Archive &ar, const unsigned int version );//@} // not defined yet
+
+ // Bit-loop implementation
+ void consume_bits( unsigned char byte, int amount )
{
- using mpl::if_c;
- using mpl::int_;
+ typedef boost::mpl::int_<+1> one_type;
+ typedef boost::mpl::int_< 0> zero_type;
+ typedef boost::mpl::int_<-1> one_ntype;
+
+ typedef typename boost::mpl::if_c<BigEndian, one_type, zero_type>::type
+ starting_type;
+ typedef typename boost::mpl::if_c<BigEndian, one_ntype, one_type>::type
+ direction_type;
- typedef typename if_c< BigEndian, int_<1>, int_<0> >::type starting;
- typedef typename if_c< BigEndian, int_<-1>, int_<+1> >::type direction;
+ BOOST_ASSERT( (amount >= 0) && (amount <= CHAR_BIT) );
- for ( int i = 0, j = starting::value * (CHAR_BIT - 1) ; i < CHAR_BIT ;
- ++i, j += direction::value )
+ for ( int i = 0, j = starting_type::value * (amount - 1) ; i < amount ;
+ ++i, j += direction_type::value )
this->inner( byte & (0x01u << j) );
}
- bool operator ==( bit_to_byte_processor const &o ) const
- { return this->inner == o.inner; }
- bool operator !=( bit_to_byte_processor const &o ) const
- { return !this->operator ==( o ); }
-
- value_type operator ()() const { return this->inner(); }
+ // Don't let bit_coding_shell manually duplicate consume_bits
+ friend class bit_coding_shell<BitProcessor, BigEndian>;
}; // bit_to_byte_processor
-template < class BitProcessor, bool BigEndian, typename SizeType >
+/** \brief A presentation layer for encapsulating bit-processing.
+
+ This class template can wrap a bit-computation class type. This template
+ can provide an easy interface for a computation type, or a family of
+ computation types can share an already-implemented interface. The
+ separation of concerns between presentation and computation can ease
+ debugging, since the two families of methods are in different types.
+
+ This class template extends \c boost::coding::byte_coding_shell with
+ bit-level operations, but doesn't publicly inherit from the base class
+ template to hide the base's \c processor_type and equality operators.
+
+ \pre <i>(Move \p BitProcessor support list here)</i>.
+
+ \tparam BitProcessor The bit-processing class type, where all of this
+ class template's functionality is routed to. It must
+ support:
+ - copying (either through assignment operator or
+ constructor); default construction recommended.
+ - a memeber type \c consumed_type that compatible
+ with a Boolean, like <code>bool</code>.
+ - a member type \c product_type (that's "normal")
+ - a (non-<code>const</code>) member <code>operator
+ ()</code> that takes a single \c consumed_type
+ argument.
+ - equality operators (at least <code>==</code>),
+ member or free.
+ - a (<code>const</code>) member <code>operator
+ ()</code> that takes nothing and returns a
+ \c product_type value.
+ - serialization (through Boost.Serialization).
+ \tparam BigEndian The order the bits within a byte are processed. If
+ \c true, the most-significant bit of the byte is
+ processed first, going down to the least-significant
+ bit. If \p BigEndian is set to \c false, iteration
+ goes from least- to most-significant bit.
+
+ \see boost::coding::byte_coding_shell
+ \see boost::coding::bit_to_byte_processor
+ */
+template < class BitProcessor, bool BigEndian >
class bit_coding_shell
- : private byte_coding_shell< bit_to_byte_processor<BitProcessor, BigEndian>,
- SizeType >
+ : private byte_coding_shell<bit_to_byte_processor<BitProcessor, BigEndian> >
{
- typedef byte_coding_shell< bit_to_byte_processor<BitProcessor, BigEndian>,
- SizeType > base_type;
+ typedef byte_coding_shell< bit_to_byte_processor<BitProcessor, BigEndian> >
+ base_type;
+ typedef bit_coding_shell self_type;
class applicator
{
@@ -177,95 +352,524 @@
public:
// Types
- typedef BitProcessor processor_type;
- typedef SizeType size_type;
- typedef typename BitProcessor::value_type value_type;
+ /** \brief Type of the bit-processing engine
+
+ Represents the type check-summing bits.
+ */
+ typedef BitProcessor processor_type;
+ /** \brief Type of size values
+
+ Represents the type used for sizing parameters.
+ */
+ typedef std::size_t size_type;
+ /** \brief Type of the bit-processing result
+
+ Represents the type of hashes generated.
+ */
+ typedef typename BitProcessor::product_type value_type;
// Constants
- static bool const reads_start_from_high_order_bit = BigEndian;
+ //! The bit-wise endian setting
+ static bool const reads_start_highest = BigEndian;
// Member data
using base_type::bytes;
+ /** \brief Proxy for bit-oriented application interface
+
+ Accesses an interface where <code>this->bits</code> can be used as a
+ function object that can take a single <code>bool</code> value as input.
+ It cannot be reseated from <code>*this</code>, but assignment to it will
+ copy the other's owner's state to <code>*this</code>, enabling
+ algorithms that return updated function objects to work.
+
+ \todo The current implementation stores a reference pointer to
+ \c #bytes' wrapped engine, but copies of this sub-object will
+ allocate (with regular <code>operator new</code>) independent
+ copies of that engine. This will cause throws/crashes in
+ situtations when default memory allocation is full or disabled.
+ (And there's no choice for an alternate allocation scheme.)
+ Maybe a <code>boost::variant< BitProcessor *, BitProcessor
+ ></code> can be used, but it has its own complicated storage
+ issues, especially during assignment.
+ */
applicator bits;
// Lifetime management (use automatic destructor)
- explicit bit_coding_shell( processor_type const &p = processor_type() )
- : base_type( typename base_type::processor_type(p) )
- , bits( &this->base_type::context().inner )
- {
- }
- bit_coding_shell( bit_coding_shell const &c )
- : base_type( typename base_type::processor_type(c.context()) )
- , bits( &this->base_type::context().inner )
- {
- }
+ //! Default and member-initialization construction
+ explicit bit_coding_shell( processor_type const &p = processor_type() );
+ //! Copy construction
+ bit_coding_shell( self_type const &c );
+ /*! \name Access */ //@{
// Accessors
- processor_type const & context() const { return *this->bits.source; }
- processor_type & context() { return *this->bits.source; }
+ //! Non-mutable access to bit-processing engine
+ processor_type const & context() const;
+ //! Mutable access to bit-processing engine
+ processor_type & context();//@}
+ /*! \name Input reading */ //@{
// Processors
using base_type::process_byte;
using base_type::process_byte_copies;
using base_type::process_block;
using base_type::process_bytes;
- void process_bit( bool bit ) { this->bits( bit ); }
- void process_bits( unsigned char bits, size_type bit_count )
- {
- using mpl::if_c;
- using mpl::int_;
-
- BOOST_ASSERT( (0u <= bit_count) && (bit_count <= CHAR_BIT) );
-
- typedef typename if_c< BigEndian, int_<1>, int_<0> >::type starting;
- typedef typename if_c< BigEndian, int_<-1>, int_<+1> >::type direction;
+ //! Enters one bit for hashing
+ void process_bit( bool bit );
+ //! Enters lowest-signficant part of a byte
+ void process_bits( unsigned char bits, size_type bit_count );
+ //! Enters several bits, all of the same value
+ void process_bit_copies( bool value, size_type bit_count );
- for ( int i = (static_cast<int>(bit_count) - 1) * starting::value ;
- bit_count-- ; i += direction::value )
- this->bits( bits & (0x01u << i) );
- }
- void process_bit_copies( bool value, size_type bit_count )
- { while ( bit_count-- ) this->bits( value ); }
-
- void process_octet( uint_least8_t octet )
- { this->process_bits( octet, 8 ); }
+ //! Enters an octet
+ void process_octet( uint_least8_t octet );//@}
// Finishers
using base_type::checksum;
+ /*! \name Operators */ //@{
// Operators
- bit_coding_shell & operator =( bit_coding_shell const &c )
- {
- // Make sure "bits" isn't reseated
- static_cast<base_type &>( *this ) = static_cast<base_type const &>( c );
- return *this;
- }
- bool operator ==( bit_coding_shell const &o ) const
- { return this->bits == o.bits; }
- bool operator !=( bit_coding_shell const &o ) const
- { return !this->operator ==( o ); }
-
- using base_type::operator ();
+ //! Copy-assignment
+ self_type & operator =( self_type const &c );
+ //! Equals
+ bool operator ==( self_type const &o ) const;
+ //! Not-equals
+ bool operator !=( self_type const &o ) const;
+
+ using base_type::operator ();//@} // remove?
+
+private:
+ /*! \name Persistence */ //@{
+ // Serialization
+ friend class boost::serialization::access;
+
+ //! Enables persistence with Boost.Serialization-compatible archives
+ template < class Archive >
+ void serialize( Archive &ar, const unsigned int version );//@} // not defined yet
}; // bit_coding_shell
// Byte-processing coding shell class template member definitions ----------//
-// Put something here
+/** Constructs a byte-processor shell set to a given engine.
+
+ \param p The byte-processor engine to copy as the initial state. If not
+ given, a default-constructed engine is used.
+
+ \post \c #bytes uses a copy of \p p and refers to \c *this.
+ */
+template < class ByteProcessor >
+inline
+byte_coding_shell<ByteProcessor>::byte_coding_shell
+(
+ processor_type const & p // = processor_type()
+)
+ : bytes( p )
+{}
+
+/** Provides non-mutable access to the byte-processor engine.
+
+ \return A \c const reference to the internal engine.
+ */
+template < class ByteProcessor >
+inline typename byte_coding_shell<ByteProcessor>::processor_type const &
+byte_coding_shell<ByteProcessor>::context() const
+{ return this->bytes.source; }
+
+/** Provides mutable access to the byte-processor engine.
+
+ \post None, besides what tinkering with the result may do.
+
+ \return A non-<code>const</code> reference to the internal engine.
+ */
+template < class ByteProcessor >
+inline typename byte_coding_shell<ByteProcessor>::processor_type &
+byte_coding_shell<ByteProcessor>::context()
+{ return this->bytes.source; }
+
+/** Submits a byte for processing.
+
+ \param byte The byte value to be submitted.
+
+ \post Calls <code>this->bytes( <var>byte</var> )</code>.
+ */
+template < class ByteProcessor >
+inline void
+byte_coding_shell<ByteProcessor>::process_byte( unsigned char byte )
+{ this->bytes( byte ); }
+
+/** Submits multiple copies of a single byte value for processing.
+
+ \param value The byte value to be submitted.
+ \param byte_count The number of bytes to submit.
+
+ \post Calls <code>this->bytes( <var>value</var> )</code> \p byte_count
+ times.
+ */
+template < class ByteProcessor >
+inline void
+byte_coding_shell<ByteProcessor>::process_byte_copies
+(
+ unsigned char value,
+ size_type byte_count
+)
+{
+ while ( byte_count-- )
+ this->bytes( value );
+}
+
+/** Submits bytes, delimited by a pointer range, for processing.
+
+ \pre If \p bytes_begin is not \c NULL, then \p bytes_end has to be
+ reachable from \p bytes_begin via forward iterations of their
+ equivalent <code>unsigned char const *</code> values, otherwise
+ \p bytes_end has to be \c NULL too.
+
+ \param bytes_begin The start of the byte range to be submitted.
+ \param bytes_end One-past-the-end of the byte range in \p bytes_begin.
+
+ \post Calls <code>this->bytes( <var>x</var> )</code> for each byte \p x
+ in the given range, starting from the one at the address
+ \p bytes_begin to the byte just before the \p bytes_end mark. (If
+ the parameters are identical, then nothing is done.)
+ */
+template < class ByteProcessor >
+inline void
+byte_coding_shell<ByteProcessor>::process_block
+(
+ void const * bytes_begin,
+ void const * bytes_end
+)
+{
+ BOOST_ASSERT( !bytes_begin == !bytes_end ); // Can't test reachability!
+
+ for ( BOOST_AUTO(p, static_cast<unsigned char const *>( bytes_begin )) ;
+ p != bytes_end ; ++p )
+ this->bytes( *p );
+}
+
+/** Submits bytes, bounded by a pointer and length, for processing.
+
+ \pre If \p buffer is \c NULL, then \p byte_count must be zero.
+
+ \param buffer The start of the byte range to be submitted.
+ \param byte_count Number of (leading) bytes to use from the range.
+
+ \post Calls <code>this->bytes( <var>x</var> )</code> for each byte \p x
+ in the given range, starting from the one at the address \p buffer,
+ going forward for \p byte_count bytes total.
+ */
+template < class ByteProcessor >
+inline void
+byte_coding_shell<ByteProcessor>::process_bytes
+(
+ void const * buffer,
+ size_type byte_count
+)
+{
+ BOOST_ASSERT( buffer || !byte_count );
+
+ for ( BOOST_AUTO(p, static_cast<unsigned char const *>( buffer )) ;
+ byte_count-- ; ++p )
+ this->bytes( *p );
+}
+
+/** Provides the computed check-sum of all the submitted values. Since this is
+ a \c const member function, the engine must act as if value-submission is
+ complete whenever this function is called.
+
+ \return The check-sum.
+ */
+template < class ByteProcessor >
+inline typename byte_coding_shell<ByteProcessor>::value_type
+byte_coding_shell<ByteProcessor>::checksum() const
+{ return this->context()(); }
+
+/** Compares byte-processor shells for equivalence. Such shells are equal if
+ their internal engines are equal.
+
+ \param o The right-side operand to be compared.
+
+ \retval true \c *this and \p o are equivalent.
+ \retval false \c *this and \p o are not equivalent.
+ */
+template < class ByteProcessor >
+inline bool
+byte_coding_shell<ByteProcessor>::operator ==( self_type const &o ) const
+{ return this->bytes == o.bytes; }
+
+/** Compares byte-processor shells for non-equivalence. Such shells are unequal
+ if their internal engines are unequal.
+
+ \param o The right-side operand to be compared.
+
+ \retval true \c *this and \p o are not equivalent.
+ \retval false \c *this and \p o are equivalent.
+ */
+template < class ByteProcessor >
+inline bool
+byte_coding_shell<ByteProcessor>::operator !=( self_type const &o ) const
+{ return !this->operator ==( o ); }
+
+/** Computes the check-sum of the submitted data, through a standard generator
+ interface.
+
+ \return The generated check-sum.
+
+ \see #checksum()const
+ */
+template < class ByteProcessor >
+inline typename byte_coding_shell<ByteProcessor>::value_type
+byte_coding_shell<ByteProcessor>::operator ()() const
+{ return this->checksum(); }
// Bit-processing coding shell class templates member defintions -----------//
+/** Represents which way the bits within a submitted byte are processed.
+ */
+template < class BitProcessor, bool BigEndian >
+bool const bit_to_byte_processor<BitProcessor, BigEndian>::reads_start_highest;
+
+/** Constructs a byte-processor engine from to a given bit-processor engine.
+
+ \param p The bit-processor engine to copy as the initial state. If not
+ given, a default-constructed engine is used.
+
+ \post <code>#inner == <var>p</var></code>.
+ */
+template < class BitProcessor, bool BigEndian >
+inline
+bit_to_byte_processor<BitProcessor, BigEndian>::bit_to_byte_processor
+(
+ processor_type const & p // = processor_type()
+)
+ : inner( p )
+{}
+
+/** Submits a byte for processing, bit-wise in the initialized endian order.
+
+ \param byte The byte value to be submitted.
+
+ \post Calls <code>this->inner( <var>x</var> )</code> \c CHAR_BIT times,
+ with \p x iterating from either the highest-order bit (if
+ \c #reads_start_highest is \c true) or lowest-order bit (if \c false)
+ towards, and including, the opposite-order bit.
+ */
+template < class BitProcessor, bool BigEndian >
+inline void
+bit_to_byte_processor<BitProcessor, BigEndian>::operator ()(consumed_type byte)
+{ this->consume_bits( byte, CHAR_BIT ); }
+
+/** Compares byte-processors for equivalence. Such engines are equal if their
+ internal bit-processors are equal.
+
+ \param o The right-side operand to be compared.
+
+ \retval true \c *this and \p o are equivalent.
+ \retval false \c *this and \p o are not equivalent.
+ */
+template < class BitProcessor, bool BigEndian >
+inline bool
+bit_to_byte_processor<BitProcessor, BigEndian>::operator ==
+( self_type const &o ) const
+{ return this->inner == o.inner; }
+
+/** Compares byte-processors for non-equivalence. Such engines are unequal if
+ their internal bit-processors are unequal.
+
+ \param o The right-side operand to be compared.
+
+ \retval true \c *this and \p o are not equivalent.
+ \retval false \c *this and \p o are equivalent.
+ */
+template < class BitProcessor, bool BigEndian >
+inline bool
+bit_to_byte_processor<BitProcessor, BigEndian>::operator !=
+( self_type const &o ) const
+{ return !this->operator ==( o ); }
+
+/** Provides the computed check-sum of all the submitted bytes, through a
+ standard generator interface. Since this is a \c const member function, the
+ engine must act as if bit-submission is complete whenever this function is
+ called.
+
+ \return The check-sum.
+ */
+template < class BitProcessor, bool BigEndian >
+inline typename bit_to_byte_processor<BitProcessor, BigEndian>::product_type
+bit_to_byte_processor<BitProcessor, BigEndian>::operator ()() const
+{ return this->inner(); }
+
+/** Represents which way the bits within a submitted byte are processed.
+ */
+template < class BitProcessor, bool BigEndian >
+bool const bit_coding_shell<BitProcessor, BigEndian>::reads_start_highest;
+
+/** Constructs a bit-processor shell set to a given engine.
+
+ \param p The bit-processor engine to copy as the initial state. If not
+ given, a default-constructed engine is used.
+
+ \post \c #bytes and \c #bits use a copy of \p p and refer to \c *this.
+ */
+template < class BitProcessor, bool BigEndian >
+inline
+bit_coding_shell<BitProcessor, BigEndian>::bit_coding_shell
+(
+ processor_type const & p // = processor_type()
+)
+ : base_type( typename base_type::processor_type(p) )
+ , bits( &this->base_type::context().inner )
+{}
+
+/** Constructs a bit-processor shell with a copy of another's the significant
+ state.
+
+ \param c The bit-processor shell containing the engine to copy.
+
+ \post \c #bytes and \c #bits use a copy of
+ <code><var>c</var>.context()</code>, but refer to \c *this.
+ */
+template < class BitProcessor, bool BigEndian >
+inline
+bit_coding_shell<BitProcessor, BigEndian>::bit_coding_shell(self_type const &c)
+ : base_type( typename base_type::processor_type(c.context()) )
+ , bits( &this->base_type::context().inner )
+{}
+
+/** Provides non-mutable access to the bit-processor engine.
+
+ \return A \c const reference to the internal engine.
+ */
+template < class BitProcessor, bool BigEndian >
+inline BitProcessor const &
+bit_coding_shell<BitProcessor, BigEndian>::context() const
+{ return *this->bits.source; }
+
+/** Provides mutable access to the bit-processor engine.
+
+ \post None, besides what tinkering with the result may do.
+
+ \return A non-<code>const</code> reference to the internal engine.
+ */
+template < class BitProcessor, bool BigEndian >
+inline BitProcessor &
+bit_coding_shell<BitProcessor, BigEndian>::context()
+{ return *this->bits.source; }
+
+/** Submits a single bit for processing.
+
+ \param bit The bit value to be submitted.
+
+ \post Calls <code>this->bits( <var>bit</var> )</code>.
+ */
template < class BitProcessor, bool BigEndian >
-bool const bit_to_byte_processor<BitProcessor,
- BigEndian>::reads_start_from_high_order_bit;
+inline void
+bit_coding_shell<BitProcessor, BigEndian>::process_bit( bool bit )
+{ this->bits( bit ); }
+
+/** Submits lowest-order part of a byte for processing, bit-wise in the
+ initialized endian order.
+
+ \pre <code>0 <= <var>bit_count</var> <= CHAR_BIT</code>.
+
+ \param bits The byte from which the values are submitted.
+ \param bit_count The number of bits to submit.
+
+ \post Calls <code>this->bits( <var>x</var> )</code> \p bit_count times,
+ with \p x iterating from either the 2<sup><var>bit_count</var> -
+ 1</sup>-place (if \c #reads_start_highest is \c true) or the
+ ones-place (if \c false) towards, and including, the other mentioned
+ bit. (If \p bit_count is zero, no calls are made.)
+ */
+template < class BitProcessor, bool BigEndian >
+inline void
+bit_coding_shell<BitProcessor, BigEndian>::process_bits
+(
+ unsigned char bits,
+ size_type bit_count
+)
+{ this->base_type::context().consume_bits( bits, bit_count ); }
+
+/** Submits multiple copies of a single bit value for processing.
+
+ \param value The bit value to be submitted.
+ \param bit_count The number of bits to submit.
+
+ \post Calls <code>this->bits( <var>value</var> )</code> \p bit_count
+ times.
+ */
+template < class BitProcessor, bool BigEndian >
+inline void
+bit_coding_shell<BitProcessor, BigEndian>::process_bit_copies
+(
+ bool value,
+ size_type bit_count
+)
+{
+ while ( bit_count-- )
+ this->bits( value );
+}
+
+/** Submits an octet for processing, bit-wise in the initialized endian order.
+
+ \param octet The octet value to be submitted.
-template < class BitProcessor, bool BigEndian, typename SizeType >
-bool const bit_coding_shell<BitProcessor, BigEndian,
- SizeType>::reads_start_from_high_order_bit;
+ \post Calls <code>this->process_bits( <var>octet</var>, 8 )</code>.
+
+ \see #process_bits(unsigned char,#size_type)
+ */
+template < class BitProcessor, bool BigEndian >
+inline void
+bit_coding_shell<BitProcessor, BigEndian>::process_octet( uint_least8_t octet )
+{ this->process_bits( octet, 8 ); }
+
+/** Changes a bit-processing shell to have the same observable state as a given
+ shell. (No function object proxies are reseated, however.)
+
+ \param c The source object with the new state.
+
+ \return \c *this
+
+ \post \c #bits and \c #bytes \e still point to \c *this
+ */
+template < class BitProcessor, bool BigEndian >
+inline bit_coding_shell<BitProcessor, BigEndian> &
+bit_coding_shell<BitProcessor, BigEndian>::operator =( self_type const &c )
+{
+ static_cast<base_type &>( *this ) = static_cast<base_type const &>( c );
+ // "bits" is NOT reseated
+ return *this;
+}
+
+/** Compares bit-processor shells for equivalence. Such shells are equal if
+ their internal engines are equal.
+
+ \param o The right-side operand to be compared.
+
+ \retval true \c *this and \p o are equivalent.
+ \retval false \c *this and \p o are not equivalent.
+ */
+template < class BitProcessor, bool BigEndian >
+inline bool
+bit_coding_shell<BitProcessor, BigEndian>::operator ==(self_type const &o) const
+{ return this->bits == o.bits; }
+
+/** Compares bit-processor shells for non-equivalence. Such shells are unequal
+ if their internal engines are unequal.
+
+ \param o The right-side operand to be compared.
+
+ \retval true \c *this and \p o are not equivalent.
+ \retval false \c *this and \p o are equivalent.
+ */
+template < class BitProcessor, bool BigEndian >
+inline bool
+bit_coding_shell<BitProcessor, BigEndian>::operator !=(self_type const &o) const
+{ return !this->operator ==( o ); }
} // namespace coding
Modified: sandbox/md5/boost/coding/md5.hpp
==============================================================================
--- sandbox/md5/boost/coding/md5.hpp (original)
+++ sandbox/md5/boost/coding/md5.hpp 2008-08-01 02:37:10 EDT (Fri, 01 Aug 2008)
@@ -1,18 +1,18 @@
-// Boost md5.hpp header file ------------------------------------------------//
-
-// (C) Copyright Daryle Walker 2008. Distributed under the Boost Software
-// License, Version 1.0. (See the accompanying file LICENSE_1_0.txt or a copy
-// at <http://www.boost.org/LICENSE_1_0.txt>.)
-
-// See <http://www.boost.org/libs/coding> for documentation.
-
+// Boost coding/md5.hpp header file -----------------------------------------//
/** \file
- \brief Declarations of MD5 computation components
+ \brief Declarations of MD5 computation components.
+
+ \author Daryle Walker
Contains the declaration of types and functions used for computing MD5
message digests of given data blocks and granting I/O capability to any
applicable types.
+
+ (C) Copyright Daryle Walker 2008. Distributed under the Boost Software
+ License, Version 1.0. (See the accompanying file LICENSE_1_0.txt or a copy
+ at <http://www.boost.org/LICENSE_1_0.txt>.)
*/
+// See <http://www.boost.org/libs/coding> for documentation.
#ifndef BOOST_CODING_MD5_HPP
#define BOOST_CODING_MD5_HPP
@@ -23,7 +23,7 @@
#include <boost/assert.hpp> // for BOOST_ASSERT
#include <boost/coding/coding_shell.hpp> // for b:c:bit_coding_shell
#include <boost/coding/operations.hpp> // for b:c:queued_bit_processing_base
-#include <boost/integer.hpp> // for boost::uint_t
+#include <boost/integer.hpp> // for boost::sized_integral
#include <boost/serialization/access.hpp> // for boost::serialization::access
#include <boost/static_assert.hpp> // for BOOST_STATIC_ASSERT
#include <boost/typeof/typeof.hpp> // for BOOST_AUTO
@@ -58,28 +58,23 @@
purposes, but not ordering. Persistence is supported through the standard
text stream I/O system.
- \see boost::coding::md5_computerX
+ \see boost::coding::md5_context
+ \see boost::coding::md5_computer
\see boost::coding::compute_md5(void const*,std::size_t)
*/
class md5_digest
{
public:
- /** \brief Number of bits for word-sized quantities
-
- Represents the number of bits per word as given in RFC 1321, section 2.
- */
+ //! Number of bits for word-sized quantities
static int const bits_per_word = 32;
/** \brief Type of MD register
Represents the type of each register of the MD buffer.
*/
- typedef uint_t<bits_per_word>::least word_type;
-
- /** \brief Length of MD buffer
+ typedef boost::sized_integral<bits_per_word, unsigned>::type word_type;
- Represents the number of registers in a MD buffer.
- */
+ //! Length of MD buffer
static std::size_t const words_per_digest = 4u;
/** \brief The MD5 message digest checksum
@@ -107,7 +102,7 @@
\see boost::coding::md5_digest
\see boost::coding::compute_md5(void const*,std::size_t)
- \todo Replace "uint_fast64_t" with "uint_t<significant_bits_per_length>::
+ \todo Replace "uint_fast64_t" with "uint_t<significant_bits_per_length>::
fast", where "significant_bits_per_length" is 64. (Need to tweak
Boost.Integer to support 64-bit types.) Also need to make a
convienent constant for the "16" in the base class declaration.
@@ -145,33 +140,13 @@
using base_type::bytes;
// Constants
- /** \brief Number of bits for length quantities
-
- Represents the number of significant (low-order) bits kept for the
- message length, which can also be processed as two words, all as given
- in RFC 1321, section 3.2, paragraph 1.
- */
+ //! Number of bits for length quantities
static int const significant_bits_per_length = 2 *
md5_digest::bits_per_word;
- /** \brief Number of bits in hash queue
-
- Represents the number of submitted bits that are queued until that queue
- is emptied as a single block to be hashed, implied from RFC 1321,
- section 3.4. The count of unhashed bits is always less than this value.
- (The input processing member functions trigger a hash right after a bit
- fills the queue.)
- */
+ //! Number of bits in hash queue
static std::size_t const bits_per_block = base_type::queue_length;
- /** \brief Hashing sine table
-
- Sample of the table described in RFC 1321, section 3.4, paragraph 4.
- Its values are taken directly from the "MD5Transform" function in the
- RFC's section A.3, and are not computed. Of course, the index is
- zero-based (C++) instead of one-based (RFC).
-
- \see #generate_hashing_table
- */
+ //! Hashing sine table
static array<md5_digest::word_type, 64> const hashing_table;
// Types
@@ -247,11 +222,6 @@
/*! \name Message-digest writing */ //@{
// Output processing
//! Returns the message digest, assuming all bits have been hashed
- /** Provides the computed check-sum of all the submitted bits. (The queued
- bits are temporarily hashed with a special finishing procedure.)
-
- \return The check-sum (i.e. message digest).
- */
value_type checksum() const;//@}
/*! \name Operators */ //@{
@@ -269,15 +239,6 @@
// Extras
//! Creates a copy of #hashing_table using calculated, not static, values
- /** Constructs the hashing sine table based on the directions given in RFC
- 1321, section 3.4, paragraph 4. It should give the same values as
- #hashing_table, but it's dependent on the quality of the environment's
- math library, thereby giving a test of the environment.
-
- \return The computed hashing sine table
-
- \see #hashing_table
- */
static array<md5_digest::word_type, 64> generate_hashing_table();
private:
@@ -312,25 +273,61 @@
}; // md5_computerX
+/** \brief A computer that produces MD5 message digests from consuming bits.
+
+ This class is the bare-bones engine for the MD5 message-digest algorithm
+ described in RFC 1321. Besides computation, it also supports comparisons
+ (equivalence only, not ordering) and serialization.
+
+ \see boost::coding::md5_digest
+ */
class md5_context
{
+ typedef md5_context self_type;
+
friend class md5_computer;
public:
- typedef md5_computerX::value_type value_type;
+ typedef md5_digest product_type;
+ typedef bool consumed_type;
- void operator ()( bool bit ) { this->worker.process_bit(bit); }
- bool operator ==( md5_context const &o ) const
+ void operator ()( consumed_type bit ) { this->worker.process_bit(bit); }
+ bool operator ==( self_type const &o ) const
{ return this->worker == o.worker; }
- bool operator !=( md5_context const &o ) const
+ bool operator !=( self_type const &o ) const
{ return !this->operator ==( o ); }
- value_type operator ()() const { return this->worker.checksum(); }
+ product_type operator ()() const { return this->worker.checksum(); }
private:
md5_computerX worker;
+ // Serialization
+ friend class boost::serialization::access;
+
+ template < class Archive >
+ void serialize( Archive &ar, const unsigned int version ); // not defined yet
+
}; // md5_context
+/** \brief A class for generating a MD5 message digest from submitted data.
+
+ This class can accept data in several runs and produce a hash based on that
+ data from the MD5 message-digest algorithm described in RFC 1321. It should
+ have a similar interface to Boost.CRC, plus specialized function object
+ interfaces for bit- and byte-level processing (inspired by Boost.Bimap).
+ Comparisons are supported for check-summing purposes, but not ordering.
+ Persistence is supported though Boost.Serialization.
+
+ \see boost::coding::md5_digest
+ \see boost::coding::md5_context
+ \see boost::coding::compute_md5(void const*,std::size_t)
+
+ \todo Replace "uint_fast64_t" with "uint_t<significant_bits_per_length>::
+ fast", where "significant_bits_per_length" is 64. (Need to tweak
+ Boost.Integer to support 64-bit types.) Also need to make a
+ convienent constant for the "16" in the base class declaration.
+ (It's the number of words per block, from RFC 1321, section 3.4.)
+ */
class md5_computer
: public bit_coding_shell<md5_context, true>
{
@@ -391,6 +388,13 @@
static array<md5_digest::word_type, 64> generate_hashing_table()
{ return md5_computerX::generate_hashing_table(); }
+private:
+ // Serialization
+ friend class boost::serialization::access;
+
+ template < class Archive >
+ void serialize( Archive &ar, const unsigned int version ); // not defined yet
+
}; // md5_computer
@@ -965,6 +969,7 @@
\return The MD5 message digest of the data block.
+ \see boost::coding::md5_digest
\see boost::coding::md5_computer
*/
inline
Modified: sandbox/md5/boost/coding_fwd.hpp
==============================================================================
--- sandbox/md5/boost/coding_fwd.hpp (original)
+++ sandbox/md5/boost/coding_fwd.hpp 2008-08-01 02:37:10 EDT (Fri, 01 Aug 2008)
@@ -1,17 +1,17 @@
// Boost coding_fwd.hpp header file -----------------------------------------//
-
-// (C) Copyright Daryle Walker 2008. Distributed under the Boost Software
-// License, Version 1.0. (See the accompanying file LICENSE_1_0.txt or a copy
-// at <http://www.boost.org/LICENSE_1_0.txt>.)
-
-// See <http://www.boost.org/libs/coding> for documentation.
-
/** \file
- \brief Forward declarations of Boost.Coding components
+ \brief Forward declarations of Boost.Coding components.
+
+ \author Daryle Walker
Contains the forward declarations of Boost.Coding's public structures,
classes, and templates thereof, and any type aliases.
+
+ (C) Copyright Daryle Walker 2008. Distributed under the Boost Software
+ License, Version 1.0. (See the accompanying file LICENSE_1_0.txt or a copy
+ at <http://www.boost.org/LICENSE_1_0.txt>.)
*/
+// See <http://www.boost.org/libs/coding> for documentation.
#ifndef BOOST_CODING_FWD_HPP
#define BOOST_CODING_FWD_HPP
@@ -33,13 +33,13 @@
// From <boost/coding/coding_shell.hpp> ------------------------------------//
-template < class ByteProcessor, typename SizeType = std::size_t >
+template < class ByteProcessor >
class byte_coding_shell;
template < class BitProcessor, bool BigEndian >
class bit_to_byte_processor;
-template < class BitProcessor, bool BigEndian, typename SizeType = std::size_t >
+template < class BitProcessor, bool BigEndian >
class bit_coding_shell;
Modified: sandbox/md5/libs/coding/src/md5.cpp
==============================================================================
--- sandbox/md5/libs/coding/src/md5.cpp (original)
+++ sandbox/md5/libs/coding/src/md5.cpp 2008-08-01 02:37:10 EDT (Fri, 01 Aug 2008)
@@ -1,18 +1,18 @@
// Boost md5.cpp implementation file ----------------------------------------//
-
-// (C) Copyright Daryle Walker 2008. Distributed under the Boost Software
-// License, Version 1.0. (See the accompanying file LICENSE_1_0.txt or a copy
-// at <http://www.boost.org/LICENSE_1_0.txt>.)
-
-// See <http://www.boost.org/libs/coding> for documentation.
-
/** \file
- \brief Definitions of MD5 computation components
+ \brief Definitions of MD5 computation components.
+
+ \author Daryle Walker
Contains the definitions of constants and functions used for computing MD5
message digests of given data blocks and granting I/O capability to any
applicable types.
+
+ (C) Copyright Daryle Walker 2008. Distributed under the Boost Software
+ License, Version 1.0. (See the accompanying file LICENSE_1_0.txt or a copy
+ at <http://www.boost.org/LICENSE_1_0.txt>.)
*/
+// See <http://www.boost.org/libs/coding> for documentation.
#include <boost/coding/md5.hpp>
@@ -187,10 +187,15 @@
// MD5 message-digest class-static member definitions ----------------------//
+/** Represents the number of bits per word as given in RFC 1321, section 2.
+ */
int const md5_digest::bits_per_word;
+/** Represents the number of registers in a MD buffer.
+ */
std::size_t const md5_digest::words_per_digest;
+//! \cond
// Implementation detail object definitions --------------------------------//
namespace detail
@@ -212,15 +217,33 @@
std::size_t const md5_constants::characters_per_digest;
} // namespace detail
+//! \endcond
// MD5 message-digest computer class-static member definitions -------------//
std::size_t const md5_computerX::words_per_block;
+/** Represents the number of significant (low-order) bits kept for the
+ message length, which can also be processed as two words, all as given
+ in RFC 1321, section 3.2, paragraph 1.
+ */
int const md5_computerX::significant_bits_per_length;
+/** Represents the number of submitted bits that are queued until that queue
+ is emptied as a single block to be hashed, implied from RFC 1321,
+ section 3.4. The count of unhashed bits is always less than this value.
+ (The input processing member functions trigger a hash right after a bit
+ fills the queue.)
+ */
std::size_t const md5_computerX::bits_per_block;
+/** Sample of the table described in RFC 1321, section 3.4, paragraph 4.
+ Its values are taken directly from the "MD5Transform" function in the
+ RFC's section A.3, and are not computed. Of course, the index is
+ zero-based (C++) instead of one-based (RFC).
+
+ \see #generate_hashing_table
+ */
array<md5_digest::word_type, 64> const md5_computerX::hashing_table = { {
0xD76AA478ul,
0xE8C7B756ul,
@@ -297,7 +320,15 @@
// MD5 message-digest computer class-static member function definitions ----//
-// Generated copy of "hashing_table"; see header for notes
+/** Constructs the hashing sine table based on the directions given in RFC
+ 1321, section 3.4, paragraph 4. It should give the same values as
+ #hashing_table, but it's dependent on the quality of the environment's
+ math library, thereby giving a test of the environment.
+
+ \return The computed hashing sine table
+
+ \see #hashing_table
+ */
array<md5_digest::word_type, 64>
md5_computerX::generate_hashing_table()
{
@@ -408,7 +439,11 @@
// MD5 message-digest computation digest-output member function definition -//
-// Check-sum computation; see header for notes
+/** Provides the computed check-sum of all the submitted bits. (The queued
+ bits are temporarily hashed with a special finishing procedure.)
+
+ \return The check-sum (i.e. message digest).
+ */
md5_computerX::value_type
md5_computerX::checksum() const
{
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk