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 ListParser< ExampleListPolicy > parser_type;
40 typedef ListParser_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 (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;
55 // Members needed in the container policy for iteration
56 struct iterator_data {};
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;
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.
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.
77 struct ExampleListPolicy
79 typedef PacketParserBase::data_iterator iterator;
80 typedef PacketParserBase::state_type state_type;
81 typedef PacketParserBase::size_type size_type;
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
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
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
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 ... */
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. */
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
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
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. */
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.
132 \warning if the list is empty, the returned iterator
133 \e must be the same as the one returned by setEnd. */
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
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. */
149 iterator next(iterator i, state_type s); ///< Advance to next element
150 /**< given an iterator to an element, go to the next
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. */
160 void update(iterator i, state_type s); ///< Called before every container access
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"