4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
25 /** \brief Example of a list policy. ONLY FOR EXPOSITION.
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:
30 struct ExampleListPolicy
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;
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;
42 // mandatory constant in parser and container policy
43 static const size_type init_bytes = 0;
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;
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;
54 struct iterator_policy
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;
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.
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.
76 struct ExampleListPolicy
78 typedef PacketParserBase::data_iterator iterator;
79 typedef PacketParserBase::state_type state_type;
80 typedef PacketParserBase::size_type size_type;
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
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
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
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 ... */
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. */
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
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
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. */
126 /** \brief Example of a list iterator policy. ONLY FOR EXPOSITION.
128 \see \ref ExampleListPolicy \n
131 struct iterator_policy
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.
138 \warning if the list is empty, the returned iterator
139 \e must be the same as the one returned by setEnd. */
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
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. */
155 iterator next(iterator i, state_type s); ///< Advance to next element
156 /**< given an iterator to an element, go to the next
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. */
167 /** \brief Example of a list container policy. ONLY FOR EXPOSITION
169 \see \ref ExampleListPolicy \n
172 struct container_policy
174 void init(iterator i, state_type s); ///< Initialize new container
175 void update(iterator i, state_type s); ///< Called before every container access
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"