senf/Packets/ArrayParser.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   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.
  12 //
  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.
  17 //
  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.
  22
  23 /** \file
  24     \brief ArrayParser public header */
  25
  26 #ifndef HH_SENF_Packets_ArrayParser_
  27 #define HH_SENF_Packets_ArrayParser_ 1
  28
  29 /** \defgroup parsecollection Collection parsers
  30
  31     Collection parsers are parsers which build collections from other parsers. Examples are a vector
  32     of 16bit unsigned integers or a list of lists of 32bit numbers and so on.
  33
  34     Collection parsers provide a (reduced) STL sequence like interface. It depends on the type of
  35     collection parser, what kind of sequence is modelled (e.g. random access sequence, forward
  36     sequence etc). Most collections will also provide a kind of container wrapper to allow extensive
  37     manipulations of the collection contents. A container wrapper is initialized with the collection
  38     parser and then provides a more complete sequence interface. Additionally, the collection
  39     wrapper has a longer lifetime than an ordinary parser: While a parser will be invalidated
  40     whenever the collection is changed, the container wrapper will stay valid as long as the
  41     collection is changed through the wrapper (directly or indirectly, where indirectly means that a
  42     sub-field or sub-collection of the collection is changed). Some collections may provide even
  43     more lifetime guarantees but this guarantee should be met by all collection wrappers.
  44
  45     \warning Parser lifetime has to be tightly checked when working with collection parsers since
  46     \e every change of the collections size will invalidate \e all parsers and iterators referencing
  47     the \e complete packet chain. Collection wrappers do \e not invalidate if the change is \e after
  48     the collection.
  49
  50     \ingroup packetparser
  51 */
  52
  53 // Custom includes
  54 #include "PacketParser.hh"
  55
  56 //#include "ArrayParser.mpp"
  57 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  58
  59 namespace senf {
  60
  61     namespace detail { template <class> class ArrayParser_iterator; }
  62
  63     /** \brief Fixed size collection of fixed size elements
  64
  65         ArrayParser will parse a sequence of <em>fixed size</em> parsers. The number of array
  66         elements is given by the \e elements template parameter and is fixed at compile time.
  67
  68         Each element will be parsed by \a ElementParser, which can be any <em>fixed size</em>
  69         parser. The array models an STL random-access sequence with the restriction that elements
  70         cannot be added or removed since the size is fixed.
  71
  72         \ingroup parsecollection
  73      */
  74     template <unsigned elements, class ElementParser>
  75     struct ArrayParser : public PacketParserBase
  76     {
  77         ArrayParser(data_iterator i, state_type s);
  78
  79         static size_type const fixed_bytes = elements*ElementParser::fixed_bytes;
  80
  81         void init() const;
  82
  83         //-////////////////////////////////////////////////////////////////////////
  84         // Container interface
  85
  86         typedef ElementParser value_type;
  87         typedef detail::ArrayParser_iterator<value_type> iterator;
  88         typedef iterator const_iterator;
  89
  90         static size_type size();
  91
  92         iterator begin() const;
  93         iterator end() const;
  94
  95         value_type operator[](difference_type i) const;
  96     };
  97
  98     /** \brief Define array field
  99
 100         This macro is a special helper to define a senf::ArrayParser type field, a fixed size
 101         collection of fixed size elements.
 102
 103         \param[in] name field name
 104         \param[in] elt_type array element type
 105         \param[in] size constant number of elements
 106         \hideinitializer
 107         \ingroup packetparsermacros
 108      */
 109 #   define SENF_PARSER_ARRAY(name, elt_type, size)                                                \
 110         typedef senf::ArrayParser<size,elt_type> BOOST_PP_CAT(name, _array_t);                    \
 111         SENF_PARSER_FIELD( name, BOOST_PP_CAT(name, _array_t) )
 112
 113 }
 114
 115 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 116 #endif
 117 #if !defined(HH_SENF_Packets_Packets__decls_) && !defined(HH_SENF_Packets_ArrayParser_i_)
 118 #define HH_SENF_Packets_ArrayParser_i_
 119 //#include "ArrayParser.cci"
 120 #include "ArrayParser.ct"
 121 #include "ArrayParser.cti"
 122 #endif
 123
 124 \f
 125 // Local Variables:
 126 // mode: c++
 127 // fill-column: 100
 128 // c-file-style: "senf"
 129 // indent-tabs-mode: nil
 130 // ispell-local-dictionary: "american"
 131 // compile-command: "scons -u test"
 132 // comment-column: 40
 133 // End: