senf/Packets/ListParser.dox

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