Tulip  5.2.0
Large graphs analysis and drawing
Graph.h
1 /*
2  *
3  * This file is part of Tulip (http://tulip.labri.fr)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux
7  *
8  * Tulip is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *
13  * Tulip 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.
16  * See the GNU General Public License for more details.
17  *
18  */
19 
20 #ifndef Tulip_SUPERGRAPH_H
21 #define Tulip_SUPERGRAPH_H
22 
23 #include <iostream>
24 #include <set>
25 #include <string>
26 #include <vector>
27 
28 #include <climits>
29 #include <tulip/tulipconf.h>
30 #include <tulip/DataSet.h>
31 #include <tulip/Node.h>
32 #include <tulip/Edge.h>
33 #include <tulip/Observable.h>
34 
35 namespace tlp {
36 
37 class PropertyInterface;
38 class BooleanProperty;
39 class PluginProgress;
40 template <class C>
41 struct Iterator;
42 
43 /**
44  * @enum This Enum describes the possible types of an element of the graph.
45  *
46  * It is used in functions that can return an edge or a node, to distinguish between the two cases.
47  **/
49  /** This element describes a node **/
50  NODE = 0,
51  /** This element describes an edge **/
52  EDGE = 1
53 };
54 
55 /**
56  * @ingroup Graph
57  * @brief Loads a graph from a file (extension can be any of the Tulip supported input graph file
58  *format).
59  *
60  * This function loads a graph serialized in a file trough the available Tulip import plugins.
61  * Since Tulip 4.8, the selection of the import plugin is based on the provided filename extension.
62  * The import will fail if the selected import plugin is not loaded.
63  * The graph file formats that can currently be imported are : TLP (*.tlp, *.tlp.gz, *.tlpz), TLP
64  *Binary (*.tlpb, *.tlpb.gz, *.tlpbz), TLP JSON (*.json),
65  * Gephi (*.gexf), Pajek (*.net, *.paj), GML (*.gml), Graphviz (*.dot) and UCINET (*.txt)
66  *
67  * Before Tulip 4.8 and as a fallback, the function uses the "TLP Import" import plugin
68  * (always loaded as it is linked into the tulip-core library).
69  *
70  * If the import fails (no such file, parse error, ...) nullptr is returned.
71  *
72  * @param filename the file in one of the supported formats to parse.
73  * @return Graph* the imported Graph, nullptr if the import failed.
74  **/
75 TLP_SCOPE Graph *loadGraph(const std::string &filename, tlp::PluginProgress *progress = nullptr);
76 
77 /**
78  * @ingroup Graph
79  * @brief Saves the corresponding graph to a file (extension can be any of the Tulip supported ouput
80  *graph file format)..
81  *
82  * This function serializes the corresponding graph and all its subgraphs (depending on the format)
83  *to a file
84  * through the available Tulip export plugins.
85  * Since Tulip 4.8, the selection of the export plugin is based on the provided filename extension.
86  * The export will fail if the selected export plugin is not loaded.
87  *
88  * Before Tulip 4.8 and as a fallback, this function uses the "TLP Export" export plugin
89  * (always loaded as it is linked into the tulip-core library).
90  *
91  * @param graph the graph to save.
92  * @param filename the file to save the graph to.
93  * @param progress PluginProgress to report the progress of the operation, as well as final state.
94  *Defaults to nullptr.
95  * @param data Parameters to pass to the export plugin (e.g. additional data, options for the
96  *format)
97  * @return bool whether the export was successfull or not.
98  **/
99 TLP_SCOPE bool saveGraph(Graph *graph, const std::string &filename,
100  tlp::PluginProgress *progress = nullptr, tlp::DataSet *data = nullptr);
101 
102 /**
103  * @ingroup Graph
104  * @brief Exports a graph using the specified export plugin with parameters stored in the DataSet.
105  *
106  * You determine the destination, whether by using a fstream, or by saving the contents of the
107  *stream to the destination of your choice.
108  *
109  * @param graph The graph to export.
110  * @param outputStream The stream to export to. Can be a standard ostream, an ofstream, or even a
111  *gzipped ostream.
112  * @param format The format to use to export the Graph.
113  * @param dataSet Parameters to pass to the export plugin (e.g. additional data, options for the
114  *format)
115  * @param progress A PluginProgress to report the progress of the operation, as well as final state.
116  *Defaults to nullptr.
117  * @return bool Whether the export was successfull or not.
118  **/
119 TLP_SCOPE bool exportGraph(Graph *graph, std::ostream &outputStream, const std::string &format,
120  DataSet &dataSet, PluginProgress *progress = nullptr);
121 
122 /**
123  * @ingroup Graph
124  * @brief Imports a graph using the specified import plugin with the parameters stored in the
125  *DataSet.
126  *
127  * If no graph is passed, then a new graph will be created. You can pass a graph in order to import
128  *data into it.
129  * Returns the graph with imported data, or nullptr if the import failed. In this case, the
130  *Pluginprogress should have an error that can be displayed.
131  *
132  * @param format The format to use to import the graph.
133  * @param dataSet The parameters to pass to the import plugin (file to read, ...)
134  * @param progress A PluginProgress to report the progress of the operation, as well as final state.
135  *Defaults to nullptr.
136  * @param newGraph The graph to import the data into. This can be useful to import data into a
137  *subgraph. Defaults to nullptr.
138  * @return :Graph* The graph containing the imported data, or nullptr in case of failure.
139  **/
140 TLP_SCOPE Graph *importGraph(const std::string &format, DataSet &dataSet,
141  PluginProgress *progress = nullptr, Graph *newGraph = nullptr);
142 
143 /**
144  * @ingroup Graph
145  * @brief Creates a new, empty graph.
146  *
147  * This is a simple method factory to create a Graph implementation (remember, Graph is only an
148  *interface).
149  *
150  * This is the recommended way to create a new Graph.
151  *
152  * @return :Graph* A new, empty graph.
153  **/
154 TLP_SCOPE Graph *newGraph();
155 
156 /**
157  * @ingroup Graph
158  * Appends the selected part of the graph inG (properties, nodes and edges) into the graph outG.
159  * If no selection is done (inSel=nullptr), the whole inG graph is appended.
160  * The output selection is used to select the appended nodes & edges
161  * \warning The input selection is extended to all selected edge ends.
162  */
163 TLP_SCOPE void copyToGraph(Graph *outG, const Graph *inG, BooleanProperty *inSelection = nullptr,
164  BooleanProperty *outSelection = nullptr);
165 
166 /**
167  * @ingroup Graph
168  * Removes the selected part of the graph ioG (properties values, nodes and edges).
169  * If no selection is done (inSel=nullptr), the whole graph is reseted to default value.
170  * \warning The selection is extended to all selected edge ends.
171  */
172 TLP_SCOPE void removeFromGraph(Graph *ioG, BooleanProperty *inSelection = nullptr);
173 
174 /**
175  * @ingroup Graph
176  * Gets an iterator over the root graphs. That is all the currently existing graphs which have been
177  * created using the tlp::newGraph, tlp::loadGraph or tlp::importGraph functions and are the root
178  * graphs of an existing graph hierarchy.
179  * @return An iterator over all the root graphs. The caller of this function is responsible of the
180  * deletion of the returned iterator.
181  */
182 TLP_SCOPE Iterator<Graph *> *getRootGraphs();
183 
184 /**
185  * @ingroup Graph
186  * The class Graph is the interface of a Graph in the Tulip Library.
187  *
188  * There are a few principles to know when working with a Tulip Graph.
189  *
190  * @chapter Directed
191  * Every edge is directed in a Tulip Graph.
192  * You can choose to ignore this, but every edge has a source and destination.
193  *
194  * @chapter Inheritance
195  *
196  * Subgraphs inherit from their parent graph.
197  * This is true of nodes and edges; every node and edge in a subgraph also exists in each of its
198  *parent graphs.
199  * This is also true of properties; every property in a graph exist in all of its subgraphs, except
200  *if it has been replaced
201  * by a local property.
202  *
203  * For instance, if you have the following graph hierarchy:
204  * root
205  * / \
206  * A B
207  *
208  * Every node in A is in root, and every node in B is in root.
209  * Nodes can be in A and root but not B; or in B and root but not A.
210  *
211  * For instance, imagine a graph. You want to compare it to its Delaunay triangulation.
212  * You need to create a subgraph that is a clone of the original (say this is A) to keep the
213  *original graph,
214  * and another copy (say this one is B) on which you will perform the delaunay triangulation.
215  *
216  * B will have none of the original edges, and A will have only the original edges.
217  *
218  * As for properties; let's imagine the same graph hierarchy.
219  * You want to compare two different layouts on the same graph.
220  * You need to create two clone subgraphs, on each you make the 'viewLayout' property local.
221  * This results in A and B having different values for the layout, but everything else in common.
222  * You then can apply two different algorithms on A and B (e.g. Bubble Tree and Tree Radial).
223  *
224  * @chapter Meta Nodes
225  * A meta node is a node representing a subgraph of the current graph.
226  *
227  * @chapter Undo Redo
228  * The Tulip Graph object supports for undo and redo of modifications.
229  *The operations affect the whole graph hierarchy, and cannot be limited to a subgraph.
230  *
231  */
232 class TLP_SCOPE Graph : public Observable {
233 
234  friend class GraphAbstract;
235  friend class GraphUpdatesRecorder;
236  friend class GraphDecorator;
237  friend class PropertyManager;
238  friend class PropertyInterface;
239 
240 public:
241  Graph() : id(0) {}
242  ~Graph() override {}
243 
244  /**
245  * @brief Applies an algorithm plugin, identified by its name.
246  * Algorithm plugins are subclasses of the tlp::Algorithm interface.
247  * Parameters are transmitted to the algorithm trough the DataSet.
248  * To determine a plugin's parameters, you can either:
249  *
250  * * refer to its documentation
251  *
252  * * use buildDefaultDataSet on the plugin object if you have an instance of it
253  *
254  * * call getPluginParameters() with the name of the plugin on the PluginLister
255  *
256  *
257  * If an error occurs, a message describing the error should be stored in errorMessage.
258  *
259  * @param algorithm The algorithm to apply.
260  * @param errorMessage A string that will be modified to contain an error message if an error
261  *occurs.
262  * @param parameters The parameters of the algorithm. Defaults to nullptr.
263  * @param progress A PluginProgress to report the progress of the operation, as well as the final
264  *state. Defaults to nullptr.
265  * @return bool Whether the algorithm applied successfully or not. If not, check the error
266  *message.
267  **/
268  bool applyAlgorithm(const std::string &algorithm, std::string &errorMessage,
269  DataSet *parameters = nullptr, PluginProgress *progress = nullptr);
270 
271  //=========================================================================
272  // Graph hierarchy access and building
273  //=========================================================================
274 
275  /**
276  * @brief Removes all nodes, edges and subgraphs from this graph.
277  *
278  * Contrarily to creating a new Graph, this keeps attributes and properties.
279  *
280  * @return void
281  **/
282  virtual void clear() = 0;
283 
284  /**
285  * @brief Creates and returns a new subgraph of this graph.
286  *
287  * If a BooleanProperty is provided, only nodes and edges for which it is true will be added to
288  *the subgraph.
289  * If none is provided, then the subgraph will be empty.
290  *
291  * @param selection The elements to add to the new subgraph. Defaults to nullptr.
292  * @param name The name of the newly created subgraph. Defaults to "unnamed".
293  * @return :Graph* The newly created subgraph.
294  **/
295  virtual Graph *addSubGraph(BooleanProperty *selection = nullptr,
296  const std::string &name = "unnamed") = 0;
297 
298  /**
299  * @brief Creates and returns a new named subgraph of this graph.
300  *
301  * @param name The name of the newly created subgraph.
302  * @return :Graph* The newly created subgraph.
303  **/
304  Graph *addSubGraph(const std::string &name);
305 
306  /**
307  * @brief Creates and returns a subgraph that contains all the elements of this graph.
308  *
309  * @param name The name of the newly created subgraph. Defaults to "unnamed".
310  * @param addSibling if true the clone subgraph will be a sibling of this graph, if false (the
311  *default) it will be a subgraph of this graph
312  * @param addSiblingProperties if true the local properties will be cloned into the sibling of
313  *this graph, if false (the default) the local properties will not be cloned
314  * @return :Graph* The newly created clone subgraph. nullptr will be returned if addSibling is set
315  *to
316  *true and this graph is a root graph.
317  **/
318  virtual Graph *addCloneSubGraph(const std::string &name = "unnamed", bool addSibling = false,
319  bool addSiblingProperties = false);
320 
321  /**
322  * @brief Creates and returns a new subgraph of the graph induced by a vector of nodes.
323  * @since Tulip 5.0
324  * Every node contained in the given vector is added to the subgraph.
325  * Every edge connecting any two nodes in the set of given nodes is also added.
326  * @param nodes The nodes to add to the subgraph. All the edges between these nodes are added too.
327  * @param parentSubGraph If provided, is used as parent graph for the newly created subgraph
328  * instead of the graph this method is called on.
329  * @param name The name of the newly created subgraph.
330  * @return The newly created subgraph.
331  */
332  Graph *inducedSubGraph(const std::vector<node> &nodes, Graph *parentSubGraph = nullptr,
333  const std::string &name = "unnamed");
334 
335  /**
336  * @brief deprecated, use inducedSubGraph(const std::set<node>&, Graph* = nullptr, const
337  * std::string&
338  * = "unamed") instead
339  */
340  _DEPRECATED Graph *inducedSubGraph(const std::set<node> &nodeSet, Graph *parentSubGraph = nullptr,
341  const std::string &name = "unnamed");
342 
343  /**
344  * @brief Creates and returns a new subgraph of the graph induced by a selection of nodes and
345  * edges.
346  * @since Tulip 4.10
347  * Every node contained in the selection is added to the subgraph.
348  * Every edge and its source and target node contained in the selection is added to the subgraph.
349  * Every edge connecting any two nodes in the resulting set of nodes is also added.
350  * @param selection a selection of nodes and edges.
351  * @param parentSubGraph If provided, is used as parent graph for the newly created subgraph
352  * instead of the graph this method is called on.
353  * @param name The name of the newly created subgraph.
354  * @return The newly created subgraph.
355  */
356  Graph *inducedSubGraph(BooleanProperty *selection, Graph *parentSubGraph = nullptr,
357  const std::string &name = "unnamed");
358 
359  /**
360  * @brief Deletes a subgraph of this graph.
361  * All subgraphs of the removed graph are re-parented to this graph.
362  * For instance, with a graph hierarchy as follows :
363  * root
364  * / \
365  * A B
366  * /|\
367  * C D E
368  *
369  * @code root->delSubGraph(B);
370  * would result in the following hierarchy:
371  * root
372  * / | \\
373  * A C D E
374  *
375  * @param graph The subgraph to delete.
376  *
377  * @see delAllSubGraphs() if you want to remove all descendants of a graph.
378  */
379  virtual void delSubGraph(Graph *graph) = 0;
380 
381  /**
382  * @brief Deletes a subgraph of this graph and all of its subgraphs.
383  ** For instance, with a graph hierarchy as follows :
384  * root
385  * / \
386  * A B
387  * /|\
388  * C D E
389  *
390  * @codeline root->delSubGraph(B); @endcode
391  * would result in the following hierarchy:
392  * root
393  * |
394  * A
395  *
396  * @param graph The subgraph to delete.
397  * @see delSubGraph() if you want to keep the descendants of the subgraph to remove.
398  */
399  virtual void delAllSubGraphs(Graph *graph = nullptr) = 0;
400 
401  /**
402  * @brief Returns the parent of the graph. If called on the root graph, it returns itself.
403  * @return The parent of this graph (or itself if it is the root graph).
404  * @see getRoot() to directly retrieve the root graph.
405  */
406  virtual Graph *getSuperGraph() const = 0;
407 
408  /**
409  * @brief Gets the root graph of the graph hierarchy.
410  * @return The root graph of the graph hierarchy.
411  */
412  virtual Graph *getRoot() const = 0;
413 
414  /**
415  * @cond DOXYGEN_HIDDEN
416  * @brief Sets the parent of a graph.
417  * @warning ONLY USE IF YOU KNOW EXACTLY WHAT YOU ARE DOING.
418  * @endcond
419  */
420  virtual void setSuperGraph(Graph *) = 0;
421 
422  /**
423  * @brief Gets an iterator over all the subgraphs of the graph.
424  * For instance, in the following graph hierarchy:
425  ** root
426  * / \
427  * A B
428  * /|\
429  * C D E
430  *
431  * @codeline root->getSubGraphs(); @endcode
432  * Will return an iterator over A and B, but not C, D and E.
433  * @return An iterator over this graph's direct subgraphs.
434  */
435  virtual Iterator<Graph *> *getSubGraphs() const = 0;
436 
437  /**
438  * @brief Return a const reference on the vector of subgraphs of the graph
439  * It is the fastest way to access to subgraphs, Iterators are 25% slower.
440  * @remark o(1)
441  */
442  virtual const std::vector<Graph *> &subGraphs() const = 0;
443 
444  /**
445  * @brief This method returns the nth subgraph.
446  * Since subgraphs order cannot be ensured in every implementation, this method should be
447  equivalent to:
448  * @code
449  int i=0;
450  Iterator<Graph *> *it = g->getSubGraphs();
451  while (it->hasNext()) {
452  Graph *result = it->next();
453  if (i++ == n) {
454  delete it;
455  return result;
456  }
457  }
458  delete it;
459  return nullptr;
460  * @endcode
461  * @param n the index of the subgraph to retrieve.
462  * @return The n-th subgraph.
463  */
464  virtual Graph *getNthSubGraph(unsigned int n) const;
465 
466  /**
467  * @brief Return the number of direct subgraphs.
468  * For instance, in the following graph hierarchy:
469  * root
470  * / \
471  * A B
472  * /|\
473  * C D E
474  *
475  * @codeline root->numberOfSubGraphs(); @endcode
476  * Will return 2.
477  * @return The number of direct subgraphs.
478  * @see numberOfDescendantGraphs() to count in the whole hierarchy.
479  */
480  virtual unsigned int numberOfSubGraphs() const = 0;
481 
482  /**
483  * @brief Return the number of descendant subgraphs.
484  * For instance, in the following graph hierarchy:
485  * root
486  * / \
487  * A B
488  * /|\
489  * C D E
490  *
491  * @codeline root->numberOfSubGraphs(); @endcode
492  * Will return 5.
493  * @return The number of descendants subgraphs.
494  * @see numberOfSubGraphs() to count only direct subgraphs.
495  */
496  virtual unsigned int numberOfDescendantGraphs() const = 0;
497 
498  /**
499  * @brief Indicates if the graph argument is a direct subgraph.
500  * @param subGraph The graph to check is a subgraph of this graph.
501  * @return Whether subGraph is a direct subgraph of this graph.
502  * @see isDescendantGraph() to search in the whole hierarchy.
503  */
504  virtual bool isSubGraph(const Graph *subGraph) const = 0;
505 
506  /**
507  * @brief Indicates if the graph argument is a descendant of this graph.
508  * @param subGraph The graph to check is a descendant of this graph.
509  * @return Whether subGraph is a descendant of this graph.
510  * @see isSubGraph to search only in direct subgraphs.
511  */
512  virtual bool isDescendantGraph(const Graph *subGraph) const = 0;
513 
514  /**
515  * @brief Returns a pointer on the subgraph with the corresponding id
516  * or nullptr if there is no subgraph with that id.
517  * @param id The id of the subgraph to retrieve.
518  * @return A subgraph of the given id, or null if no such subgraph exists on this graph.
519  * @see getDescendantGraph(unsigned int) to search in the whole hierarchy.
520  */
521  virtual Graph *getSubGraph(unsigned int id) const = 0;
522 
523  /**
524  * @brief Returns a pointer on the subgraph with the corresponding name
525  * or nullptr if there is no subgraph with that name.
526  * @param name The name of the subgraph to retrieve.
527  * @return A Graph named name, or nullptr if no such subgraph exists on this graph.
528  * @see getDescendantGraph(const std::string &) to search in the whole hierarchy.
529  */
530  virtual Graph *getSubGraph(const std::string &name) const = 0;
531 
532  /**
533  * @brief Returns a pointer on the descendant with the corresponding id
534  * or nullptr if there is no descendant with that id.
535  * @param id The id of the descendant graph to retrieve.
536  * @return A graph with the given id, or nullptr if no such graph exists in this graph's
537  * descendants.
538  * @see getSubGraph(unsigned int) to search only in direct subgraphs.
539  */
540  virtual Graph *getDescendantGraph(unsigned int id) const = 0;
541 
542  /**
543  * @brief Returns a pointer on the first descendant graph with the corresponding name
544  * or nullptr if there is no descendant graph with that name.
545  * @param name The name of the descendant graph to look for.
546  * @return A graph named name, or nullptr if there is no such graph in this graph's descendants.
547  * @see getSubGraph(const std::string &) to search only in direct subgraphs.
548  */
549  virtual Graph *getDescendantGraph(const std::string &name) const = 0;
550 
551  /**
552  * @brief Gets an iterator over all the descendant subgraphs of the graph.
553  * For instance, in the following graph hierarchy:
554  ** root
555  * / \
556  * A B
557  * /|\
558  * C D E
559  *
560  * @codeline root->getSubGraphs(); @endcode
561  * Will return an iterator over A B, C, D and E.
562  * @return An iterator over this graph's descendant subgraphs.
563  */
564  Iterator<Graph *> *getDescendantGraphs() const;
565 
566  //==============================================================================
567  // Modification of the graph structure
568  //==============================================================================
569  /**
570  * @brief Adds a new node in the graph and returns it. This node is also added in all
571  * the ancestor graphs.
572  * @return The newly added node.
573  * @see addNodes() if you want to add more than one node.
574  */
575  virtual node addNode() = 0;
576 
577  /**
578  * @brief Adds new nodes in the graph.
579  * The new nodes are also added in all the ancestor graphs.
580  *
581  * @param nbNodes The number of nodes to add.
582  * @see addNode() to add a single node.
583  */
584  virtual void addNodes(unsigned int nbNodes) = 0;
585 
586  /**
587  * @brief Adds new nodes in the graph and returns them in the addedNodes vector.
588  * The new nodes are also added in all the ancestor graphs.
589  *
590  * @param nbNodes The number of nodes to add.
591  * @param addedNodes The newly added nodes. This vector is cleared before being filled.
592  * @see addNode() to add a single node.
593  */
594  virtual void addNodes(unsigned int nbNodes, std::vector<node> &addedNodes) = 0;
595 
596  /**
597  * @brief Adds an existing node in the graph. This node is also added in all the ancestor graphs.
598  * This node must exists in the graph hierarchy (which means it must exist in the root graph).
599  * You cannot add a node to the root graph this way (as it must already be an element of the root
600  * graph).
601  * @warning Using this method on the root graph will display a warning on the console.
602  *
603  * @param n The node to add to a subgraph. This node must exist in the root graph.
604  * @see addNode() to add a new node to a graph.
605  */
606  virtual void addNode(const node n) = 0;
607 
608  /**
609  * @brief Adds existing nodes in the graph. The nodes are also added in all the ancestor graphs.
610  * as with addNode(const tlp::node), the nodes must exist in the graph hierarchy and thus exist in
611  the root graph,
612  * and node cannot be added this way to the root graph.
613 
614  * @warning Using this method on the root graph will display a warning on the console.
615  * @warning The graph does not take ownership of the Iterator.
616  *
617  * @param nodes An iterator over nodes to add to this subgraph. The graph does not takes ownership
618  of this iterator.
619  */
620  virtual void addNodes(Iterator<node> *nodes) = 0;
621 
622  /**
623  * @brief Adds existing nodes in the graph. The nodes are also added in all the ancestor graphs.
624  * as with addNode(const tlp::node), the nodes must exist in the graph hierarchy and thus exist in
625  the root graph,
626  * and nodes cannot be added this way to the root graph.
627 
628  * @warning Using this method on the root graph will display a warning on the console.
629  *
630  * @param nodes a vector of nodes to add to this subgraph.
631  */
632  void addNodes(const std::vector<node> &nodes);
633 
634  /**
635  * @brief Deletes a node in the graph.
636  * This node is also removed in the subgraphs hierarchy of the current graph.
637  * @param n The node to delete.
638  * @param deleteInAllGraphs Whether to delete in all its parent graphs or only in this graph. By
639  * default only removes in the current graph.
640  * @see delNodes() to remove multiple nodes.
641  */
642  virtual void delNode(const node n, bool deleteInAllGraphs = false) = 0;
643 
644  /**
645  * @brief Deletes nodes in the graph.
646  * These nodes are also removed in the subgraphs hierarchy of the current graph.
647  * @warning the graph does not take ownership of the Iterator.
648  * @param it The nodes to delete.
649  * @param deleteInAllGraphs Whether to delete in all its parent graphs or only in this graph. By
650  * default only removes in the current graph.
651  * @see delNode() to remove a single node.
652  */
653  virtual void delNodes(Iterator<node> *it, bool deleteInAllGraphs = false) = 0;
654 
655  /**
656  * @brief Deletes nodes in the graph.
657  * These nodes are also removed in the subgraphs hierarchy of the current graph.
658  * @warning the graph does not take ownership of the Iterator.
659  * @param nodes a vector of the nodes to delete.
660  * @param deleteInAllGraphs Whether to delete in all its parent graphs or only in this graph. By
661  * default only removes in the current graph.
662  * @see delNode() to remove a single node.
663  */
664  void delNodes(const std::vector<node> &nodes, bool deleteInAllGraphs = false);
665 
666  /**
667  * @brief Adds a new edge in the graph
668  * This edge is also added in all the super-graph of the graph.
669  * @param source The source of the edge.
670  * @param target The target of the edge.
671  * @return The newly added edge.
672  * @see addEdges() to add multiple edges at once.
673  */
674  virtual edge addEdge(const node source, const node target) = 0;
675 
676  /**
677  * @brief Adds new edges in the graph.
678  * The new edges are also added in all graph ancestors.
679  *
680  * @warning If the edges vector contains a node that does not belong to this graph,
681  * undefined behavior will ensue.
682  * @param edges A vector describing between which nodes to add edges.
683  * The first element of the pair is the source, the second is the destination.
684  *
685  */
686  virtual void addEdges(const std::vector<std::pair<node, node>> &edges) = 0;
687 
688  /**
689  * @brief Adds new edges in the graph and returns them in the addedEdges vector.
690  * The new edges are also added in all graph ancestors.
691  *
692  * @warning If the edges vector contains a node that does not belong to this graph,
693  * undefined behavior will ensue.
694  * @param edges A vector describing between which nodes to add edges.
695  * The first element of the pair is the source, the second is the destination.
696  * @param addedEdges The newly added edges. This vector is cleared before being filled.
697  *
698  */
699  virtual void addEdges(const std::vector<std::pair<node, node>> &edges,
700  std::vector<edge> &addedEdges) = 0;
701 
702  /**
703  * @brief Adds an existing edge in the graph. This edge is also added in all
704  * the ancestor graphs.
705  * The edge must be an element of the graph hierarchy, thus it must be
706  * an element of the root graph.
707  * @warning Using this method on the root graph will display a warning on the console.
708  * @param e The edge to add to this subgraph.
709  * @see addEgdes() to add more than one edge at once.
710  * @see addNode() to add nodes.
711  */
712  virtual void addEdge(const edge e) = 0;
713 
714  /**
715  * @brief Adds existing edges in the graph. The edges are also added in all
716  * the ancestor graphs.
717  * The added edges must be elements of the graph hierarchy,
718  * thus they must be elements of the root graph.
719  * @warning Using this method on the root graph will display a warning on the console.
720  * @warning The graph does not take ownership of the iterator.
721  * @param edges The edges to add on this subgraph.
722  */
723  virtual void addEdges(Iterator<edge> *edges) = 0;
724 
725  /**
726  * @brief Adds existing edges in the graph. The edges are also added in all
727  * the ancestor graphs.
728  * The added edges must be elements of the graph hierarchy,
729  * thus they must be elements of the root graph.
730  * @warning Using this method on the root graph will display a warning on the console.
731  * @param edges a vector of the edges to add on this subgraph.
732  */
733  void addEdges(const std::vector<edge> &edges);
734 
735  /**
736  * @brief Deletes an edge in the graph. The edge is also removed in
737  * the subgraphs hierarchy.
738  * The ordering of remaining edges is preserved.
739  * @param e The edge to delete.
740  * @param deleteInAllGraphs Whether to delete in all its parent graphs or only in this graph. By
741  * default only removes in the current graph.
742  */
743  virtual void delEdge(const edge e, bool deleteInAllGraphs = false) = 0;
744 
745  /**
746  * @brief Deletes edges in the graph. These edges are also removed in the subgraphs hierarchy.
747  * The ordering of remaining edges is preserved.
748  * @warning The graph does not take ownership of the Iterator.
749  * @param itE
750  * @param deleteInAllGraphs Whether to delete in all its parent graphs or only in this graph. By
751  * default only removes in the current graph.
752  */
753  virtual void delEdges(Iterator<edge> *itE, bool deleteInAllGraphs = false) = 0;
754 
755  /**
756  * @brief Deletes edges in the graph. These edges are also removed in the subgraphs hierarchy.
757  * The ordering of remaining edges is preserved.
758  * @warning The graph does not take ownership of the Iterator.
759  * @param edges a vector of the edges to delete
760  * @param deleteInAllGraphs Whether to delete in all its parent graphs or only in this graph. By
761  * default only removes in the current graph.
762  */
763  void delEdges(const std::vector<edge> &edges, bool deleteInAllGraphs = false);
764 
765  /**
766  * @brief Sets the order of the edges around a node.
767  * This operation ensures that adjacent edges of a node will
768  * be ordered as they are in the vector of edges given in parameter.
769  *
770  * This can be useful if you want to make sure you retrieve the edges in a specific order when
771  * iterating upon them.
772  * @param n The node whose edges to order.
773  * @param edges The edges, in the order you want them.
774  */
775  virtual void setEdgeOrder(const node n, const std::vector<edge> &edges) = 0;
776 
777  /**
778  * @brief Swaps two edges in the adjacency list of a node.
779  * @param n The node on whoch to swap the edges order.
780  * @param e1 The first edge, that will take the second edge's position.
781  * @param e2 The second edge, that will take the first edge's position.
782  */
783  virtual void swapEdgeOrder(const node n, const edge e1, const edge e2) = 0;
784 
785  /**
786  * @brief Sets the source of an edge to be the given node.
787  * @param e The edge to change the source of.
788  * @param source The new source of the edge.
789  */
790  virtual void setSource(const edge e, const node source) = 0;
791 
792  /**
793  * @brief Sets the target of an edge to be the given node.
794  * @param e The edge to change the target of.
795  * @param target The new target of the edge.
796  */
797  virtual void setTarget(const edge e, const node target) = 0;
798 
799  /**
800  * @brief Sets both the source and the target of an edge.
801  * @param e The edge to set the source and target of.
802  * @param source The new source of the edge.
803  * @param target The new target of the edge.
804  */
805  virtual void setEnds(const edge e, const node source, const node target) = 0;
806 
807  /**
808  * @brief Reverses the direction of an edge, the source becomes the target and the target
809  * becomes the source.
810  * @warning The ordering is global to the entire graph hierarchy. Thus, by changing
811  * the ordering of a graph you change the ordering of the hierarchy.
812  * @param e The edge top reverse.
813  */
814  virtual void reverse(const edge e) = 0;
815  // Attempts to reserve enough space to store nodes.
816  // Only defined on root graph.
817  virtual void reserveNodes(unsigned int nbNodes) = 0;
818  // Attempts to reserve enough space to store edges.
819  // Only defined on root graph.
820  virtual void reserveEdges(unsigned int nbEdges) = 0;
821  //================================================================================
822  // Iterators on the graph structure.
823  //================================================================================
824  /**
825  * @brief Finds the first node whose input degree equals 0.
826  *
827  * @return tlp::node The first encountered node with input degree of 0, or an invalid node if none
828  *was found.
829  **/
830  virtual tlp::node getSource() const;
831 
832  /**
833  * @brief Finds the first node whose output degree equals 0.
834  *
835  * @return tlp::node The first encountered node with output degree of 0, or an invalid node if
836  *none was found.
837  **/
838  virtual tlp::node getSink() const;
839 
840  /**
841  * @brief Returns the first node in the graph.
842  *
843  */
844  virtual node getOneNode() const = 0;
845 
846  /**
847  * @brief Returns a random node in the graph.
848  *
849  * @since Tulip 4.8
850  *
851  */
852  virtual node getRandomNode() const = 0;
853 
854  /**
855  * @brief Return a const reference on the vector of nodes of the graph
856  * It is the fastest way to access to nodes, Iterators are 25% slower.
857  * @remark o(1)
858  */
859  virtual const std::vector<node> &nodes() const = 0;
860 
861  /**
862  * @brief Return the position of a node in the vector of nodes of the graph
863  * @param n The node for which the position is requested
864  */
865  virtual unsigned int nodePos(const node n) const = 0;
866 
867  /**
868  * @brief Gets an iterator over this graph's nodes.
869  * @return An iterator over all the nodes of this graph.
870  * @see getInNodes()
871  * @see getOutNodes()
872  * @see getInOutNodes()
873  * @see getEdges()
874  */
875  virtual Iterator<node> *getNodes() const = 0;
876 
877  /**
878  * @brief Gets the i-th node in the input nodes of a given node.
879  * An input node 'in' of a node 'N' is the source of an edge going from
880  * 'in' to 'N'. e.g.
881  * @code
882  * node in = graph->addNode();
883  * node N = graph->addNode();
884  * graph->addEdge(in, N);
885  * //in == graph->getInNode(N, 1);
886  * @endcode
887  *
888  * If you have 5 input nodes on a node N, then
889  * @codeline graph->getInNode(2); @endcode
890  * will return the second of those nodes.
891  * It will ignore the output nodes of this node.
892  * @param n The node to get an input node of.
893  * @param i The index of the input node to get.
894  * @return The i-th input node of the given node.
895  * @see getInNodes()
896  * @see getInEdges()
897  */
898  virtual node getInNode(const node n, unsigned int i) const = 0;
899 
900  /**
901  * @brief Gets an iterator over the input nodes of a node.
902  * @param n The node to get the input nodes of.
903  * @return An iterator over the input nodes of a node.
904  * @see getInNode()
905  * @see getInOutNodes()
906  * @see getInEdges()
907  */
908  virtual Iterator<node> *getInNodes(const node n) const = 0;
909 
910  /**
911  * @brief Gets the i-th node in the output nodes of a given node.
912  * An output node 'out' of a node 'N' is the target of an edge going from
913  * 'N' to 'out'. e.g.
914  * @code
915  * node N = graph->addNode();
916  * node out = graph->addNode();
917  * graph->addEdge(N, out);
918  * //out == graph->getOutNode(N, 1);
919  * @endcode
920  *
921  * If you have 5 output nodes on a node N, then
922  * @codeline graph->getOutNode(2); @endcode
923  * will return the second of those nodes.
924  * It will ignore the input nodes of this node.
925  * @param n The node to get an output node of.
926  * @param i The index of the output node to get.
927  * @return The i-th output node of the given node.
928  * @see getOutNodes()
929  * @see getOutEdges()
930  */
931  virtual node getOutNode(const node n, unsigned int i) const = 0;
932 
933  /**
934  * @brief Gets an iterator over the output nodes of a node.
935  * @param n The node to get the output nodes of.
936  * @return An iterator over the output nodes of a node.
937  * @see getOutNode()
938  * @see getInOutNodes()
939  * @see getOutEdges()
940  */
941  virtual Iterator<node> *getOutNodes(const node n) const = 0;
942 
943  /**
944  * @brief Gets an iterator over the neighbors of a given node.
945  * @param n The node to retrieve the neighbors of.
946  * @return An iterator over the node's neighbors.
947  */
948  virtual Iterator<node> *getInOutNodes(const node n) const = 0;
949 
950  /**
951  * @brief Gets an iterator performing a breadth-first search on the graph.
952  * @param root The node from whom to start the BFS. If not provided, the root
953  * node will be assigned to a source node in the graph (node with input degree equals to 0).
954  * If there is no source node in the graph, a random node will be picked.
955  * @return A stable iterator over the graph nodes in the BFS order.
956  */
957  virtual Iterator<node> *bfs(const node root = node()) const = 0;
958 
959  /**
960  * @brief Gets an iterator performing a depth-first search on the graph.
961  * @param root The node from whom to start the DFS. If not provided, the root
962  * node will be assigned to a source node in the graph (node with input degree equals to 0).
963  * If there is no source node in the graph, a random node will be picked.
964  * @return A stable iterator over the graph nodes in the DFS order.
965  */
966  virtual Iterator<node> *dfs(const node root = node()) const = 0;
967 
968  /**
969  * @brief Gets the underlying graph of a meta node.
970  * @param metaNode The metanode.
971  * @return The Graph pointed to by the metanode.
972  * @see getEdgeMetaInfo()
973  */
974  virtual Graph *getNodeMetaInfo(const node metaNode) const = 0;
975 
976  /**
977  * @brief Return a const reference on the vector of edges of the graph
978  * It is the fastest way to access to edges, Iterators are 25% slower.
979  * @remark o(1)
980  */
981  virtual const std::vector<edge> &edges() const = 0;
982 
983  /**
984  * @brief Return the position of an edge in the vector of edges of the graph
985  * @param e The edge for which the position is requested
986  */
987  virtual unsigned int edgePos(const edge e) const = 0;
988 
989  /**
990  * @brief Get an iterator over all the graph's edges.
991  * @return An iterator over all the graph's edges.
992  * @see getInEdges()
993  * @see getOutEdges()
994  * @see getInOutEdges()
995  */
996  virtual Iterator<edge> *getEdges() const = 0;
997 
998  /**
999  * @brief Returns the first edge in the graph.
1000  *
1001  */
1002  virtual edge getOneEdge() const = 0;
1003 
1004  /**
1005  * @brief Returns a random edge in the graph.
1006  *
1007  * @since Tulip 4.8
1008  *
1009  */
1010  virtual edge getRandomEdge() const = 0;
1011 
1012  /**
1013  * @brief Gets an iterator over the output edges of a node.
1014  * @param n The node to get the output edges from.
1015  * @return An iterator over the node's output edges.
1016  * @see getEdges()
1017  * @see getOutEdges()
1018  * @see getInOutEdges()
1019  */
1020  virtual Iterator<edge> *getOutEdges(const node n) const = 0;
1021 
1022  /**
1023  * @brief Gets an iterator over the edges of a node.
1024  * @param n The node to get the edges from.
1025  * @return An iterator over the node's edges.
1026  * @see getEdges()
1027  * @see getOutEdges()
1028  * @see getInEdges()
1029  */
1030  virtual Iterator<edge> *getInOutEdges(const node n) const = 0;
1031 
1032  /**
1033  * @brief Gets an iterator over the input edges of a node.
1034  * @param n The node to get the input edges from.
1035  * @return An iterator over the node's input edges.
1036  * @see getEdges()
1037  * @see getOutEdges()
1038  * @see getInOutEdges()
1039  */
1040  virtual Iterator<edge> *getInEdges(const node n) const = 0;
1041 
1042  /**
1043  * @brief Gets all input/output edges of a node existing in the root graph
1044  * @warning If the current graph is not the root, the existence of the edge
1045  * can be tested with isElement(edge) function.
1046  * @param n The node to get the input/ouput edges from.
1047  * @return a const reference to the vector of all edges of a node
1048  */
1049  virtual const std::vector<edge> &allEdges(const node n) const = 0;
1050 
1051  /**
1052  * @brief Gets an iterator over the edges composing a meta edge.
1053  * @param metaEdge The metaEdge to get the real edges of.
1054  * @return An Iterator over the edges composing the metaEdge.
1055  * @see getNodeMetaInfo()
1056  */
1057  virtual Iterator<edge> *getEdgeMetaInfo(const edge metaEdge) const = 0;
1058 
1059  /**
1060  * @brief sort the graph elements in ascending order
1061  * @warning: That operation modify the vector of nodes and the vector of edges
1062  * and thus devalidate all iterators.
1063  */
1064  virtual void sortElts() = 0;
1065 
1066  //================================================================================
1067  // Graph, nodes and edges information about the graph stucture
1068  //================================================================================
1069  /**
1070  * @brief Gets the unique identifier of the graph.
1071  * @return The unique identifier of this graph.
1072  */
1073  unsigned int getId() const {
1074  return id;
1075  }
1076 
1077  /**
1078  * @brief return whether the graph is empty or not.
1079  * @return true if the graph has no nodes, false if not.
1080  */
1081  virtual inline bool isEmpty() const {
1082  return nodes().empty();
1083  }
1084 
1085  /**
1086  * @brief Gets the number of nodes in this graph.
1087  * @return The number of nodes in this graph.
1088  * @see numberOfEdges()
1089  */
1090  virtual unsigned int numberOfNodes() const = 0;
1091 
1092  /**
1093  * @brief Gets the number of edges in this graph.
1094  * @return The number of edges in this graph.
1095  * @see numberOfNodes()
1096  */
1097  virtual unsigned int numberOfEdges() const = 0;
1098 
1099  /**
1100  * @param n The node to get the degree of.
1101  * @return The degree of the given node.
1102  */
1103  virtual unsigned int deg(const node n) const = 0;
1104 
1105  /**
1106  * @brief Get the input degree of a node.
1107  * @param n The node to get the input degree of.
1108  * @return The input degree of the given node.
1109  */
1110  virtual unsigned int indeg(const node n) const = 0;
1111 
1112  /**
1113  * @brief Get the output degree of a node.
1114  * @param n The node to get the output degree of.
1115  * @return The output degree of the given node.
1116  */
1117  virtual unsigned int outdeg(const node n) const = 0;
1118 
1119  /**
1120  * @brief Gets the source of an edge.
1121  * @param e The edge to get the source of.
1122  * @return The source of the given edge.
1123  */
1124  virtual node source(const edge e) const = 0;
1125 
1126  /**
1127  * @brief Gets the target of an edge.
1128  * @param e The edge to get the target of.
1129  * @return The target of the given edge.
1130  */
1131  virtual node target(const edge e) const = 0;
1132 
1133  /**
1134  * @brief Gets the source and the target of an edge.
1135  * @param e The edge to get the ends of.
1136  * @return A pair whose first element is the source, and second is the target.
1137  */
1138  virtual const std::pair<node, node> &ends(const edge e) const = 0;
1139 
1140  /**
1141  * @brief Gets the opposite node of n through e.
1142  * @param e The edge linking the two nodes.
1143  * @param n The node at one end of e.
1144  * @return The node at the other end of e.
1145  */
1146  virtual node opposite(const edge e, const node n) const = 0;
1147 
1148  /**
1149  * @brief Checks if an element belongs to this graph.
1150  * @param n The node to check if it is an element of the graph.
1151  * @return Whether or not the element belongs to the graph.
1152  */
1153  virtual bool isElement(const node n) const = 0;
1154 
1155  /**
1156  * @brief Checks if a node is a meta node.
1157  * @param n The node to check if it is a meta node.
1158  * @return Whether or not the node is a meta node.
1159  */
1160  virtual bool isMetaNode(const node n) const = 0;
1161 
1162  /**
1163  * @brief Checks if an element belongs to this graph.
1164  * @param e The edge to check if it is an element of the graph.
1165  * @return Whether or not the element belongs to the graph.
1166  */
1167  virtual bool isElement(const edge e) const = 0;
1168 
1169  /**
1170  * @brief Checks if an edge is a meta edge.
1171  * @param e The edge to check if it is a meta edge.
1172  * @return Whether or not the edge is a meta edge.
1173  */
1174  virtual bool isMetaEdge(const edge e) const = 0;
1175 
1176  /**
1177  * @brief Checks if an edge exists between two given nodes.
1178  * @param source The source of the hypothetical edge.
1179  * @param target The target of the hypothetical edge.
1180  * @param directed When set to false edges from target to source are also considered
1181  * @return true if such an edge exists
1182  */
1183  virtual bool hasEdge(const node source, const node target, bool directed = true) const {
1184  return existEdge(source, target, directed).isValid();
1185  }
1186 
1187  /**
1188  * @brief Returns all the edges between two nodes.
1189  * @param source The source of the hypothetical edges.
1190  * @param target The target of the hypothetical edges.
1191  * @param directed When set to false edges from target to source are also considered
1192  * @return a vector of existing edges
1193  */
1194  virtual std::vector<edge> getEdges(const node source, const node target,
1195  bool directed = true) const = 0;
1196 
1197  /**
1198  * @brief Returns the first edge found between the two given nodes.
1199  * @warning This function always returns an edge,
1200  * you need to check if this edge is valid with edge::isValid().
1201  * @param source The source of the hypothetical edge.
1202  * @param target The target of the hypothetical edge.
1203  * @param directed When set to false
1204  * an edge from target to source may also be returned
1205  * @return An edge that is only valid if it exists.
1206  */
1207  virtual edge existEdge(const node source, const node target, bool directed = true) const = 0;
1208 
1209  //================================================================================
1210  // Access to the graph attributes and to the node/edge property.
1211  //================================================================================
1212  /**
1213  * @brief Sets the name of the graph.
1214  * The name does not have to be unique, it is used for convenience.
1215  * @param name The new name of the graph.
1216  */
1217  virtual void setName(const std::string &name) = 0;
1218 
1219  /**
1220  * @brief Retrieves the name of the graph.
1221  * @return The name of the graph.
1222  */
1223  virtual std::string getName() const = 0;
1224 
1225  /**
1226  * @brief Gets the attributes of the graph.
1227  *
1228  * The attributes contains the name and any user-defined value.
1229  * @return The attributes of the graph.
1230  */
1231  const DataSet &getAttributes() const {
1232  return const_cast<Graph *>(this)->getNonConstAttributes();
1233  }
1234 
1235  /**
1236  * @brief Gets an attribute on the graph.
1237  * @param name The name of the attribute to set.
1238  * @param value The value to set.
1239  * @return Whether the setting of the attribute was sucessful.
1240  */
1241  template <typename ATTRIBUTETYPE>
1242  bool getAttribute(const std::string &name, ATTRIBUTETYPE &value) const;
1243 
1244  /**
1245  * @brief Gets a copy of the attribute.
1246  * @param name The name of the attribute to retrieve.
1247  * @return A copy of the attribute to retrieve.
1248  */
1249  DataType *getAttribute(const std::string &name) const;
1250 
1251  /**
1252  * @brief Sets an attribute on the graph.
1253  * @param name The name of the attribute to set.
1254  * @param value The value to set on this attribute.
1255  */
1256  template <typename ATTRIBUTETYPE>
1257  void setAttribute(const std::string &name, const ATTRIBUTETYPE &value);
1258 
1259  /**
1260  * @brief Sets an attribute on the graph.
1261  * @param name The name of the attribute to set.
1262  * @param value The value to set.
1263  */
1264  void setAttribute(const std::string &name, const DataType *value);
1265 
1266  /**
1267  * @brief Removes an attribute on the graph.
1268  * @param name The name of the attribute to remove.
1269  */
1270  void removeAttribute(const std::string &name) {
1271  notifyRemoveAttribute(name);
1272  getNonConstAttributes().remove(name);
1273  }
1274 
1275  /**
1276  * @brief Checks if an attribute exists.
1277  * @param name The name of the attribute to check for.
1278  * @return Whether the attribute exists.
1279  */
1280  bool existAttribute(const std::string &name) const {
1281  return getAttributes().exists(name);
1282  }
1283 
1284  /**
1285  * @brief deprecated, use existAttribute instead.
1286  */
1287  _DEPRECATED bool attributeExist(const std::string &name) const {
1288  return existAttribute(name);
1289  }
1290 
1291  /**
1292  * @brief Adds a property to the graph.
1293  * The graph takes ownership of the property. If you want to delete it, use
1294  * Graph::delLocalProperty().
1295  * @param name The unique identifier of the property.
1296  * @param prop The property to add.
1297  */
1298  virtual void addLocalProperty(const std::string &name, PropertyInterface *prop) = 0;
1299 
1300  /**
1301  * @brief Gets an existing property.
1302  * In DEBUG mode an assertion checks the existence of the property.
1303  *
1304  * The graph keeps ownership of the property, if you wish to remove it from the graph use
1305  * Graph::delLocalProperty().
1306  *
1307  * @param name The unique identifier of the property.
1308  * @return An existing property, or nullptr if no property with the given name exists.
1309  */
1310  virtual PropertyInterface *getProperty(const std::string &name) const = 0;
1311 
1312  /**
1313  * @brief Gets a property on this graph.
1314  * The name of a property identifies it uniquely.
1315  * Either there already exists a property with the given name, in which case it is returned.
1316  * Either no such property exists and it is created.
1317  *
1318  * The graph keeps ownership of the property, if you wish to remove it from the graph use
1319  * Graph::delLocalProperty().
1320  * @warning using the wrong template parameter will cause a segmentation fault.
1321  * @param The unique identifier of the property.
1322  * @return The property of given name.
1323  */
1324  template <typename PropertyType>
1325  PropertyType *getLocalProperty(const std::string &name);
1326 
1327  /**
1328  * @brief Gets a property on this graph or one of its ancestors.
1329  * If the property already exists on the graph or in one of its ancestors, it is returned.
1330  * Otherwise a new property is created on this graph.
1331  *
1332  * The graph keeps ownership of the property, if you wish to remove it from the graph use
1333  * Graph::delLocalProperty().
1334  *
1335  * @warning using the wrong propertyType will result in a segmentation fault. Using an invalid
1336  * property type will always return nullptr.
1337  * @param name The unique identifier of the property.
1338  * @return An existing property, or a new one if none exists with the given name.
1339  */
1340  template <typename PropertyType>
1341  PropertyType *getProperty(const std::string &name);
1342 
1343  /**
1344  * @brief Gets a property on this graph, and this graph only.
1345  * This forwards the call to the template version of getLocalProperty(), with the correct template
1346  * parameter deduced from the propertyType parameter.
1347  *
1348  * The graph keeps ownership of the property, if you wish to remove it from the graph use
1349  * Graph::delLocalProperty().
1350  *
1351  * @warning using the wrong propertyType will result in a segmentation fault. Using an invalid
1352  * property type will always return nullptr.
1353  * @param propertyName The unique identifier of the property.
1354  * @param propertyType A string describing the type of the property.
1355  * @return The property of given name.
1356  * @see getLocalProperty().
1357  */
1358  PropertyInterface *getLocalProperty(const std::string &propertyName,
1359  const std::string &propertyType);
1360 
1361  /**
1362  * @brief Gets a property on this graph or one of its ancestors.
1363  * This forwards the call to the template version of getProperty(), with the correct template
1364  * parameter deduced from the propertyType parameter.
1365  *
1366  * The graph keeps ownership of the property, if you wish to remove it from the graph use
1367  * Graph::delLocalProperty().
1368  *
1369  * @warning using the wrong propertyType will result in a segmentation fault. Using an invalid
1370  * property type will always return nullptr.
1371  * @param propertyName The unique identifier of the property.
1372  * @param propertyType A string describing the type of the property.
1373  * @return The property of given name.
1374  * @see getProperty().
1375  */
1376  PropertyInterface *getProperty(const std::string &propertyName, const std::string &propertyType);
1377 
1378  /**
1379  * @brief Checks if a property exists in this graph or one of its ancestors.
1380  * @param The unique identifier of the property.
1381  * @return Whether a property with the given name exists.
1382  */
1383  virtual bool existProperty(const std::string &name) const = 0;
1384 
1385  /**
1386  * @brief Checks if a property exists in this graph.
1387  * @param The unique identifier of the property.
1388  * @return Whether a property with the given name exists.
1389  */
1390  virtual bool existLocalProperty(const std::string &name) const = 0;
1391 
1392  /**
1393  * @brief Removes and deletes a property from this graph.
1394  * The property is removed from the graph's property pool, meaning its name can now be used by
1395  * another property.
1396  * The object is deleted and the memory freed.
1397  * @param name The unique identifier of the property.
1398  */
1399  virtual void delLocalProperty(const std::string &name) = 0;
1400 
1401  /**
1402  * @brief Gets an iterator over the names of the local properties of this graph.
1403  * @return An iterator over this graph's properties names.
1404  */
1405  virtual Iterator<std::string> *getLocalProperties() const = 0;
1406 
1407  /**
1408  * @brief Gets an iterator over the local properties of this graph.
1409  * @return An iterator over this graph's properties.
1410  */
1411  virtual Iterator<PropertyInterface *> *getLocalObjectProperties() const = 0;
1412 
1413  /**
1414  * @brief Gets an iterator over the names of the properties inherited from this graph's ancestors,
1415  * excluding this graph's local properties.
1416  * @return An iterator over the names of the properties this graph inherited.
1417  */
1418  virtual Iterator<std::string> *getInheritedProperties() const = 0;
1419 
1420  /**
1421  * @brief Gets an iterator over the properties inherited from this graph's ancestors,
1422  * excluding this graph's local properties.
1423  * @return An iterator over the properties this graph inherited.
1424  */
1425  virtual Iterator<PropertyInterface *> *getInheritedObjectProperties() const = 0;
1426 
1427  /**
1428  * @brief Gets an iterator over the names of all the properties attached to this graph,
1429  * whether they are local or inherited.
1430  * @return An iterator over the names of all the properties attached to this graph.
1431  */
1432  virtual Iterator<std::string> *getProperties() const = 0;
1433 
1434  /**
1435  * @brief Gets an iterator over the properties attached to this graph,
1436  * whether they are local or inherited.
1437  * @return An iterator over all of the properties attached to this graph.
1438  */
1439  virtual Iterator<PropertyInterface *> *getObjectProperties() const = 0;
1440 
1441  /**
1442  * @brief Runs a plugin on the graph, whose result is a property.
1443  *
1444  * @param algorithm The name of the plugin to run.
1445  * @param result The property in which to store the computed nodes/edges associated values. All
1446  * previous values will be erased.
1447  * @param errorMessage Stores the error message if the plugin fails.
1448  * @param parameters The parameters of the algorithm. Some algorithms use this DataSet to output
1449  * @param progress A PluginProgress to report the progress of the operation, as well as the final
1450  * state. Defaults to nullptr.
1451  * some additional information.
1452  * @return Whether the plugin applied successfully or not. If not, check the error message.
1453  *
1454  * @see PluginLister::getPluginParameters() to retrieve the list of default parameters for the
1455  * plugin.
1456  */
1457  bool applyPropertyAlgorithm(const std::string &algorithm, PropertyInterface *result,
1458  std::string &errorMessage, DataSet *parameters = nullptr,
1459  PluginProgress *progress = nullptr);
1460 
1461  /**
1462  * @brief Deprecated, use applyPropertyAlgorithm(const std::string &algorithm, PropertyInterface
1463  * *result, std::string &errorMessage, DataSet *parameters = nullptr, PluginProgress *progress =
1464  * nullptr) instead
1465  */
1466  _DEPRECATED bool applyPropertyAlgorithm(const std::string &algorithm, PropertyInterface *result,
1467  std::string &errorMessage, PluginProgress *progress,
1468  DataSet *parameters = nullptr) {
1469  return applyPropertyAlgorithm(algorithm, result, errorMessage, parameters, progress);
1470  }
1471 
1472  // updates management
1473  /**
1474  * @brief Saves the current state of the whole graph hierarchy and allows to revert to this state
1475  * later on, using pop().
1476  * All modifications except those altering the ordering of the edges will be undone.
1477  *
1478  * This allows to undo/redo modifications on a graph.
1479  * This is mostly useful from a user interface point of view, but some algorithms use this
1480  * mechanism to clean up before finishing.
1481  * For instance:
1482  * @code
1483  * Graph* graph = tlp::newGraph();
1484  * DoubleProperty* prop = graph->getProperty<DoubleProperty>("metric");
1485  * string errorMessage;
1486  *
1487  * //our super metric stuff we want to kee
1488  * DoubleProperty* superProperty = graph->getProperty<DoubleProperty>("superStuff");
1489  * vector<PropertyInterface*> propertiesToKeep;
1490  * propertiesToKeep.push_back(superProperty);
1491  *
1492  *
1493  * //apply some metric
1494  * graph->applyPropertyAlgorithm("Degree", prop, errorMessage);
1495  *
1496  * // save this state to be able to revert to it later
1497  * //however we do not want to allow to unpop(), which would go forward again to the state where
1498  * prop contains 'Depth'.
1499  * //this saves some memory.
1500  * //Also we always want to keep the value of our super property, so we pass it in the collection
1501  * of properties to leave unaffected by the pop().
1502  * graph->push(false, propertiesToKeep);
1503  *
1504  * //compute the quality of this metric, or whatever makes sense
1505  * int degreeQuality = prop->getMax();
1506  *
1507  * //compute another metric
1508  * graph->applyPropertyAlgorithm("Depth", prop, errorMessage);
1509  *
1510  * //compute our secret metric, that depends on depth
1511  * graph->applyPropertyAlgorithm("MySuperSecretAlgorithm", superProperty, errorMessage);
1512  *
1513  * //compute its quality
1514  * int depthQuality = prop->getMax();
1515  *
1516  * //if the degree was better, revert back to the state where its contents were in prop.
1517  * if(degreeQuality > depthQuality) {
1518  * //this does not affect superProperty, as we told the system not to consider it when
1519  * recording modifications to potentially revert.
1520  * graph->pop();
1521  * }
1522  *
1523  * //do some stuff using our high quality metric
1524  * ColorProperty* color = graph->getProperty("viewColor");
1525  * graph->applyPropertyAlgorithm("Color Mapping", color, errorMessage);
1526  *
1527  * @endcode
1528  *
1529  * @param unpopAllowed Whether or not to allow to re-do the modifications once they are undone.
1530  * @param propertiesToPreserveOnPop A collection of properties whose state to preserve when using
1531  * pop().
1532  * @see pop()
1533  * @see popIfNoUpdates()
1534  * @see unpop()
1535  * @see canPop()
1536  * @see canUnPop()
1537  * @see canPopThenUnPop()
1538  */
1539  virtual void push(bool unpopAllowed = true,
1540  std::vector<PropertyInterface *> *propertiesToPreserveOnPop = nullptr) = 0;
1541 
1542  /**
1543  * @brief Undoes modifications and reverts the whole graph hierarchy back to a previous state.
1544  *
1545  * @param unpopAllowed Whether or not it is possible to redo what will be undoe by this call.
1546  */
1547  virtual void pop(bool unpopAllowed = true) = 0;
1548 
1549  /**
1550  * @brief abort last push if no updates have been recorded
1551  */
1552  virtual void popIfNoUpdates() = 0;
1553 
1554  /**
1555  * @brief Re-perform actions that were undone using pop().
1556  *
1557  * For instance:
1558  * @code
1559  * DoubleProperty* prop = graph->getProperty<DoubleProperty>("metric");
1560  * string errorMessage;
1561  *
1562  * //apply some metric
1563  * graph->applyPropertyAlgorithm("Degree", prop, errorMessage);
1564  *
1565  * // save this state to be able to revert to it later
1566  * graph->push();
1567  *
1568  * //compute the quality of this metric, or whatever makes sense
1569  * int degreeQuality = prop->getMax();
1570  *
1571  * //compute another metric
1572  * graph->applyPropertyAlgorithm("Depth", prop, errorMessage);
1573  *
1574  * //compute its quality
1575  * int depthQuality = prop->getMax();
1576  *
1577  * //if the degree was better, revert back to the state where its contents were in prop.
1578  * if(degreeQuality > depthQuality) {
1579  * graph->pop();
1580  * }
1581  *
1582  * ...
1583  *
1584  * //revert back to the depth for some reason.
1585  * graph->unpop();
1586  * @endcode
1587  */
1588  virtual void unpop() = 0;
1589 
1590  /**
1591  * @brief Checks if there is a state to revert to.
1592  * @return Whether there was a previous call to push() that was not yet pop()'ed.
1593  */
1594  virtual bool canPop() = 0;
1595 
1596  /**
1597  * @brief Checks if the last undone modifications can be redone.
1598  * @return Whether it is possible to re-do modifications that have been undone by pop().
1599  */
1600  virtual bool canUnpop() = 0;
1601 
1602  /**
1603  * @brief Checks if it is possible to call pop() and then unPop(), to undo then re-do
1604  * modifications.
1605  * @return Whether it is possible to undo and then redo.
1606  */
1607  virtual bool canPopThenUnpop() = 0;
1608 
1609  // meta nodes management
1610  /**
1611  * @brief Creates a meta-node from a vector of nodes.
1612  * Every edges from any node in the vector to another node of the graph will be replaced with meta
1613  * edges
1614  * from the meta node to the other nodes.
1615  * @warning This method will fail when called on the root graph.
1616  *
1617  * @param nodes The vector of nodes to put into the meta node.
1618  * @param multiEdges Whether a meta edge should be created for each underlying edge.
1619  * @param delAllEdge Whether the underlying edges will be removed from the whole hierarchy.
1620  * @return The newly created meta node.
1621  */
1622  virtual node createMetaNode(const std::vector<node> &nodes, bool multiEdges = true,
1623  bool delAllEdge = true);
1624 
1625  /**
1626  * @brief Deprecated, use createMetaNode(const std::vector<node>&, bool multiEdges = true, bool
1627  * delAllEdge = true) instead
1628  */
1629  _DEPRECATED node createMetaNode(const std::set<node> &nodeSet, bool multiEdges = true,
1630  bool delAllEdge = true);
1631 
1632  /**
1633  * @brief Populates a quotient graph with one meta node
1634  * for each iterated graph.
1635  *
1636  * @param itS a Graph iterator, (typically a subgraph iterator)
1637  * @param quotientGraph the graph that will contain the meta nodes
1638  * @param metaNodes will contains all the added meta nodes after the call
1639  *
1640  */
1641  virtual void createMetaNodes(Iterator<Graph *> *itS, Graph *quotientGraph,
1642  std::vector<node> &metaNodes);
1643  /**
1644  * @brief Closes an existing subgraph into a metanode. Edges from nodes
1645  * in the subgraph to nodes outside the subgraph are replaced with
1646  * edges from the metanode to the nodes outside the subgraph.
1647  * @warning this method will fail when called on the root graph.
1648  *
1649  * @param subGraph an existing subgraph
1650  * @param multiEdges indicates if a meta edge will be created for each underlying edge
1651  * @param delAllEdge indicates if the underlying edges will be removed from the entire hierarchy
1652  */
1653  virtual node createMetaNode(Graph *subGraph, bool multiEdges = true, bool delAllEdge = true);
1654 
1655  /**
1656  * @brief Opens a metanode and replaces all edges between that
1657  * meta node and other nodes in the graph.
1658  *
1659  * @warning this method will fail when called on the root graph.
1660  *
1661  * @param n The meta node to open.
1662  * @param updateProperties If set to true, open meta node will update inner nodes layout, color,
1663  * size, etc
1664  */
1665  void openMetaNode(node n, bool updateProperties = true);
1666 
1667  ///@cond DOXYGEN_HIDDEN
1668 protected:
1669  virtual DataSet &getNonConstAttributes() = 0;
1670  // designed to reassign an id to a previously deleted elt
1671  // used by GraphUpdatesRecorder
1672  virtual void restoreNode(node) = 0;
1673  virtual void restoreEdge(edge, node source, node target) = 0;
1674  // designed to only update own structures
1675  // used by GraphUpdatesRecorder
1676  virtual void removeNode(const node) = 0;
1677  virtual void removeEdge(const edge) = 0;
1678 
1679  // to check if a property can be deleted
1680  // used by PropertyManager
1681  virtual bool canDeleteProperty(Graph *g, PropertyInterface *prop) {
1682  return getRoot()->canDeleteProperty(g, prop);
1683  }
1684 
1685  // local property renaming
1686  // can failed if a property with the same name already exists
1687  virtual bool renameLocalProperty(PropertyInterface *prop, const std::string &newName) = 0;
1688 
1689  // internally used to deal with sub graph deletion
1690  virtual void removeSubGraph(Graph *) = 0;
1691  virtual void clearSubGraphs() = 0;
1692  virtual void restoreSubGraph(Graph *) = 0;
1693  virtual void setSubGraphToKeep(Graph *) = 0;
1694 
1695  // for notification of GraphObserver
1696  void notifyAddNode(const node n);
1697  void notifyAddNode(Graph *, const node n) {
1698  notifyAddNode(n);
1699  }
1700  void notifyAddEdge(const edge e);
1701  void notifyAddEdge(Graph *, const edge e) {
1702  notifyAddEdge(e);
1703  }
1704  void notifyBeforeSetEnds(const edge e);
1705  void notifyBeforeSetEnds(Graph *, const edge e) {
1706  notifyBeforeSetEnds(e);
1707  }
1708  void notifyAfterSetEnds(const edge e);
1709  void notifyAfterSetEnds(Graph *, const edge e) {
1710  notifyAfterSetEnds(e);
1711  }
1712  void notifyDelNode(const node n);
1713  void notifyDelNode(Graph *, const node n) {
1714  notifyDelNode(n);
1715  }
1716  void notifyDelEdge(const edge e);
1717  void notifyDelEdge(Graph *, const edge e) {
1718  notifyDelEdge(e);
1719  }
1720  void notifyReverseEdge(const edge e);
1721  void notifyReverseEdge(Graph *, const edge e) {
1722  notifyReverseEdge(e);
1723  }
1724  void notifyBeforeAddSubGraph(const Graph *);
1725  void notifyAfterAddSubGraph(const Graph *);
1726  void notifyBeforeAddSubGraph(Graph *, const Graph *sg) {
1727  notifyBeforeAddSubGraph(sg);
1728  }
1729  void notifyAfterAddSubGraph(Graph *, const Graph *sg) {
1730  notifyAfterAddSubGraph(sg);
1731  }
1732  void notifyBeforeDelSubGraph(const Graph *);
1733  void notifyAfterDelSubGraph(const Graph *);
1734  void notifyBeforeDelSubGraph(Graph *, const Graph *sg) {
1735  notifyBeforeDelSubGraph(sg);
1736  }
1737  void notifyAfterDelSubGraph(Graph *, const Graph *sg) {
1738  notifyAfterDelSubGraph(sg);
1739  }
1740 
1741  void notifyBeforeAddDescendantGraph(const Graph *);
1742  void notifyAfterAddDescendantGraph(const Graph *);
1743  void notifyBeforeDelDescendantGraph(const Graph *);
1744  void notifyAfterDelDescendantGraph(const Graph *);
1745 
1746  void notifyBeforeAddLocalProperty(const std::string &);
1747  void notifyAddLocalProperty(const std::string &);
1748  void notifyAddLocalProperty(Graph *, const std::string &name) {
1749  notifyAddLocalProperty(name);
1750  }
1751  void notifyBeforeDelLocalProperty(const std::string &);
1752  void notifyAfterDelLocalProperty(const std::string &);
1753  void notifyDelLocalProperty(Graph *, const std::string &name) {
1754  notifyBeforeDelLocalProperty(name);
1755  }
1756  void notifyBeforeSetAttribute(const std::string &);
1757  void notifyBeforeSetAttribute(Graph *, const std::string &name) {
1758  notifyBeforeSetAttribute(name);
1759  }
1760  void notifyAfterSetAttribute(const std::string &);
1761  void notifyAfterSetAttribute(Graph *, const std::string &name) {
1762  notifyAfterSetAttribute(name);
1763  }
1764  void notifyRemoveAttribute(const std::string &);
1765  void notifyRemoveAttribute(Graph *, const std::string &name) {
1766  notifyRemoveAttribute(name);
1767  }
1768  void notifyDestroy();
1769  void notifyDestroy(Graph *) {
1770  notifyDestroy();
1771  }
1772 
1773  unsigned int id;
1774  TLP_HASH_MAP<std::string, tlp::PropertyInterface *> circularCalls;
1775  ///@endcond
1776 };
1777 
1778 /**
1779  * @ingroup Observation
1780  * Event class for specific events on Graph
1781  **/
1782 class TLP_SCOPE GraphEvent : public Event {
1783 public:
1784  // be careful about the ordering of the constants
1785  // in the enum below because it is used in some assertions
1786  enum GraphEventType {
1787  TLP_ADD_NODE = 0,
1788  TLP_DEL_NODE = 1,
1789  TLP_ADD_EDGE = 2,
1790  TLP_DEL_EDGE = 3,
1791  TLP_REVERSE_EDGE = 4,
1792  TLP_BEFORE_SET_ENDS = 5,
1793  TLP_AFTER_SET_ENDS = 6,
1794  TLP_ADD_NODES = 7,
1795  TLP_ADD_EDGES = 8,
1796  TLP_BEFORE_ADD_DESCENDANTGRAPH = 9,
1797  TLP_AFTER_ADD_DESCENDANTGRAPH = 10,
1798  TLP_BEFORE_DEL_DESCENDANTGRAPH = 11,
1799  TLP_AFTER_DEL_DESCENDANTGRAPH = 12,
1800  TLP_BEFORE_ADD_SUBGRAPH = 13,
1801  TLP_AFTER_ADD_SUBGRAPH = 14,
1802  TLP_BEFORE_DEL_SUBGRAPH = 15,
1803  TLP_AFTER_DEL_SUBGRAPH = 16,
1804  TLP_ADD_LOCAL_PROPERTY = 17,
1805  TLP_BEFORE_DEL_LOCAL_PROPERTY = 18,
1806  TLP_AFTER_DEL_LOCAL_PROPERTY = 19,
1807  TLP_ADD_INHERITED_PROPERTY = 20,
1808  TLP_BEFORE_DEL_INHERITED_PROPERTY = 21,
1809  TLP_AFTER_DEL_INHERITED_PROPERTY = 22,
1810  TLP_BEFORE_RENAME_LOCAL_PROPERTY = 23,
1811  TLP_AFTER_RENAME_LOCAL_PROPERTY = 24,
1812  TLP_BEFORE_SET_ATTRIBUTE = 25,
1813  TLP_AFTER_SET_ATTRIBUTE = 26,
1814  TLP_REMOVE_ATTRIBUTE = 27,
1815  TLP_BEFORE_ADD_LOCAL_PROPERTY = 28,
1816  TLP_BEFORE_ADD_INHERITED_PROPERTY = 29
1817  };
1818 
1819  // constructor for node/edge/nodes/edges events
1820  GraphEvent(const Graph &g, GraphEventType graphEvtType, unsigned int id,
1821  Event::EventType evtType = Event::TLP_MODIFICATION)
1822  : Event(g, evtType), evtType(graphEvtType) {
1823  if (graphEvtType == TLP_ADD_NODES || graphEvtType == TLP_ADD_EDGES)
1824  info.nbElts = id;
1825  else
1826  info.eltId = id;
1827 
1828  vectInfos.addedNodes = nullptr;
1829  }
1830  // constructor for subgraph events
1831  GraphEvent(const Graph &g, GraphEventType graphEvtType, const Graph *sg)
1832  : Event(g, Event::TLP_MODIFICATION), evtType(graphEvtType) {
1833  info.subGraph = sg;
1834  vectInfos.addedNodes = nullptr;
1835  }
1836 
1837  // constructor for attribute/property events
1838  GraphEvent(const Graph &g, GraphEventType graphEvtType, const std::string &str,
1839  Event::EventType evtType = Event::TLP_MODIFICATION)
1840  : Event(g, evtType), evtType(graphEvtType) {
1841  info.name = new std::string(str);
1842  vectInfos.addedNodes = nullptr;
1843  }
1844 
1845  // constructor for rename property events
1846  GraphEvent(const Graph &g, GraphEventType graphEvtType, PropertyInterface *prop,
1847  const std::string &newName)
1848  : Event(g, Event::TLP_MODIFICATION), evtType(graphEvtType) {
1849  info.renamedProp = new std::pair<PropertyInterface *, std::string>(prop, newName);
1850  vectInfos.addedNodes = nullptr;
1851  }
1852 
1853  ~GraphEvent() override;
1854 
1855  Graph *getGraph() const {
1856  return static_cast<Graph *>(sender());
1857  }
1858 
1859  node getNode() const {
1860  assert(evtType < TLP_ADD_EDGE);
1861  return node(info.eltId);
1862  }
1863 
1864  edge getEdge() const {
1865  assert(evtType > TLP_DEL_NODE && evtType < TLP_ADD_NODES);
1866  return edge(info.eltId);
1867  }
1868 
1869  const std::vector<node> &getNodes() const;
1870 
1871  unsigned int getNumberOfNodes() const {
1872  assert(evtType == TLP_ADD_NODES);
1873  return info.nbElts;
1874  }
1875 
1876  const std::vector<edge> &getEdges() const;
1877 
1878  unsigned int getNumberOfEdges() const {
1879  assert(evtType == TLP_ADD_EDGES);
1880  return info.nbElts;
1881  }
1882 
1883  const Graph *getSubGraph() const {
1884  assert(evtType > TLP_ADD_EDGES && evtType < TLP_ADD_LOCAL_PROPERTY);
1885  return info.subGraph;
1886  }
1887 
1888  const std::string &getAttributeName() const {
1889  assert(evtType > TLP_AFTER_DEL_INHERITED_PROPERTY);
1890  return *(info.name);
1891  }
1892 
1893  const std::string &getPropertyName() const;
1894 
1895  PropertyInterface *getProperty() const {
1896  assert(evtType == TLP_BEFORE_RENAME_LOCAL_PROPERTY ||
1897  evtType == TLP_AFTER_RENAME_LOCAL_PROPERTY);
1898  return info.renamedProp->first;
1899  }
1900 
1901  const std::string &getPropertyNewName() const {
1902  assert(evtType == TLP_BEFORE_RENAME_LOCAL_PROPERTY);
1903  return info.renamedProp->second;
1904  }
1905 
1906  const std::string &getPropertyOldName() const {
1907  assert(evtType == TLP_AFTER_RENAME_LOCAL_PROPERTY);
1908  return info.renamedProp->second;
1909  }
1910 
1911  GraphEventType getType() const {
1912  return evtType;
1913  }
1914 
1915 protected:
1916  GraphEventType evtType;
1917  union {
1918  unsigned int eltId;
1919  const Graph *subGraph;
1920  std::string *name;
1921  unsigned int nbElts;
1922  std::pair<PropertyInterface *, std::string> *renamedProp;
1923  } info;
1924  union {
1925  std::vector<node> *addedNodes;
1926  std::vector<edge> *addedEdges;
1927  } vectInfos;
1928 };
1929 } // namespace tlp
1930 
1931 /// Print the graph (only nodes and edges) in ostream, in the tulip format
1932 TLP_SCOPE std::ostream &operator<<(std::ostream &, const tlp::Graph *);
1933 
1934 //================================================================================
1935 // these functions allow to use tlp::Graph as a key in a hash-based data structure (e.g. hashmap).
1936 //================================================================================
1937 ///@cond DOXYGEN_HIDDEN
1938 TLP_BEGIN_HASH_NAMESPACE {
1939  template <>
1940  struct TLP_SCOPE hash<const tlp::Graph *> {
1941  size_t operator()(const tlp::Graph *s) const {
1942  return size_t(s->getId());
1943  }
1944  };
1945  template <>
1946  struct TLP_SCOPE hash<tlp::Graph *> {
1947  size_t operator()(tlp::Graph *s) const {
1948  return size_t(s->getId());
1949  }
1950  };
1951 }
1952 TLP_END_HASH_NAMESPACE
1953 ///@endcond
1954 
1955 #include "cxx/Graph.cxx"
1956 #endif
void removeFromGraph(Graph *ioG, BooleanProperty *inSelection=nullptr)
bool attributeExist(const std::string &name) const
deprecated, use existAttribute instead.
Definition: Graph.h:1287
A graph property that maps a boolean value to graph elements.
virtual bool isEmpty() const
return whether the graph is empty or not.
Definition: Graph.h:1081
Interface for Tulip iterators. Allows basic iteration operations only.
Definition: Graph.h:41
Graph * newGraph()
Creates a new, empty graph.
PropertyInterface describes the interface of a graph property.
virtual bool hasEdge(const node source, const node target, bool directed=true) const
Checks if an edge exists between two given nodes.
Definition: Graph.h:1183
Describes a value of any type.
Definition: DataSet.h:57
A container that can store data from any type.
Definition: DataSet.h:189
Graph * loadGraph(const std::string &filename, tlp::PluginProgress *progress=nullptr)
Loads a graph from a file (extension can be any of the Tulip supported input graph file format)...
bool existAttribute(const std::string &name) const
Checks if an attribute exists.
Definition: Graph.h:1280
Graph * importGraph(const std::string &format, DataSet &dataSet, PluginProgress *progress=nullptr, Graph *newGraph=nullptr)
Imports a graph using the specified import plugin with the parameters stored in the DataSet...
Iterator< Graph * > * getRootGraphs()
ElementType
Definition: Graph.h:48
const DataSet & getAttributes() const
Gets the attributes of the graph.
Definition: Graph.h:1231
The edge struct represents an edge in a Graph object.
Definition: Edge.h:40
The node struct represents a node in a Graph object.
Definition: Node.h:40
Event is the base class for all events used in the Observation mechanism.
Definition: Observable.h:51
PluginProcess subclasses are meant to notify about the progress state of some process (typically a pl...
bool applyPropertyAlgorithm(const std::string &algorithm, PropertyInterface *result, std::string &errorMessage, PluginProgress *progress, DataSet *parameters=nullptr)
Deprecated, use applyPropertyAlgorithm(const std::string &algorithm, PropertyInterface *result...
Definition: Graph.h:1466
void removeAttribute(const std::string &name)
Removes an attribute on the graph.
Definition: Graph.h:1270
void copyToGraph(Graph *outG, const Graph *inG, BooleanProperty *inSelection=nullptr, BooleanProperty *outSelection=nullptr)
unsigned int getId() const
Gets the unique identifier of the graph.
Definition: Graph.h:1073
The Observable class is the base of Tulip&#39;s observation system.
Definition: Observable.h:141
bool saveGraph(Graph *graph, const std::string &filename, tlp::PluginProgress *progress=nullptr, tlp::DataSet *data=nullptr)
Saves the corresponding graph to a file (extension can be any of the Tulip supported ouput graph file...
bool exportGraph(Graph *graph, std::ostream &outputStream, const std::string &format, DataSet &dataSet, PluginProgress *progress=nullptr)
Exports a graph using the specified export plugin with parameters stored in the DataSet.
std::ostream & operator<<(std::ostream &os, const Array< T, N > &array)
operator << stream operator to easily print an array, or save it to a file.