1 ============================ 2 |(logo)|__ ``read_graphml`` 3 ============================ 4 5 .. Copyright (C) 2006 Tiago de Paula Peixoto <tiago@forked.de> 6 7 Distributed under the Boost Software License, Version 1.0. (See 8 accompanying file LICENSE_1_0.txt or copy at 9 http://www.boost.org/LICENSE_1_0.txt) 10 11 Authors: Tiago de Paula Peixoto 12 13 .. |(logo)| image:: ../../../boost.png 14 :align: middle 15 :alt: Boost 16 17 __ ../../../index.htm 18 19 :: 20 21 void read_graphml(std::istream& in, MutableGraph& graph, 22 dynamic_properties& dp, size_t graph_index = 0); 23 24 25 The ``read_graphml`` function interprets a graph described using the 26 GraphML_ format and builds a BGL graph that captures that 27 description. Using this function, you can initialize a graph using 28 data stored as text. 29 30 The GraphML format can specify both directed and undirected graphs, and 31 ``read_graphml`` differentiates between the two. One must pass 32 ``read_graphml`` an undirected graph when reading an undirected graph; 33 the same is true for directed graphs. Furthermore, ``read_graphml`` 34 will throw an exception if it encounters parallel edges and cannot add 35 them to the graph. 36 37 To handle attributes expressed in the GraphML format, ``read_graphml`` 38 takes a dynamic_properties_ object and operates on its collection of 39 property maps. The reader passes all the properties encountered to 40 this object, using the GraphML attribute names as the property names, 41 and with the appropriate C++ value type based on the GraphML attribute type 42 definition. Graph properties are also set with the same 43 dynamic_properties_ object, where the key type is the type of the graph itself. 44 45 If the file contains multiple graphs, the ``graph_index`` parameter controls 46 which graph will be loaded. It defaults to ``0``, meaning that the first graph 47 in the file will be loaded. If ``graph_index`` is greater than or equal to the 48 number of graphs in the file, an empty graph will be returned. 49 50 Requirements: 51 - The type of the graph must model the `Mutable Graph`_ concept. 52 - The type of the iterator must model the `Multi-Pass Iterator`_ 53 concept. 54 - The property map value types must be default-constructible. 55 56 57 .. contents:: 58 59 Where Defined 60 ------------- 61 ``<boost/graph/graphml.hpp>`` 62 63 Exceptions 64 ---------- 65 66 :: 67 68 struct graph_exception : public std::exception { 69 virtual ~graph_exception() throw(); 70 virtual const char* what() const throw() = 0; 71 }; 72 73 struct bad_parallel_edge : public graph_exception { 74 std::string from; 75 std::string to; 76 77 bad_parallel_edge(const std::string&, const std::string&); 78 virtual ~bad_parallel_edge() throw(); 79 const char* what() const throw(); 80 }; 81 82 struct directed_graph_error : public graph_exception { 83 virtual ~directed_graph_error() throw(); 84 virtual const char* what() const throw(); 85 }; 86 87 struct undirected_graph_error : public graph_exception { 88 virtual ~undirected_graph_error() throw(); 89 virtual const char* what() const throw(); 90 }; 91 92 struct parse_error : public graph_exception { 93 parse_error(const std::string&); 94 virtual ~parse_error() throw() {} 95 virtual const char* what() const throw(); 96 std::string statement; 97 std::string error; 98 }; 99 100 Under certain circumstances, ``read_graphml`` will throw one of the 101 above exceptions. The three concrete exceptions can all be caught 102 using the general ``graph_exception`` moniker when greater precision 103 is not needed. In addition, all of the above exceptions derive from 104 the standard ``std::exception`` for even more generalized error 105 handling. 106 107 The ``bad_parallel_edge`` exception is thrown when an attempt to add a 108 parallel edge to the supplied MutableGraph fails. The GraphML format 109 supports parallel edges, but some BGL-compatible graph types do not. 110 One example of such a graph is ``boost::adjacency_list<setS,vecS>``, 111 which allows at most one edge can between any two vertices. 112 113 114 The ``directed_graph_error`` exception occurs when an undirected graph 115 type is passed to ``read_graph``, but the graph defined in the GraphML 116 file contains at least one directed edge. 117 118 The ``undirected_graph_error`` exception occurs when a directed graph 119 type is passed to ``read_graph``, but the graph defined in the GraphML 120 file contains at least one undirected edge. 121 122 The ``parse_error`` exception occurs when a syntax error is 123 encountered in the GraphML file. The error string will contain the 124 line and column where the error was encountered. 125 126 127 Building the GraphML reader 128 ----------------------------- 129 To use the GraphML reader, you will need to build and link against 130 the "boost_graph" library. The library can be built by following the 131 `Boost Jam Build Instructions`_ for the subdirectory ``libs/graph/build``. 132 133 134 Notes 135 ----- 136 137 - On successful reading of a graph, every vertex and edge will have 138 an associated value for every respective edge and vertex property 139 encountered while interpreting the graph. These values will be set 140 using the ``dynamic_properties`` object. Some properties may be 141 ``put`` multiple times during the course of reading in order to 142 ensure the GraphML semantics. Those edges and vertices that are 143 not explicitly given a value for a property (and that property has 144 no default) will be given the default constructed value of the 145 value type. **Be sure that property map value types are default 146 constructible.** 147 148 - Nested graphs are supported as long as they are exactly of the same 149 type as the root graph, i.e., are also directed or undirected. Note 150 that since nested graphs are not directly supported by BGL, they 151 are in fact completely ignored when building the graph, and the 152 internal vertices or edges are interpreted as belonging to the root 153 graph. 154 155 - Hyperedges and Ports are not supported. 156 157 See Also 158 -------- 159 160 write_graphml_ 161 162 163 .. _GraphML: http://graphml.graphdrawing.org/ 164 .. _`Mutable Graph`: MutableGraph.html 165 .. _`Multi-Pass Iterator`: ../../iterator/index.html 166 .. _dynamic_properties: ../../property_map/doc/dynamic_property_map.html 167 .. _write_graphml: write_graphml.html 168 .. _Boost Jam Build Instructions: ../../../more/getting_started.html#Build_Install 169
