// 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
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;
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
{
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
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);
///////////////////////////////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"