senf/Packets/VectorParser.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 // All Rights Reserved.
  24 //
  25 // Contributor(s):
  26 //   Stefan Bund <g0dil@berlios.de>
  27
  28 /** \file
  29     \brief VectorParser public header */
  30
  31 #ifndef HH_SENF_Packets_VectorParser_
  32 #define HH_SENF_Packets_VectorParser_ 1
  33
  34 // Custom includes
  35 #include <boost/type_traits.hpp>
  36 #include "PacketParser.hh"
  37 #include "ArrayParser.hh" // for ArrayParser_iterator
  38 #include "AuxParser.hh" // for the AuxPolicies
  39
  40 //#include "VectorParser.mpp"
  41 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  42
  43 namespace senf {
  44
  45     template <class ElementParser, class AuxPolicy> class VectorParser_Container;
  46
  47     /** \brief Collection of fixed-size elements
  48
  49         A Vector is a collection of fixed-size elements of which the size of the collection can be
  50         determined directly (that is without traversing the collection). This allows very efficient
  51         random access to the elements of the collection.
  52
  53         A vector is a model of an STL random-access sequence. The parser only provides a reduced
  54         interface, the container wrapper however completes this interface.
  55
  56         VectorParser makes use of a policy template argument, \a AuxPolicy, to customize the way the
  57         containers size is obtained. You will normally not instantiate VectorParser directly, you
  58         will use the \ref SENF_PARSER_VECTOR() helper macro.
  59
  60         Some basic vector access methods are defined as parser members. To access the complete list
  61         API however you will need to instantiate a container wrapper for the vector. See \ref
  62         packet_usage_fields_collection.
  63
  64         \see
  65             \ref How to access \ref packet_usage_fields_collection \n
  66             SENF_PARSER_VECTOR() macro used to define vector fields \n
  67             VectorParser_Container vector container wrapper API
  68
  69         \ingroup parsecollection
  70      */
  71     template <class ElementParser, class AuxPolicy>
  72     struct VectorParser
  73         : public PacketParserBase,
  74           private AuxPolicy
  75     {
  76         VectorParser(data_iterator i, state_type s);
  77         VectorParser(AuxPolicy policy, data_iterator i, state_type s);
  78                                         ///< Additional sizer specific constructor
  79                                         /**< This constructor may be used, if the sizer needs
  80                                              additional parameters. */
  81
  82         size_type bytes() const;
  83         void init() const;
  84
  85         static const size_type init_bytes = AuxPolicy::aux_bytes;
  86
  87         //-////////////////////////////////////////////////////////////////////////
  88         // Container interface
  89
  90         typedef ElementParser value_type;
  91         typedef detail::ArrayParser_iterator<value_type> iterator;
  92         typedef iterator const_iterator;
  93         typedef VectorParser_Container<ElementParser,AuxPolicy> container;
  94
  95         size_type size() const;
  96         bool empty() const;
  97
  98         iterator begin() const;
  99         iterator end() const;
 100
 101         value_type operator[](difference_type i) const;
 102         value_type front() const;
 103         value_type back() const;
 104
 105         // Mutators
 106
 107         // The mutators provided here are those which don't take an iterator argument.
 108         // If you need to pass an iterator it is much simpler and cleaner to use the
 109         // 'container' wrapper
 110
 111         template <class Value> void push_back        (Value const & value, size_type n=1) const;
 112         value_type                  push_back_space  (size_type n=1) const;
 113         template <class Value> void push_front       (Value const & value, size_type n=1) const;
 114         value_type                  push_front_space (size_type n=1) const;
 115         void                        resize           (size_type n) const;
 116         template <class Value> void resize           (size_type n, Value value) const;
 117
 118      private:
 119
 120         friend class VectorParser_Container<ElementParser,AuxPolicy>;
 121     };
 122
 123     /** \brief VectorParser container wrapper
 124
 125         This is the container wrapper used for vector parsers. The container wrapper will stay valid
 126         after changing the collection. However the container still depends on the packet and will be
 127         invalidated if the Packet is deallocated or if the packet size is changed from without the
 128         container wrapper (more precisely, it is invalidated if the insertion/deletion happens before
 129         the vector in the packet data).
 130
 131         The vector container wrapper provides a complete STL random-access sequence interface.
 132
 133         \code
 134         SomePacket p (...);
 135         SomePacket::aVectorCollection_t::container c (p->aVectorCollection());
 136         c.insert(c.begin(), ... );
 137         \endcode
 138
 139         \see VectorParser
 140       */
 141     template <class ElementParser, class AuxPolicy>
 142     class VectorParser_Container
 143         : private AuxPolicy::WrapperPolicy
 144     {
 145     public:
 146         //-////////////////////////////////////////////////////////////////////////
 147         // Types
 148
 149         typedef VectorParser<ElementParser,AuxPolicy> parser_type;
 150         typedef PacketParserBase::data_iterator data_iterator;
 151         typedef PacketParserBase::size_type size_type;
 152         typedef PacketParserBase::difference_type difference_type;
 153         typedef ElementParser value_type;
 154         typedef detail::ArrayParser_iterator<value_type> iterator;
 155         typedef iterator const_iterator;
 156         typedef PacketParserBase::state_type state_type;
 157
 158         //-////////////////////////////////////////////////////////////////////////
 159         ///\name Structors and default members
 160         //\{
 161
 162         // no default constructor
 163         // default copy
 164         // default destructor
 165         // conversion constructors
 166
 167         VectorParser_Container(parser_type const & vector);
 168
 169         //\}
 170         //-////////////////////////////////////////////////////////////////////////
 171
 172         ///\name Accessors
 173         //\{
 174
 175         size_type size() const;
 176         bool empty() const;
 177
 178         iterator begin() const;
 179         iterator end() const;
 180
 181         value_type operator[](difference_type i) const;
 182         value_type front() const;
 183         value_type back() const;
 184
 185         //\}
 186         ///\name Mutators
 187         //\{
 188
 189         iterator shift(iterator pos, size_type n=1);
 190         template <class Value>
 191         void insert(iterator pos, Value const & t);
 192         template <class Value>
 193         void insert(iterator pos, size_type n, Value const & t);
 194 #       ifndef DOXYGEN
 195         template <class ForwardIterator>
 196         void insert(iterator pos, ForwardIterator f, ForwardIterator l,
 197                     typename boost::disable_if< boost::is_convertible<ForwardIterator,size_type> >::type * = 0);
 198 #       else
 199         template <class ForwardIterator>
 200         void insert(iterator pos, ForwardIterator f, ForwardIterator l);
 201 #       endif
 202
 203         void erase(iterator pos, size_type n=1);
 204         void erase(iterator f, iterator l);
 205         void clear();
 206
 207         template <class Value> void push_back        (Value const & value, size_type n=1);
 208         value_type                  push_back_space  (size_type n=1);
 209         template <class Value> void push_front       (Value const & value, size_type n=1);
 210         value_type                  push_front_space (size_type n=1);
 211         void                        resize           (size_type n);
 212         template <class Value> void resize           (size_type n, Value value);
 213
 214         //\}
 215
 216         ///\name Parser interface
 217         //\{
 218
 219         parser_type parser() const;
 220         data_iterator i() const;
 221         state_type state() const;
 222         PacketData & data() const;
 223
 224         size_type bytes() const;
 225         void init() const;
 226
 227         //\}
 228
 229     protected:
 230
 231     private:
 232         void setSize(size_type value);
 233
 234         state_type state_;
 235         size_type i_;
 236     };
 237
 238     /** \brief Define VectorParser field
 239
 240         This macro is a special helper to define a senf::VectorParser type field, a vector of
 241         elements of type \a elt_type (a parser) which size is given by the \a size field.
 242
 243         \code
 244         // The size field should be declared private (size is accessible via the vector)
 245         SENF_PARSER_PRIVATE_FIELD ( vec_size_, senf::UInt16Parser );
 246         // Define the vector, here it has 32bit unsigned integer elements
 247         SENF_PARSER_VECTOR        ( vec,       vec_size_, senf::UInt32Parser );
 248         \endcode
 249
 250         \warning Realize, that the \a size field is controlled by the vector parser. This field
 251             should therefore be declared either read-only or private and must be changed only via
 252             the vector parser.
 253
 254         Further additional tags are supported which modify the way, the \a size field is
 255         interpreted:
 256
 257         <table class="senf fixedcolumn">
 258         <tr><td>\c bytes(\a size)</td><td>\a size gives the size of the vector in bytes not the
 259         number of contained elements</td></tr>
 260
 261         <tr><td>\c packetSize()</td><td>Use the size of the packet to get the vector size. The
 262         vector will occupy all space up to the end of the packet.</td></tr>
 263
 264         <tr><td>\c transform(\a transform, \a size)</td><td>The \a transform is applied to the \a
 265         size value, the value is not used directly</td>
 266         </table>
 267
 268         The optional \a transform is a class with the following layout
 269
 270         \code
 271         struct MyTransform
 272         {
 273             typedef ... value_type;
 274             static value_type get(other_type v);
 275             static other_type set(value_type v);
 276         };
 277         \endcode \c other_type is the \a size ::\c value_type where as the \c value_type typedef is
 278         the arbitrary return type of the transform.
 279
 280         The tags are applied to the \a size parameter:
 281         \code
 282         SENF_PARSER_VECTOR ( vec, transform(MyTransform, vec_size_), senf::UInt32Parser );
 283         SENF_PARSER_VECTOR ( vec, packetSize(), senf::UInt32Parser );
 284         \endcode
 285
 286         \param[in] name field name
 287         \param[in] size name of field giving the vector size
 288         \param[in] elt_type vector element type
 289
 290         \see
 291             How to use \ref packet_usage_fields_collection \n
 292             senf::VectorParser the vector parser API for vector field access
 293             senf::VectorParser_Container the vector parser container API for vector field access
 294
 295         \hideinitializer
 296         \ingroup packetparsermacros
 297      */
 298 #   define SENF_PARSER_VECTOR(name, size, elt_type) \
 299         SENF_PARSER_VECTOR_I(public, name, size, elt_type)
 300
 301     /** \brief Define private VectorParser field
 302
 303         \see \ref SENF_PARSER_VECTOR()
 304
 305         \hideinitializer
 306         \ingroup packetparsermacros
 307      */
 308 #   define SENF_PARSER_PRIVATE_VECTOR(name, size, elt_type) \
 309         SENF_PARSER_VECTOR_I(protected, name, size, elt_type)
 310 }
 311
 312 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 313 #endif
 314 #if !defined(HH_SENF_Packets_Packets__decls_) && !defined(HH_SENF_Packets_VectorParser_i_)
 315 #define HH_SENF_Packets_VectorParser_i_
 316 //#include "VectorParser.cci"
 317 #include "VectorParser.ct"
 318 #include "VectorParser.cti"
 319 #endif
 320
 321 \f
 322 // Local Variables:
 323 // mode: c++
 324 // fill-column: 100
 325 // c-file-style: "senf"
 326 // indent-tabs-mode: nil
 327 // ispell-local-dictionary: "american"
 328 // compile-command: "scons -u test"
 329 // comment-column: 40
 330 // End: