4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
8 // This program is free software; you can redistribute it and/or modify
9 // it under the terms of the GNU General Public License as published by
10 // the Free Software Foundation; either version 2 of the License, or
11 // (at your option) any later version.
13 // This program is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License
19 // along with this program; if not, write to the
20 // Free Software Foundation, Inc.,
21 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24 \brief VectorParser public header */
26 #ifndef HH_SENF_Packets_VectorParser_
27 #define HH_SENF_Packets_VectorParser_ 1
30 #include <boost/iterator/iterator_facade.hpp>
31 #include <boost/utility.hpp>
32 #include <boost/range.hpp>
33 #include <boost/type_traits.hpp>
34 #include "PacketParser.hh"
35 #include "ArrayParser.hh" // for ArrayParser_iterator
36 #include "AuxParser.hh" // for the AuxPolicies
38 //#include "VectorParser.mpp"
39 ///////////////////////////////hh.p////////////////////////////////////////
43 template <class ElementParser, class AuxPolicy> class VectorParser_Container;
45 /** \brief Collection of fixed-size elements
47 A Vector is a collection of fixed-size elements of which the size of the collection can be
48 determined directly (that is without traversing the collection). This allows very efficient
49 random access to the elements of the collection.
51 A vector is a model of an STL random-access sequence. The parser only provides a reduced
52 interface, the container wrapper however completes this interface.
54 VectorParser makes use of a policy template argument, \a AuxPolicy, to customize the way the
55 containers size is obtained. You will normally not instantiate VectorParser directly, you
56 will use the \ref SENF_PARSER_VECTOR() helper macro.
58 \ingroup parsecollection
60 template <class ElementParser, class AuxPolicy>
62 : public PacketParserBase,
65 VectorParser(data_iterator i, state_type s);
66 VectorParser(AuxPolicy policy, data_iterator i, state_type s);
67 ///< Additional sizer specific constructor
68 /**< This constructor may be used, if the sizer needs
69 additional parameters. */
71 size_type bytes() const;
74 static const size_type init_bytes = AuxPolicy::aux_bytes;
76 ///////////////////////////////////////////////////////////////////////////
77 // Container interface
79 typedef ElementParser value_type;
80 typedef detail::ArrayParser_iterator<value_type> iterator;
81 typedef iterator const_iterator;
82 typedef VectorParser_Container<ElementParser,AuxPolicy> container;
84 size_type size() const;
87 iterator begin() const;
90 value_type operator[](difference_type i) const;
91 value_type front() const;
92 value_type back() const;
96 // The mutators provided here are those which don't take an iterator argument.
97 // If you need to pass an iterator it is much simpler and cleaner to use the
98 // 'container' wrapper
100 template <class Value> void push_back (Value value, size_type n=1) const;
101 void push_back_space (size_type n=1) const;
102 template <class Value> void push_front (Value value, size_type n=1) const;
103 void push_front_space (size_type n=1) const;
104 void resize (size_type n) const;
105 template <class Value> void resize (size_type n, Value value) const;
109 friend class VectorParser_Container<ElementParser,AuxPolicy>;
112 /** \brief VectorParser container wrapper
114 This is the container wrapper used for vector parsers. The container wrapper will stay valid
115 after changing the collection. However the container still depends on the packet and will be
116 invalidated if the Packet is deallocated or if the packet size is changed from without the
117 container wrapper (more precisely, it is invalided if the insertion/deletion happens before
118 the vector in the packet data).
120 The vector container wrapper provides a complete STL random-access sequence interface.
124 SomePacket::aVectorCollection_t::container c (p->aVectorCollection());
125 c.insert(c.begin(), ... );
130 template <class ElementParser, class AuxPolicy>
131 class VectorParser_Container
135 ///////////////////////////////////////////////////////////////////////////
138 typedef VectorParser<ElementParser,AuxPolicy> parser_type;
139 typedef PacketParserBase::data_iterator data_iterator;
140 typedef PacketParserBase::size_type size_type;
141 typedef PacketParserBase::difference_type difference_type;
142 typedef ElementParser value_type;
143 typedef detail::ArrayParser_iterator<value_type> iterator;
144 typedef iterator const_iterator;
145 typedef PacketParserBase::state_type state_type;
147 ///////////////////////////////////////////////////////////////////////////
148 ///\name Structors and default members
151 // no default constructor
153 // default destructor
154 // conversion constructors
156 VectorParser_Container(parser_type const & vector);
159 ///////////////////////////////////////////////////////////////////////////
164 size_type size() const;
167 iterator begin() const;
168 iterator end() const;
170 value_type operator[](difference_type i) const;
171 value_type front() const;
172 value_type back() const;
178 iterator shift(iterator pos, size_type n=1);
179 template <class Value>
180 void insert(iterator pos, Value const & t);
181 template <class Value>
182 void insert(iterator pos, size_type n, Value const & t);
184 template <class ForwardIterator>
185 void insert(iterator pos, ForwardIterator f, ForwardIterator l,
186 typename boost::disable_if< boost::is_convertible<ForwardIterator,size_type> >::type * = 0);
188 template <class ForwardIterator>
189 void insert(iterator pos, ForwardIterator f, ForwardIterator l);
192 void erase(iterator pos, size_type n=1);
193 void erase(iterator f, iterator l);
196 template <class Value> void push_back (Value value, size_type n=1);
197 void push_back_space (size_type n=1);
198 template <class Value> void push_front (Value value, size_type n=1);
199 void push_front_space (size_type n=1);
200 void resize (size_type n);
201 template <class Value> void resize (size_type n, Value value);
205 ///\name Parser interface
208 parser_type parser() const;
209 data_iterator i() const;
210 state_type state() const;
211 PacketData & data() const;
213 size_type bytes() const;
221 void setSize(size_type value);
227 /** \brief Define VectorParser field
229 This macro is a special helper to define a senf::VectorParser type field, a vector of
230 elements of type \a elt_type (a parser) which size is given by the \a size field.
233 // The size field should be declared private (size is accessible via the vector)
234 SENF_PARSER_PRIVATE_FIELD ( vec_size_, senf::UInt16Parser );
235 // Define the vector, here it has 32bit unsigned integer elements
236 SENF_PARSER_VECTOR ( vec, vec_size_, senf::UInt32Parser );
239 \warning Realize, that the \a size field is controlled by the vector parser. This field
240 should therefore be declared either read-only or private and must be changed only via
243 Further additional tags are supported which modify the way, the \a size field is
246 <table class="senf fixedcolumn">
247 <tr><td>\c bytes(\a size)</td><td>\a size gives the size of the vector in bytes not the
248 number of contained elements</td></tr>
250 <tr><td>\c transform(\a transform, \a size)</td><td>The \a transform is applied to the \a
251 size value, the value is not used directly</td>
254 The optional \a transform is a class with the following layout
259 typedef ... value_type;
260 static value_type get(other_type v);
261 static other_type set(value_type v);
263 \endcode \c other_type is the \a size ::\c value_type where as the \c value_type typedef is
264 the arbitrary return type of the transform.
266 The tags are applied to the \a size parameter:
268 SENF_PARSER_VECTOR ( vec, transform(MyTransform, vec_size_), senf::UInt32Parser );
271 \param[in] name field name
272 \param[in] size name of field giving the vector size
273 \param[in] elt_type vector element type
276 \ingroup packetparsermacros
278 # define SENF_PARSER_VECTOR(name, size, elt_type) \
279 SENF_PARSER_VECTOR_I(public, name, size, elt_type)
281 /** \brief Define private VectorParser field
283 \see \ref SENF_PARSER_VECTOR()
286 \ingroup packetparsermacros
288 # define SENF_PARSER_PRIVATE_VECTOR(name, size, elt_type) \
289 SENF_PARSER_VECTOR_I(private, name, size, elt_type)
292 ///////////////////////////////hh.e////////////////////////////////////////
294 #if !defined(HH_SENF_Packets_Packets__decls_) && !defined(HH_SENF_Packets_VectorParser_i_)
295 #define HH_SENF_Packets_VectorParser_i_
296 //#include "VectorParser.cci"
297 #include "VectorParser.ct"
298 #include "VectorParser.cti"
305 // c-file-style: "senf"
306 // indent-tabs-mode: nil
307 // ispell-local-dictionary: "american"
308 // compile-command: "scons -u test"
309 // comment-column: 40