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