template <class ListPolicy>
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 <em>always follow each other
+ without padding</em> (if padding is needed, it needs to be part of the element parser).
+
+ \see ExampleListPolicy
+ \ingroup parsecollection
*/
template <class ListPolicy>
class Parse_List
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;
template <class Policy> 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 <class ElementParser>
struct ExampleListPolicy
{
// optional typedefs used to simplify all other declarations
\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.
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. <tt>senf::Parse_List<ExampleListPolicy></tt>. */
+ typedef void container_type; ///< Type of container wrapper
+ /**< This is the container wrapper of the list, e.g.
+ <tt>Parse_List_Container<ExampleListPolicy></tt>. 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
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.
};
};
+ /** \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 ListPolicy>
class Parse_List_Container
: private ListPolicy
template <class Value>
void insert(iterator pos, size_type n, Value const & t);
template <class ForwardIterator>
+# ifndef DOXYGEN
void insert(iterator pos, ForwardIterator f, ForwardIterator l,
typename boost::disable_if< boost::is_convertible<ForwardIterator,size_type> >::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);
}
///////////////////////////////hh.e////////////////////////////////////////
+#endif
+#if !defined(SENF_PACKETS_DECL_ONLY) && !defined(HH_ParseList_i_)
+#define HH_ParseList_i_
//#include "ParseList.cci"
#include "ParseList.ct"
#include "ParseList.cti"
projects / senf.git / blobdiff