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