X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FParseVec.hh;h=b9ee51bc51f913794a2c7c067cf30add988d5ae8;hb=a3d3979b7daaf22ea63ca356edbfa8047dff7b78;hp=373903eea0a15b043bf974fa0c3b26c8d5dcf608;hpb=47368f306a577d1e46df69a7f729bd3893cbe5e7;p=senf.git diff --git a/Packets/ParseVec.hh b/Packets/ParseVec.hh index 373903e..b9ee51b 100644 --- a/Packets/ParseVec.hh +++ b/Packets/ParseVec.hh @@ -38,15 +38,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. + + 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 baseclass to profit from the empty-base-class optimization + \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 +110,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 +134,75 @@ 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 */ template class Parse_Vector_Container @@ -198,6 +299,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" @@ -211,4 +315,5 @@ namespace senf { // indent-tabs-mode: nil // ispell-local-dictionary: "american" // compile-command: "scons -u test" +// comment-column: 40 // End: