// $Id$ // // Copyright (C) 2007 // Fraunhofer Institute for Open Communication Systems (FOKUS) // // The contents of this file are subject to the Fraunhofer FOKUS Public License // Version 1.0 (the "License"); you may not use this file except in compliance // with the License. You may obtain a copy of the License at // http://senf.berlios.de/license.html // // The Fraunhofer FOKUS Public License Version 1.0 is based on, // but modifies the Mozilla Public License Version 1.1. // See the full license text for the amendments. // // Software distributed under the License is distributed on an "AS IS" basis, // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License // for the specific language governing rights and limitations under the License. // // The Original Code is Fraunhofer FOKUS code. // // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V. // (registered association), Hansastraße 27 c, 80686 Munich, Germany. // // Contributor(s): // Stefan Bund namespace senf { /** \brief Example of a list policy. ONLY FOR EXPOSITION. This class shows the interface which must be implemented by a list policy. It is not a list policy only a declaration of the interface: \code struct ExampleListPolicy { // optional typedefs used to simplify all other declarations typedef PacketParserBase::data_iterator data_iterator; typedef PacketParserBase::state_type state_type; typedef PacketParserBase::size_type size_type; // mandatory typedefs in the parser and container policy typedef ElementParser element_type; typedef ListParser< ExampleListPolicy > parser_type; typedef ListParser_Container< ExampleListPolicy > container_type; // mandatory constant in parser and container policy static const size_type init_bytes = 0; // Members needed in the parser and the container policy size_type bytes (data_iterator i, state_type s) const; size_type size (data_iterator i, state_type s) const; void init (data_iterator i, state_type s) const; // Members needed only in the container policy void erase (container_type & c, data_iterator p) const; void insert (container_type & c, data_iterator p) const; void update (container_type const & c, data_iterator p) const; // Members needed in the container policy for iteration struct iterator_data {}; data_iterator setBegin (container_type const & c, iterator_data & d) const; data_iterator setEnd (container_type const & c, iterator_data & d) const; void setFromPosition (container_type const & c, iterator_data & d, iterator p) const; data_iterator next (container_type const & c, iterator_data & d) const; data_iterator raw (container_type const & c, iterator_data const & d) const; }; \endcode The list policy must be either default constructible or copy constructible. The policy may contain arbitrary additional data members. However, their number and size should be kept at an absolute minimum, since they will increase the size of the list parser. If necessary, you may use a different policy in the container_type. The ListPolicy must define the elements bytes(), size() and init(), the container policy needs all these and additionally needs erase() and insert(). The container policy will also need the element_type, parser_type and container_type typedefs. \see \ref ListParser */ struct ExampleListPolicy { typedef PacketParserBase::data_iterator iterator; typedef PacketParserBase::state_type state_type; typedef PacketParserBase::size_type size_type; typedef unspecified element_type; ///< Type of list elements /**< This is the parser used to parse the list elements. */ typedef unspecified parser_type; ///< List parser type /**< parser_type is the list parser used to parse a list of this type, e.g. senf::ListParser. */ typedef unspecified container_type; ///< Type of container wrapper /**< This is the container wrapper of the list, e.g. ListParser_Container. The container may however use a \e different policy, as long as that policy is constructible from the parser policy. */ static const size_type init_bytes = 0; ///< Size of a new list of this type /**< Initial size which needs to be allocated to this type of list */ size_type bytes(iterator i, state_type s) const; ///< Size of list in bytes /**< Return the complete size of the list in bytes. Depending on the type of list, this call may need to completely traverse the list ... */ size_type size(iterator i, state_type s) const; ///< Number of elements in list /**< Return the number of elements in the list. This operation may be quite inefficient for some lists (the list must be traversed to find that number. */ void init(iterator i, state_type s) const; ///< Initialize new list /**< Called after init_size bytes have been allocated to initialize the list. After init() is called, the list is traversed to initialize any members (probably none) */ void erase(iterator i, state_type s, iterator p) const; ///< Erase element from list /**< Delete the list element at p from the List (i,s). When this operation is called, the element is still part of the list. This call must update the meta-data as needed. The data will be removed after this call returns. */ void insert(iterator i, state_type s, iterator p) const; ///< Insert element into list /**< This is called after an element has been inserted at p into the List (i,s) to update the meta-data. */ iterator setBegin(iterator i, state_type s); ///< Initialize iterator to begin() /**< Initialize the policy from the given List (i,s). Set the iterator to the beginning iterator. Return data_iterator to the first element. \warning if the list is empty, the returned iterator \e must be the same as the one returned by setEnd. */ iterator setEnd(iterator i, state_type s); ///< Initialize iterator to end() /**< Initialize the policy from the given List (i,s). Set the iterator to the end iterator. Return data_iterator used to mark the end of the range. This may be a special sentinel value (e.g. data().end()) if needed. */ void setFromPosition(iterator i, state_type s, iterator p); ///< Initialize iterator from the given raw position /**< Set the iterator to the Element at raw position p. This operation can potentially be very inefficient if the list needs to be traversed from the beginning until the iterator is found. */ iterator next(iterator i, state_type s); ///< Advance to next element /**< given an iterator to an element, go to the next element. */ iterator raw(iterator i, state_type s); ///< Return raw position of element /**< Given the iterator state (i,s), return the raw iterator to the datum. This will be i in almost all cases EXCEPT if a special sentinel value is used as end() value. In this case, this member must return the real position after the last element. */ void update(iterator i, state_type s); ///< Called before every container access struct iterator_data {}; }; } // Local Variables: // mode: c++ // fill-column: 100 // comment-column: 40 // c-file-style: "senf" // indent-tabs-mode: nil // ispell-local-dictionary: "american" // compile-command: "scons -u test" // mode: flyspell // mode: auto-fill // End: