# Ticket #302: 302-628519c21586.patch

File 302-628519c21586.patch, 23.0 KB (added by Peter Kovacs, 10 years ago)
• ## lemon/maps.h

# HG changeset patch
# User Peter Kovacs <kpeter@inf.elte.hu>
# Date 1249234315 -7200
# Node ID 628519c21586cd33d77c0fd4483771d06067acc8
# Parent  b52189c479fb3b19a4757d246b140d7220250b90
Rearrange the doc of graph maps (#302)

diff --git a/lemon/maps.h b/lemon/maps.h
 a InverseMap inverse() const { return InverseMap(*_graph);} }; /// \brief Returns an \c IdMap class. /// /// This function just returns an \c IdMap class. /// \relates IdMap template inline IdMap idMap(const GR& graph) { return IdMap(graph); } /// \brief Provides continuous and unique id for the /// items of a graph. /// /// RangeIdMap provides a unique and continuous /// id for each item of a given type (\c Node, \c Arc or /// \c Edge) in a graph. This id is ///  - \b unique: different items get different ids, ///  - \b continuous: the range of the ids is the set of integers ///    between 0 and \c n-1, where \c n is the number of the items of ///    this type (\c Node, \c Arc or \c Edge). ///  - So, the ids can change when deleting an item of the same type. /// /// Thus this id is not (necessarily) the same as what can get using /// the \c id() function of the graph or \ref IdMap. /// This map can be inverted with its member class \c InverseMap, /// or with the \c operator()() member. /// /// \tparam GR The graph type. /// \tparam K The key type of the map (\c GR::Node, \c GR::Arc or /// \c GR::Edge). /// /// \see IdMap template class RangeIdMap : protected ItemSetTraits::template Map::Type { typedef typename ItemSetTraits::template Map::Type Map; public: /// The graph type of RangeIdMap. typedef GR Graph; typedef GR Digraph; /// The key type of RangeIdMap (\c Node, \c Arc or \c Edge). typedef K Item; /// The key type of RangeIdMap (\c Node, \c Arc or \c Edge). typedef K Key; /// The value type of RangeIdMap. typedef int Value; /// \brief Constructor. /// /// Constructor. explicit RangeIdMap(const Graph& gr) : Map(gr) { Item it; const typename Map::Notifier* nf = Map::notifier(); for (nf->first(it); it != INVALID; nf->next(it)) { Map::set(it, _inv_map.size()); _inv_map.push_back(it); } } protected: /// \brief Adds a new key to the map. /// /// Add a new key to the map. It is called by the /// \c AlterationNotifier. virtual void add(const Item& item) { Map::add(item); Map::set(item, _inv_map.size()); _inv_map.push_back(item); } /// \brief Add more new keys to the map. /// /// Add more new keys to the map. It is called by the /// \c AlterationNotifier. virtual void add(const std::vector& items) { Map::add(items); for (int i = 0; i < int(items.size()); ++i) { Map::set(items[i], _inv_map.size()); _inv_map.push_back(items[i]); } } /// \brief Erase the key from the map. /// /// Erase the key from the map. It is called by the /// \c AlterationNotifier. virtual void erase(const Item& item) { Map::set(_inv_map.back(), Map::operator[](item)); _inv_map[Map::operator[](item)] = _inv_map.back(); _inv_map.pop_back(); Map::erase(item); } /// \brief Erase more keys from the map. /// /// Erase more keys from the map. It is called by the /// \c AlterationNotifier. virtual void erase(const std::vector& items) { for (int i = 0; i < int(items.size()); ++i) { Map::set(_inv_map.back(), Map::operator[](items[i])); _inv_map[Map::operator[](items[i])] = _inv_map.back(); _inv_map.pop_back(); } Map::erase(items); } /// \brief Build the unique map. /// /// Build the unique map. It is called by the /// \c AlterationNotifier. virtual void build() { Map::build(); Item it; const typename Map::Notifier* nf = Map::notifier(); for (nf->first(it); it != INVALID; nf->next(it)) { Map::set(it, _inv_map.size()); _inv_map.push_back(it); } } /// \brief Clear the keys from the map. /// /// Clear the keys from the map. It is called by the /// \c AlterationNotifier. virtual void clear() { _inv_map.clear(); Map::clear(); } public: /// \brief Returns the maximal value plus one. /// /// Returns the maximal value plus one in the map. unsigned int size() const { return _inv_map.size(); } /// \brief Swaps the position of the two items in the map. /// /// Swaps the position of the two items in the map. void swap(const Item& p, const Item& q) { int pi = Map::operator[](p); int qi = Map::operator[](q); Map::set(p, qi); _inv_map[qi] = p; Map::set(q, pi); _inv_map[pi] = q; } /// \brief Gives back the \e range \e id of the item /// /// Gives back the \e range \e id of the item. int operator[](const Item& item) const { return Map::operator[](item); } /// \brief Gives back the item belonging to a \e range \e id /// /// Gives back the item belonging to the given \e range \e id. Item operator()(int id) const { return _inv_map[id]; } private: typedef std::vector Container; Container _inv_map; public: /// \brief The inverse map type of RangeIdMap. /// /// The inverse map type of RangeIdMap. The subscript operator gives /// back an item by its \e range \e id. /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept. class InverseMap { public: /// \brief Constructor /// /// Constructor of the InverseMap. explicit InverseMap(const RangeIdMap& inverted) : _inverted(inverted) {} /// The value type of the InverseMap. typedef typename RangeIdMap::Key Value; /// The key type of the InverseMap. typedef typename RangeIdMap::Value Key; /// \brief Subscript operator. /// /// Subscript operator. It gives back the item /// that the given \e range \e id currently belongs to. Value operator[](const Key& key) const { return _inverted(key); } /// \brief Size of the map. /// /// Returns the size of the map. unsigned int size() const { return _inverted.size(); } private: const RangeIdMap& _inverted; }; /// \brief Gives back the inverse of the map. /// /// Gives back the inverse of the RangeIdMap. const InverseMap inverse() const { return InverseMap(*this); } }; /// \brief Map of the source nodes of arcs in a digraph. /// /// SourceMap provides access for the source node of each arc in a digraph, /// which is returned by the \c source() function of the digraph. /// \tparam GR The digraph type. /// \see TargetMap template class SourceMap { public: /// The key type (the \c Arc type of the digraph). typedef typename GR::Arc Key; /// The value type (the \c Node type of the digraph). typedef typename GR::Node Value; /// \brief Constructor /// /// Constructor. /// \param digraph The digraph that the map belongs to. explicit SourceMap(const GR& digraph) : _graph(digraph) {} /// \brief Returns the source node of the given arc. /// /// Returns the source node of the given arc. Value operator[](const Key& arc) const { return _graph.source(arc); } private: const GR& _graph; }; /// \brief Returns a \c SourceMap class. /// /// This function just returns an \c SourceMap class. /// \relates SourceMap template inline SourceMap sourceMap(const GR& graph) { return SourceMap(graph); } /// \brief Map of the target nodes of arcs in a digraph. /// /// TargetMap provides access for the target node of each arc in a digraph, /// which is returned by the \c target() function of the digraph. /// \tparam GR The digraph type. /// \see SourceMap template class TargetMap { public: /// The key type (the \c Arc type of the digraph). typedef typename GR::Arc Key; /// The value type (the \c Node type of the digraph). typedef typename GR::Node Value; /// \brief Constructor /// /// Constructor. /// \param digraph The digraph that the map belongs to. explicit TargetMap(const GR& digraph) : _graph(digraph) {} /// \brief Returns the target node of the given arc. /// /// Returns the target node of the given arc. Value operator[](const Key& e) const { return _graph.target(e); } private: const GR& _graph; }; /// \brief Returns a \c TargetMap class. /// /// This function just returns a \c TargetMap class. /// \relates TargetMap template inline TargetMap targetMap(const GR& graph) { return TargetMap(graph); } /// \brief Map of the "forward" directed arc view of edges in a graph. /// /// ForwardMap provides access for the "forward" directed arc view of /// each edge in a graph, which is returned by the \c direct() function /// of the graph with \c true parameter. /// \tparam GR The graph type. /// \see BackwardMap template class ForwardMap { public: /// The key type (the \c Edge type of the digraph). typedef typename GR::Edge Key; /// The value type (the \c Arc type of the digraph). typedef typename GR::Arc Value; /// \brief Constructor /// /// Constructor. /// \param graph The graph that the map belongs to. explicit ForwardMap(const GR& graph) : _graph(graph) {} /// \brief Returns the "forward" directed arc view of the given edge. /// /// Returns the "forward" directed arc view of the given edge. Value operator[](const Key& key) const { return _graph.direct(key, true); } private: const GR& _graph; }; /// \brief Returns a \c ForwardMap class. /// /// This function just returns an \c ForwardMap class. /// \relates ForwardMap template inline ForwardMap forwardMap(const GR& graph) { return ForwardMap(graph); } /// \brief Map of the "backward" directed arc view of edges in a graph. /// /// BackwardMap provides access for the "backward" directed arc view of /// each edge in a graph, which is returned by the \c direct() function /// of the graph with \c false parameter. /// \tparam GR The graph type. /// \see ForwardMap template class BackwardMap { public: /// The key type (the \c Edge type of the digraph). typedef typename GR::Edge Key; /// The value type (the \c Arc type of the digraph). typedef typename GR::Arc Value; /// \brief Constructor /// /// Constructor. /// \param graph The graph that the map belongs to. explicit BackwardMap(const GR& graph) : _graph(graph) {} /// \brief Returns the "backward" directed arc view of the given edge. /// /// Returns the "backward" directed arc view of the given edge. Value operator[](const Key& key) const { return _graph.direct(key, false); } private: const GR& _graph; }; /// \brief Returns a \c BackwardMap class /// This function just returns a \c BackwardMap class. /// \relates BackwardMap template inline BackwardMap backwardMap(const GR& graph) { return BackwardMap(graph); } /// \brief General cross reference graph map type. }; /// \brief Provides continuous and unique id for the /// items of a graph. /// /// RangeIdMap provides a unique and continuous /// id for each item of a given type (\c Node, \c Arc or /// \c Edge) in a graph. This id is ///  - \b unique: different items get different ids, ///  - \b continuous: the range of the ids is the set of integers ///    between 0 and \c n-1, where \c n is the number of the items of ///    this type (\c Node, \c Arc or \c Edge). ///  - So, the ids can change when deleting an item of the same type. /// /// Thus this id is not (necessarily) the same as what can get using /// the \c id() function of the graph or \ref IdMap. /// This map can be inverted with its member class \c InverseMap, /// or with the \c operator()() member. /// /// \tparam GR The graph type. /// \tparam K The key type of the map (\c GR::Node, \c GR::Arc or /// \c GR::Edge). /// /// \see IdMap template class RangeIdMap : protected ItemSetTraits::template Map::Type { typedef typename ItemSetTraits::template Map::Type Map; public: /// The graph type of RangeIdMap. typedef GR Graph; typedef GR Digraph; /// The key type of RangeIdMap (\c Node, \c Arc or \c Edge). typedef K Item; /// The key type of RangeIdMap (\c Node, \c Arc or \c Edge). typedef K Key; /// The value type of RangeIdMap. typedef int Value; /// \brief Constructor. /// /// Constructor. explicit RangeIdMap(const Graph& gr) : Map(gr) { Item it; const typename Map::Notifier* nf = Map::notifier(); for (nf->first(it); it != INVALID; nf->next(it)) { Map::set(it, _inv_map.size()); _inv_map.push_back(it); } } protected: /// \brief Adds a new key to the map. /// /// Add a new key to the map. It is called by the /// \c AlterationNotifier. virtual void add(const Item& item) { Map::add(item); Map::set(item, _inv_map.size()); _inv_map.push_back(item); } /// \brief Add more new keys to the map. /// /// Add more new keys to the map. It is called by the /// \c AlterationNotifier. virtual void add(const std::vector& items) { Map::add(items); for (int i = 0; i < int(items.size()); ++i) { Map::set(items[i], _inv_map.size()); _inv_map.push_back(items[i]); } } /// \brief Erase the key from the map. /// /// Erase the key from the map. It is called by the /// \c AlterationNotifier. virtual void erase(const Item& item) { Map::set(_inv_map.back(), Map::operator[](item)); _inv_map[Map::operator[](item)] = _inv_map.back(); _inv_map.pop_back(); Map::erase(item); } /// \brief Erase more keys from the map. /// /// Erase more keys from the map. It is called by the /// \c AlterationNotifier. virtual void erase(const std::vector& items) { for (int i = 0; i < int(items.size()); ++i) { Map::set(_inv_map.back(), Map::operator[](items[i])); _inv_map[Map::operator[](items[i])] = _inv_map.back(); _inv_map.pop_back(); } Map::erase(items); } /// \brief Build the unique map. /// /// Build the unique map. It is called by the /// \c AlterationNotifier. virtual void build() { Map::build(); Item it; const typename Map::Notifier* nf = Map::notifier(); for (nf->first(it); it != INVALID; nf->next(it)) { Map::set(it, _inv_map.size()); _inv_map.push_back(it); } } /// \brief Clear the keys from the map. /// /// Clear the keys from the map. It is called by the /// \c AlterationNotifier. virtual void clear() { _inv_map.clear(); Map::clear(); } public: /// \brief Returns the maximal value plus one. /// /// Returns the maximal value plus one in the map. unsigned int size() const { return _inv_map.size(); } /// \brief Swaps the position of the two items in the map. /// /// Swaps the position of the two items in the map. void swap(const Item& p, const Item& q) { int pi = Map::operator[](p); int qi = Map::operator[](q); Map::set(p, qi); _inv_map[qi] = p; Map::set(q, pi); _inv_map[pi] = q; } /// \brief Gives back the \e range \e id of the item /// /// Gives back the \e range \e id of the item. int operator[](const Item& item) const { return Map::operator[](item); } /// \brief Gives back the item belonging to a \e range \e id /// /// Gives back the item belonging to the given \e range \e id. Item operator()(int id) const { return _inv_map[id]; } private: typedef std::vector Container; Container _inv_map; public: /// \brief The inverse map type of RangeIdMap. /// /// The inverse map type of RangeIdMap. The subscript operator gives /// back an item by its \e range \e id. /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept. class InverseMap { public: /// \brief Constructor /// /// Constructor of the InverseMap. explicit InverseMap(const RangeIdMap& inverted) : _inverted(inverted) {} /// The value type of the InverseMap. typedef typename RangeIdMap::Key Value; /// The key type of the InverseMap. typedef typename RangeIdMap::Value Key; /// \brief Subscript operator. /// /// Subscript operator. It gives back the item /// that the given \e range \e id currently belongs to. Value operator[](const Key& key) const { return _inverted(key); } /// \brief Size of the map. /// /// Returns the size of the map. unsigned int size() const { return _inverted.size(); } private: const RangeIdMap& _inverted; }; /// \brief Gives back the inverse of the map. /// /// Gives back the inverse of the RangeIdMap. const InverseMap inverse() const { return InverseMap(*this); } }; /// \brief Dynamic iterable \c bool map. /// /// This class provides a special graph map type which can store a std::map _first; }; /// \brief Map of the source nodes of arcs in a digraph. /// /// SourceMap provides access for the source node of each arc in a digraph, /// which is returned by the \c source() function of the digraph. /// \tparam GR The digraph type. /// \see TargetMap template class SourceMap { public: ///\e typedef typename GR::Arc Key; ///\e typedef typename GR::Node Value; /// \brief Constructor /// /// Constructor. /// \param digraph The digraph that the map belongs to. explicit SourceMap(const GR& digraph) : _graph(digraph) {} /// \brief Returns the source node of the given arc. /// /// Returns the source node of the given arc. Value operator[](const Key& arc) const { return _graph.source(arc); } private: const GR& _graph; }; /// \brief Returns a \c SourceMap class. /// /// This function just returns an \c SourceMap class. /// \relates SourceMap template inline SourceMap sourceMap(const GR& graph) { return SourceMap(graph); } /// \brief Map of the target nodes of arcs in a digraph. /// /// TargetMap provides access for the target node of each arc in a digraph, /// which is returned by the \c target() function of the digraph. /// \tparam GR The digraph type. /// \see SourceMap template class TargetMap { public: ///\e typedef typename GR::Arc Key; ///\e typedef typename GR::Node Value; /// \brief Constructor /// /// Constructor. /// \param digraph The digraph that the map belongs to. explicit TargetMap(const GR& digraph) : _graph(digraph) {} /// \brief Returns the target node of the given arc. /// /// Returns the target node of the given arc. Value operator[](const Key& e) const { return _graph.target(e); } private: const GR& _graph; }; /// \brief Returns a \c TargetMap class. /// /// This function just returns a \c TargetMap class. /// \relates TargetMap template inline TargetMap targetMap(const GR& graph) { return TargetMap(graph); } /// \brief Map of the "forward" directed arc view of edges in a graph. /// /// ForwardMap provides access for the "forward" directed arc view of /// each edge in a graph, which is returned by the \c direct() function /// of the graph with \c true parameter. /// \tparam GR The graph type. /// \see BackwardMap template class ForwardMap { public: typedef typename GR::Arc Value; typedef typename GR::Edge Key; /// \brief Constructor /// /// Constructor. /// \param graph The graph that the map belongs to. explicit ForwardMap(const GR& graph) : _graph(graph) {} /// \brief Returns the "forward" directed arc view of the given edge. /// /// Returns the "forward" directed arc view of the given edge. Value operator[](const Key& key) const { return _graph.direct(key, true); } private: const GR& _graph; }; /// \brief Returns a \c ForwardMap class. /// /// This function just returns an \c ForwardMap class. /// \relates ForwardMap template inline ForwardMap forwardMap(const GR& graph) { return ForwardMap(graph); } /// \brief Map of the "backward" directed arc view of edges in a graph. /// /// BackwardMap provides access for the "backward" directed arc view of /// each edge in a graph, which is returned by the \c direct() function /// of the graph with \c false parameter. /// \tparam GR The graph type. /// \see ForwardMap template class BackwardMap { public: typedef typename GR::Arc Value; typedef typename GR::Edge Key; /// \brief Constructor /// /// Constructor. /// \param graph The graph that the map belongs to. explicit BackwardMap(const GR& graph) : _graph(graph) {} /// \brief Returns the "backward" directed arc view of the given edge. /// /// Returns the "backward" directed arc view of the given edge. Value operator[](const Key& key) const { return _graph.direct(key, false); } private: const GR& _graph; }; /// \brief Returns a \c BackwardMap class /// This function just returns a \c BackwardMap class. /// \relates BackwardMap template inline BackwardMap backwardMap(const GR& graph) { return BackwardMap(graph); } /// \brief Map of the in-degrees of nodes in a digraph. /// /// This map returns the in-degree of a node. Once it is constructed,