X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FParseVec.hh;h=11546710d490e5d31e50e1f3bcae910564581a86;hb=81ffa1c459b96dd44472bcef37e1e373934ee138;hp=21239e8be0498b83a330454bda0e2b4d9b2c7dfb;hpb=f13c1275e48e97dceb7de7925793a4c69a5aeb61;p=senf.git diff --git a/Packets/ParseVec.hh b/Packets/ParseVec.hh index 21239e8..1154671 100644 --- a/Packets/ParseVec.hh +++ b/Packets/ParseVec.hh @@ -20,6 +20,9 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief ParseVec public header */ + #ifndef HH_ParseVec_ #define HH_ParseVec_ 1 @@ -38,15 +41,33 @@ namespace senf { template class Parse_Vector_Container; - /** \brief + /** \brief Collection of fixed-size elements + + A Vector is a collection of fixed-size elements of which the size of the collection can be + determined directly (that is without traversing the collection). This allows very efficient + random access to the elements of the collection. - \todo Make the sizer a private baseclass to profit from the empty-base-class optimization + A vector is a model of an STL random-access sequence. The parser only provides a reduced + interface, the container wrapper however completes this interface. + + Parse_Vector makes use of a policy template argument, \a Sizer, to customize the way the + containers size is obtained. You will normally not instantiate Parser_Vector directly, you + will use one of the 'template typedefs' (which are templated structures since C++ does not + provide real template typedefs) provided with the policy implementations. + + \todo Make the sizer a private base-class to profit from the empty-base-class optimization + + \see ExampleVectorPolicy + \ingroup parsecollection */ template struct Parse_Vector : public PacketParserBase { Parse_Vector(data_iterator i, state_type s); Parse_Vector(Sizer sizer, data_iterator i, state_type s); + ///< Additional sizer specific constructor + /**< This constructor may be used, if the sizer needs + additional parameters. */ size_type bytes() const; void init() const; @@ -92,6 +113,23 @@ namespace senf { namespace detail { template class Parse_VectorN_Sizer; } + /** \brief Vector with prefix sizing + + This is a 'template typedef'. It defines a vector with a directly preceding size + field holding the number of vector elements. The size field is considered part of the + vector. + \code + // Define MyVector as a vector of 16bit unsigned elements with a directly preceding + // 8bit unsigned size field + typedef senf::Parse_VectorN::parser MyVector; + \endcode + + \param ElementParser \e fixed-size parser for parsing the vector elements + \param SizeParser parser for parsing the vector size (number of elements) + + \see Parse_Vector + \ingroup parsecollection + */ template struct Parse_VectorN { @@ -99,9 +137,77 @@ namespace senf { detail::Parse_VectorN_Sizer > parser; }; - /** \brief + /** \brief Example vector sizer. ONLY FOR EXPOSITION + + This class shows the interface which must be implemented by a vector sizer policy. It is not + a vector sizer, it is only a declaration of the interface: + \code + struct ExampleVectorPolicy + { + // optional typedefs used to simplify all other declarations + typedef PacketParserBase::size_type size_type; + typedef PacketParserBase::data_iterator iterator; + typedef PacketParserBase::state_type state_type; + + // mandatory members + static const size_type init_bytes = 0; + size_type size (iterator i, state_type s) const; + void size (iterator i, state_type s, size_type v) const; + iterator begin (iterator i, state_type s) const; + size_type bytes (iterator i, state_type s) const; + void init (iterator i, state_type s) const; + }; + \endcode + + A sizer may if needed define additional data members. + */ + struct ExampleVectorPolicy + { + typedef PacketParserBase::size_type size_type; + typedef PacketParserBase::data_iterator iterator; + typedef PacketParserBase::state_type state_type; + + static const size_type init_bytes = 0; ///< Size of a new vector of this size + /**< Initial size which needs to be allocated to this type + of list */ + + size_type size (iterator i, state_type s) const; ///< Get current vector size + /**< Return the current number of elements in the + vector. */ + void size (iterator i, state_type s, size_type v) const; ///< Change vector size + /**< Set the size of the vector to \a v. */ + iterator begin (iterator i, state_type s) const; + ///< Return data_iterator to first element + /**< The returned data_iterator must point to the beginning + of the first vector element. The last iterator can than + automatically be calculated from the fixed element size + and the number of vector elements. */ + size_type bytes (iterator i, state_type s) const; ///< Size of vector parser + /**< Return the size of the complete vector in bytes. This + is not necessarily the same as \c size() * \e + fixed_element_bytes. */ + void init (iterator i, state_type s) const; ///< Initialize new vector + /** Called to initialize a new vector after allocating + init_bytes number of bytes for the vector. */ + }; + + /** \brief Parse_Vector container wrapper + + This is the container wrapper used for vector parsers. The container wrapper will stay valid + after changing the collection. However the container still depends on the packet and will be + invalidated if the Packet is deallocated or if the packet size is changed from without the + container wrapper (more precisely, it is invalided if the insertion/deletion happens before + the vector in the packet data). - Holds a reference to the container ! + The vector container wrapper provides a complete STL random-access sequence interface. + + \code + SomePacket p (...); + SomePacket::aVectorCollection_t::container c (p->aVectorCollection()); + c.insert(c.begin(), ... ); + \endcode + + \see Parse_Vector */ template class Parse_Vector_Container @@ -155,9 +261,14 @@ namespace senf { void insert(iterator pos, Value const & t); template void insert(iterator pos, size_type n, Value const & t); +# ifndef DOXYGEN template void insert(iterator pos, ForwardIterator f, ForwardIterator l, typename boost::disable_if< boost::is_convertible >::type * = 0); +# else + template + void insert(iterator pos, ForwardIterator f, ForwardIterator l); +# endif void erase(iterator pos, size_type n=1); void erase(iterator f, iterator l); @@ -198,6 +309,9 @@ namespace senf { } ///////////////////////////////hh.e//////////////////////////////////////// +#endif +#if !defined(SENF_PACKETS_DECL_ONLY) && !defined(HH_ParseVec_i_) +#define HH_ParseVec_i_ //#include "ParseVec.cci" #include "ParseVec.ct" #include "ParseVec.cti"