X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FParseList.hh;h=3b7506b819635ccf6ea1229b2c12017d1f2a5d36;hb=81ffa1c459b96dd44472bcef37e1e373934ee138;hp=945f72e8098782e78f3c831beca8691558f80574;hpb=2d6585ff852e9d282c17003ba1db0b73eb3a8500;p=senf.git diff --git a/Packets/ParseList.hh b/Packets/ParseList.hh index 945f72e..3b7506b 100644 --- a/Packets/ParseList.hh +++ b/Packets/ParseList.hh @@ -39,7 +39,23 @@ namespace senf { template class Parse_List_Container; - /** \brief + /** \brief Arbitrary sequential element collection + + A List is a sequential collection of elements. The element type is given as an arbitrary + parser. The list is more flexible than a vector: It is not limited to fixed-size elements + and it might not have direct access to the size of the collection. + + The cost is however, that a List is only a model of an STL forward sequence. The parser + provides a reduced interface to this sequence, the container wrapper provides the complete + interface. + + Pare_List makes use of a policy template argument, \a ListPolicy, to customize the way the + list is laid out. This policy is given quite some freedom in the list + implementation. It is however important, that list elements always follow each other + without padding (if padding is needed, it needs to be part of the element parser). + + \see ExampleListPolicy + \ingroup parsecollection */ template class Parse_List @@ -49,6 +65,9 @@ namespace senf { public: Parse_List(data_iterator i, state_type s); Parse_List(ListPolicy policy, data_iterator i, state_type s); + ///< Additional policy specific constructor + /**< This constructor may be used, if the policy needs + additional parameters. */ size_type bytes() const; void init() const; @@ -84,12 +103,11 @@ namespace senf { template friend class Parse_List_Container; }; - /** \brief Exmaple of a list policy. ONLY FOR EXPOSITION. + /** \brief Example of a list policy. ONLY FOR EXPOSITION. This class shows the interface which must be implemented by a list policy. It is not a list policy only a declaration of the interface: \code - tempalte struct ExampleListPolicy { // optional typedefs used to simplify all other declarations @@ -126,7 +144,7 @@ namespace senf { \endcode If necessary, you may use a different policy in the container_type. The ListPolicy must - define the elements bytes(), size() and init(), the container policy needs all theese and + define the elements bytes(), size() and init(), the container policy needs all these and additionally needs erase() and insert(). The container policy will also need the element_type, parser_type and container_type typedefs. @@ -138,13 +156,26 @@ namespace senf { typedef PacketParserBase::state_type state_type; typedef PacketParserBase::size_type size_type; + typedef void element_type; ///< Type of list elements + /**< This is the parser used to parse the list elements. */ + typedef void parser_type; ///< List parser type + /**< parser_type is the list parser used to parse a list of + this type, + e.g. senf::Parse_List. */ + typedef void container_type; ///< Type of container wrapper + /**< This is the container wrapper of the list, e.g. + Parse_List_Container. The + container may however use a \e different policy, as + long as that policy is constructible from the parser + policy. */ + static const size_type init_bytes = 0; ///< Size of a new list of this type /**< Initial size which needs to be allocated to this type of list */ size_type bytes(iterator i, state_type s) const; ///< Size of list in bytes /**< Return the complete size of the list in - bytes. Depending on the type of list, thie call may + bytes. Depending on the type of list, this call may need to completely traverse the list ... */ size_type size(iterator i, state_type s) const; ///< Number of elements in list @@ -161,13 +192,13 @@ namespace senf { void erase(iterator i, state_type s, iterator p) const; ///< Erase element from list /**< Delete the list element at p from the List (i,s). When this operation is called, the element is still part of - the list. This call must update the metadata as + the list. This call must update the meta-data as needed. The data will be removed after this call returns. */ void insert(iterator i, state_type s, iterator p) const; ///< Insert element into list /**< This is called after an element has been inserted at p - into the List (i,s) to update the metadata. */ + into the List (i,s) to update the meta-data. */ /** \brief Example of a list iterator policy. ONLY FOR EXPOSITION. @@ -222,6 +253,24 @@ namespace senf { }; }; + /** \brief Parse_List container wrapper + + This is the container wrapper used for list 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::aListCollection_t::container c (p->aListCollection()); + c.insert(c.begin(), ... ); + \endcode + + \see Parse_List + */ template class Parse_List_Container : private ListPolicy @@ -278,8 +327,12 @@ namespace senf { template void insert(iterator pos, size_type n, Value const & t); template +# ifndef DOXYGEN void insert(iterator pos, ForwardIterator f, ForwardIterator l, typename boost::disable_if< boost::is_convertible >::type * = 0); +# else + void insert(iterator pos, ForwardIterator f, ForwardIterator l); +# endif void erase(iterator pos, size_type n=1); void erase(iterator f, iterator l);