X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FParseVec.hh;h=5d8d18030b08ac74dcbe8c8f55bb6a8a8762ee1a;hb=688f3266c15bd532194fe81e704c0a2cf320375a;hp=21239e8be0498b83a330454bda0e2b4d9b2c7dfb;hpb=f13c1275e48e97dceb7de7925793a4c69a5aeb61;p=senf.git diff --git a/Packets/ParseVec.hh b/Packets/ParseVec.hh index 21239e8..5d8d180 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 @@ -32,21 +35,40 @@ #include "ParseArray.hh" // for Parse_Array_iterator //#include "ParseVec.mpp" +#include "ParseVec.ih" ///////////////////////////////hh.p//////////////////////////////////////// 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; @@ -90,18 +112,77 @@ namespace senf { friend class Parse_Vector_Container; }; - namespace detail { template class Parse_VectorN_Sizer; } - - template + /** \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 { typedef Parse_Vector< ElementParser, - detail::Parse_VectorN_Sizer > parser; + detail::Parse_VectorN_Sizer > parser; }; - /** \brief + /** \brief Define Parse_VectorN field + + This macro is a special helper to define a senf::Parse_VectorN type field, a vector of + elements of type \a elt_type (a parser) which size is given by the \a size field. + + \code + // The size field should be declared private (size is accessible via the vector) + SENF_PARSER_PRIVATE_FIELD ( vec_size_, senf::Parse_UInt16 ); + // Define the vector, here it has 32bit unsigned integer elements + SENF_PARSER_VEC_N ( vec, _vec_size, senf::Parse_UInt32 ); + \endcode + + \param[in] name field name + \param[in] size name of field giving the vector size + \param[in] elt_type vector element type + \hideinitializer + \ingroup packetparsermacros + */ +# define SENF_PARSER_VEC_N(name, size, elt_type) \ + SENF_PARSER_VEC_N_I(SENF_PARSER_FIELD, name, size, elt_type) + + /** \brief Define Parse_VectorN field + + \see \ref SENF_PARSER_VEC_N() + \hideinitializer + \ingroup packetparsermacros + */ +# define SENF_PARSER_PRIVATE_VEC_N(name, size, elt_type) \ + SENF_PARSER_VEC_N_I(SENF_PARSER_PRIVATE_FIELD, name, size, elt_type) + + /** \brief Parse_Vector container wrapper - Holds a reference to the container ! + 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). + + 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 +236,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 +284,9 @@ namespace senf { } ///////////////////////////////hh.e//////////////////////////////////////// +#endif +#if !defined(HH_Packets__decls_) && !defined(HH_ParseVec_i_) +#define HH_ParseVec_i_ //#include "ParseVec.cci" #include "ParseVec.ct" #include "ParseVec.cti"