lemon-0.x: comparison src/lemon/map

equal deleted inserted replaced

-:7f398e7fc906
+:d6f320795279
 using namespace std;
 namespace lemon {
 /// \addtogroup graphmapfactory
 /// @{
-/**
+/// Map registry for graph maps.
-* Registry class to register edge or node maps into the graph. The
-* registry helps you to implement an observer pattern. If you add
+/**
-* or erase an edge or node you must notify all the maps about the
+* Registry class to register edge or node maps into the graph. The
-* event.
+* registry helps you to implement an observer pattern. If you add
-*/
+* or erase an edge or node you must notify all the maps about the
+* event.
+*
+* \param G The graph type to register maps.
+* \param K The key type of the maps registered into the registry.
+* \param KIt The key iterator type iterates on the keys.
+*
+* \author Balazs Dezso
+*/
 template <typename G, typename K, typename KIt>
 class MapRegistry {
 public:
 typedef G Graph;
 typedef K KeyType;
 typedef KIt KeyIt;
-/**
+/// MapBase is the base class of the dynamic maps.
-* MapBase is the base class of the registered maps.
+/**
+* MapBase is the base class of the dynamic maps.
 * It defines the core modification operations on the maps and
 * implements some helper functions.
 */
 class MapBase {
 public:
 typedef MapRegistry<G, K, KIt> Registry;
 friend class MapRegistry<G, K, KIt>;
+/// Default constructor.
 /**
 * Default constructor for MapBase.
 */
 MapBase() : graph(0), registry(0) {}
-/**
+/// Constructor to register map into a graph registry.
-* Simple constructor to register into a graph registry.
+/**
+* Simple constructor to register dynamic map into a graph registry.
 */
 MapBase(const Graph& g, Registry& r) : graph(&g), registry(0) {
 	r.attach(*this);
 }
+/// Copy constructor.
 /**
 * Copy constructor to register into the registry.
+* If the copiable map is registered into a registry
+* the construated map will be registered to the same registry.
 */
 MapBase(const MapBase& copy) : graph(copy.graph), registry(0) {
 	if (copy.registry) {
 	  copy.registry->attach(*this);
 	}
 }
-/**
+/// Assign operator.
-* Assign operator.
+/**
+* Assign operator. This member detach first the map
+* from the current registry and then it attach to the
+* copiable map's registry if it exists.
 */
 const MapBase& operator=(const MapBase& copy) {
 	if (registry) {
 	  registry->detach(*this);
 	}
 	  copy.registry->attach(*this);
 	}
 	return *this;
 }
+/// Destructor
-/**
-* Destructor.
+/**
+* This member detach the map from the its registry if the
+* registry exists.
 */
 virtual ~MapBase() {
 	if (registry) {
 	  registry->detach(*this);
 	}
 }
+/// The graph of the map.
 /*
 * Returns the graph that the map belongs to.
 */
 const Graph* getGraph() const { return graph; }
 Registry* registry;
 int registry_index;
 protected:
-/**
+/// Helper function to implement constructors in the subclasses.
-	 Helper function to implement constructors in the subclasses.
+/**
+* Helper function to implement constructors in the subclasses.
+* It adds all of the nodes or edges to the map via the
+* \ref MapRegistry::MapBase::add add
+* member function.
 */
 virtual void init() {
 	for (KeyIt it(*graph); it != INVALID; ++it) {
 	  add(it);
 	}
 }
-/**
-	 Helper function to implement the destructor in the subclasses.
+/// Helper function to implement destructors in the subclasses.
+/**
+* Helper function to implement destructors in the subclasses.
+* It erases all of the nodes or edges of the map via the
+* \ref MapRegistry::MapBase::erase erase
+* member function. It can be used by the clear function also.
 */
 virtual void destroy() {
 	for (KeyIt it(*getGraph()); it != INVALID; ++it) {
 	  erase(it);
 	}
 }
+/// The member function to add new node or edge to the map.
 /**
 	  The add member function should be overloaded in the subclasses.
-	  \e Add extends the map with the new node.
+	  \e Add extends the map with the new node or edge.
 */
 virtual void add(const KeyType&) = 0;
+/// The member function to erase a node or edge from the map.
 /**
 	  The erase member function should be overloaded in the subclasses.
-	  \e Erase removes the node from the map.
+	  \e Erase removes the node or edge from the map.
 */
 virtual void erase(const KeyType&) = 0;
 /**
 *  The clear member function should be overloaded in the subclasses.
 *  \e Clear makes empty the data structure.
 */
 virtual void clear() = 0;
-/**
+/// Exception class to throw at unsupported operation.
-	 Exception class to throw at unsupported operation.
+/**
+* Exception class to throw at unsupported operation.
+* If the map does not support erasing or adding new
+* node or key it must be throwed.
 */
 class NotSupportedOperationException {};
 };
 protected:
-/**
-* The container type of the maps.
-*/
 typedef std::vector<MapBase*> Container;
-/**
-* The container of the registered maps.
-*/
 Container container;
 public:
-/**
+/// Default constructor.
-* Default Constructor of the MapRegistry. It creates an empty registry.
+/**
+* Default constructor of the \e MapRegistry.
+* It creates an empty registry.
 */
 MapRegistry() {}
-/**
+/// Copy Constructor of the MapRegistry.
-* Copy Constructor of the MapRegistry. The new registry does not steal
-* the maps from the right value. The new registry will be an empty.
+/**
+* Copy constructor of the \e MapRegistry.
+* The new registry does not steal
+* the maps from the copiable registry.
+* The new registry will be empty.
 */
 MapRegistry(const MapRegistry&) {}
-/**
+/// Assign operator.
-* Assign operator. The left value does not steal the maps
-* from the right value. The left value will be an empty registry.
+/**
+* Assign operator. This registry does not steal the maps
+* from the copiable registry. This registry will be an empty registry.
+* This operator will be called when a graph is assigned.
 */
 MapRegistry& operator=(const MapRegistry&) {
 typename Container::iterator it;
 for (it = container.begin(); it != container.end(); ++it) {
-	(*it)->destroy();
+	(*it)->clear();
 	(*it)->graph = 0;
 	(*it)->registry = 0;
 }
 }
+/// Destructor.
 /**
-* Destructor of the MapRegistry.
+* Destructor of the MapRegistry. It makes empty the attached map
+* first then detachs them.
 */
 ~MapRegistry() {
 typename Container::iterator it;
 for (it = container.begin(); it != container.end(); ++it) {
-	(*it)->destroy();
+	(*it)->clear();
 	(*it)->registry = 0;
 	(*it)->graph = 0;
 }
 }
 public:
-/**
+/// Attachs a map to the \e MapRegistry.
-* Attach a map into thr registry. If the map has been attached
+/**
+* Attachs a map into thr registry. If the map has been attached
 * into an other registry it is detached from that automaticly.
 */
 void attach(MapBase& map) {
 if (map.registry) {
 	map.registry->detach(map);
 }
 container.push_back(&map);
 map.registry = this;
 map.registry_index = container.size()-1;
 }
-/**
+/// Detachs a map from the \e MapRegistry.
-* Detach the map from the registry.
+/**
+* Detachs a map from the \e MapRegistry.
 */
 void detach(MapBase& map) {
 container.back()->registry_index = map.registry_index;
 container[map.registry_index] = container.back();
 container.pop_back();
 map.registry = 0;
 map.graph = 0;
 }
+/// Notify all the registered maps about a Key added.
 /**
 * Notify all the registered maps about a Key added.
-*/
+* This member should be called whenever a node or edge
-void add(KeyType& key) {
+* is added to the graph.
+*/
+void add(const KeyType& key) {
 typename Container::iterator it;
 for (it = container.begin(); it != container.end(); ++it) {
 	(*it)->add(key);
 }
 }
+/// Notify all the registered maps about a Key erased.
 /**
 * Notify all the registered maps about a Key erased.
+* This member should be called whenever a node or edge
+* is erased from the graph.
 */
-void erase(KeyType& key) {
+void erase(const KeyType& key) {
 typename Container::iterator it;
 for (it = container.begin(); it != container.end(); ++it) {
 	(*it)->erase(key);
 }
 }
+/// Notify all the registered maps about all the Keys are erased.
 /**
 * Notify all the registered maps about the map should be cleared.
+* This member should be called whenever all of the nodes or edges
+* are erased from the graph.
 */
 void clear() {
 typename Container::iterator it;
 for (it = container.begin(); it != container.end(); ++it) {
 	(*it)->clear();

changeset 940	50a153b08f07
parent 921	818510fa3d99
child 943	cb0ac054ea92