senf/Packets/ListParser.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   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 //
  24 // Contributor(s):
  25 //   Stefan Bund <g0dil@berlios.de>
  26
  27
  28 namespace senf {
  29
  30     /** \brief Example of a list policy. ONLY FOR EXPOSITION.
  31
  32         This class shows the interface which must be implemented by a list policy. It is not a list
  33         policy only a declaration of the interface:
  34         \code
  35         struct ExampleListPolicy
  36         {
  37             // optional typedefs used to simplify all other declarations
  38             typedef PacketParserBase::data_iterator data_iterator;
  39             typedef PacketParserBase::state_type state_type;
  40             typedef PacketParserBase::size_type size_type;
  41
  42             // mandatory typedefs in the parser and container policy
  43             typedef ElementParser element_type;
  44             typedef ListParser< ExampleListPolicy > parser_type;
  45             typedef ListParser_Container< ExampleListPolicy > container_type;
  46
  47             // mandatory constant in parser and container policy
  48             static const size_type init_bytes = 0;
  49
  50             // Members needed in the parser and the container policy
  51             size_type bytes  (data_iterator i, state_type s) const;
  52             size_type size   (data_iterator i, state_type s) const;
  53             void      init   (data_iterator i, state_type s) const;
  54
  55             // Members needed only in the container policy
  56             void      erase  (container_type & c, data_iterator p) const;
  57             void      insert (container_type & c, data_iterator p) const;
  58             void      update (container_type const & c, data_iterator p) const;
  59
  60             // Members needed in the container policy for iteration
  61             struct iterator_data {};
  62
  63             data_iterator setBegin        (container_type const & c, iterator_data & d) const;
  64             data_iterator setEnd          (container_type const & c, iterator_data & d) const;
  65             void          setFromPosition (container_type const & c, iterator_data & d, iterator p) const;
  66             data_iterator next            (container_type const & c, iterator_data & d) const;
  67             data_iterator raw             (container_type const & c, iterator_data const & d) const;
  68         };
  69         \endcode
  70
  71         The list policy must be either default constructible or copy constructible. The policy may
  72         contain arbitrary additional data members. However, their number and size should be kept at
  73         an absolute minimum, since they will increase the size of the list parser.
  74
  75         If necessary, you may use a different policy in the container_type. The ListPolicy must
  76         define the elements bytes(), size() and init(), the container policy needs all these and
  77         additionally needs erase() and insert(). The container policy will also need the
  78         element_type, parser_type and container_type typedefs.
  79
  80         \see \ref ListParser
  81      */
  82     struct ExampleListPolicy
  83     {
  84         typedef PacketParserBase::data_iterator iterator;
  85         typedef PacketParserBase::state_type state_type;
  86         typedef PacketParserBase::size_type size_type;
  87
  88         typedef unspecified element_type; ///< Type of list elements
  89                                         /**< This is the parser used to parse the list elements. */
  90         typedef unspecified parser_type; ///< List parser type
  91                                         /**< parser_type is the list parser used to parse a list of
  92                                              this type,
  93                                              e.g. <tt>senf::ListParser<ExampleListPolicy></tt>. */
  94         typedef unspecified container_type; ///< Type of container wrapper
  95                                         /**< This is the container wrapper of the list, e.g.
  96                                              <tt>ListParser_Container<ExampleListPolicy></tt>. The
  97                                              container may however use a \e different policy, as
  98                                              long as that policy is constructible from the parser
  99                                              policy. */
 100
 101         static const size_type init_bytes = 0; ///< Size of a new list of this type
 102                                         /**< Initial size which needs to be allocated to this type
 103                                              of list */
 104
 105         size_type bytes(iterator i, state_type s) const; ///< Size of list in bytes
 106                                         /**< Return the complete size of the list in
 107                                              bytes. Depending on the type of list, this call may
 108                                              need to completely traverse the list ... */
 109
 110         size_type size(iterator i, state_type s) const; ///< Number of elements in list
 111                                         /**< Return the number of elements in the list. This
 112                                              operation may be quite inefficient for some lists (the
 113                                              list must be traversed to find that number. */
 114
 115         void init(iterator i, state_type s) const; ///< Initialize new list
 116                                         /**< Called after init_size bytes have been allocated to
 117                                              initialize the list. After init() is called, the list
 118                                              is traversed to initialize any members (probably
 119                                              none) */
 120
 121         void erase(iterator i, state_type s, iterator p) const; ///< Erase element from list
 122                                         /**< Delete the list element at p from the List (i,s). When
 123                                              this operation is called, the element is still part of
 124                                              the list. This call must update the meta-data as
 125                                              needed. The data will be removed after this call
 126                                              returns. */
 127
 128         void insert(iterator i, state_type s, iterator p) const; ///< Insert element into list
 129                                         /**< This is called after an element has been inserted at p
 130                                              into the List (i,s) to update the meta-data. */
 131
 132         iterator setBegin(iterator i, state_type s); ///< Initialize iterator to begin()
 133                                         /**< Initialize the policy from the given List (i,s). Set
 134                                              the iterator to the beginning iterator. Return
 135                                              data_iterator to the first element.
 136
 137                                              \warning if the list is empty, the returned iterator
 138                                              \e must be the same as the one returned by setEnd. */
 139
 140         iterator setEnd(iterator i, state_type s); ///< Initialize iterator to end()
 141                                         /**< Initialize the policy from the given List (i,s). Set
 142                                              the iterator to the end iterator. Return data_iterator
 143                                              used to mark the end of the range. This may be a
 144                                              special sentinel value (e.g. data().end()) if
 145                                              needed. */
 146
 147         void setFromPosition(iterator i, state_type s, iterator p);
 148                                         ///< Initialize iterator from the given raw position
 149                                         /**< Set the iterator to the Element at raw position p. This
 150                                              operation can potentially be very inefficient if the
 151                                              list needs to be traversed from the beginning until the
 152                                              iterator is found. */
 153
 154         iterator next(iterator i, state_type s); ///< Advance to next element
 155                                         /**< given an iterator to an element, go to the next
 156                                              element. */
 157
 158         iterator raw(iterator i, state_type s); ///< Return raw position of element
 159                                         /**< Given the iterator state (i,s), return the raw iterator
 160                                              to the datum. This will be i in almost all cases EXCEPT
 161                                              if a special sentinel value is used as end() value. In
 162                                              this case, this member must return the real position
 163                                              after the last element. */
 164
 165         void update(iterator i, state_type s); ///< Called before every container access
 166
 167         struct iterator_data
 168         {};
 169     };
 170
 171 }
 172
 173 \f
 174 // Local Variables:
 175 // mode: c++
 176 // fill-column: 100
 177 // comment-column: 40
 178 // c-file-style: "senf"
 179 // indent-tabs-mode: nil
 180 // ispell-local-dictionary: "american"
 181 // compile-command: "scons -u test"
 182 // mode: flyspell
 183 // mode: auto-fill
 184 // End: