X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FParseVec.hh;h=beb953f09abb0c964f9a854d0fa6979ab04a4501;hb=82ad2ed94c12c3e53097fef92978de8c28239fab;hp=157b061bf7e0de9a68d321972aaa17822cc83e4b;hpb=2d6585ff852e9d282c17003ba1db0b73eb3a8500;p=senf.git

diff --git a/Packets/ParseVec.hh b/Packets/ParseVec.hh
index 157b061..beb953f 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 ElementParser, class Sizer> 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 <class ElementParser, class Sizer>
     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 SizeParser> class Parse_VectorN_Sizer; }
 
+    /** \brief Vector with prefix sizing
+        
+        This is a 'template typedef'. It defines a vector with a <em>directly preceding</em> 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<senf::Parse_UInt16, senf::Parse_UInt8>::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 <class ElementParser, class SizeParser>
     struct Parse_VectorN
     {
@@ -99,9 +137,39 @@ namespace senf {
                               detail::Parse_VectorN_Sizer<SizeParser> > 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) directly preceded by a numeric size field of type \a
+        size_type (another parser).
+        
+        \param[in] name field name
+        \param[in] elt_type vector element type
+        \param[in] size_type size type
+        \hideinitializer
+        \ingroup packetparsermacros
+     */
+#   define SENF_PARSER_VEC_N(name, elt_type, size_type)                                           \
+        typedef senf::Parse_VectorN<elt_type, size_type>::parser BOOST_PP_CAT(name, _vec_t);      \
+        SENF_PARSER_FIELD( name, BOOST_PP_CAT(name, _vec_t) )
+
+    /** \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 ElementParser, class Sizer>
     class Parse_Vector_Container
@@ -155,9 +223,14 @@ namespace senf {
         void insert(iterator pos, Value const & t);
         template <class Value>
         void insert(iterator pos, size_type n, Value const & t);
+#       ifndef DOXYGEN
         template <class ForwardIterator>
         void insert(iterator pos, ForwardIterator f, ForwardIterator l,
                     typename boost::disable_if< boost::is_convertible<ForwardIterator,size_type> >::type * = 0);
+#       else
+        template <class ForwardIterator>
+        void insert(iterator pos, ForwardIterator f, ForwardIterator l);
+#       endif
 
         void erase(iterator pos, size_type n=1);
         void erase(iterator f, iterator l);
@@ -199,7 +272,7 @@ namespace senf {
 
 ///////////////////////////////hh.e////////////////////////////////////////
 #endif
-#if !defined(SENF_PACKETS_DECL_ONLY) && !defined(HH_ParseVec_i_)
+#if !defined(HH_Packets__decls_) && !defined(HH_ParseVec_i_)
 #define HH_ParseVec_i_
 //#include "ParseVec.cci"
 #include "ParseVec.ct"