4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
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
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.
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.
19 // The Original Code is Fraunhofer FOKUS code.
21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
25 // Stefan Bund <g0dil@berlios.de>
30 /** \brief Example of a list policy. ONLY FOR EXPOSITION.
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:
35 struct ExampleListPolicy
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;
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;
47 // mandatory constant in parser and container policy
48 static const size_type init_bytes = 0;
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;
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;
60 // Members needed in the container policy for iteration
61 struct iterator_data {};
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;
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.
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.
82 struct ExampleListPolicy
84 typedef PacketParserBase::data_iterator iterator;
85 typedef PacketParserBase::state_type state_type;
86 typedef PacketParserBase::size_type size_type;
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
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
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
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 ... */
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. */
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
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
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. */
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.
137 \warning if the list is empty, the returned iterator
138 \e must be the same as the one returned by setEnd. */
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
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. */
154 iterator next(iterator i, state_type s); ///< Advance to next element
155 /**< given an iterator to an element, go to the next
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. */
165 void update(iterator i, state_type s); ///< Called before every container access
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"