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 25The ``read_graphml`` function interprets a graph described using the 26GraphML_ format and builds a BGL graph that captures that 27description. Using this function, you can initialize a graph using 28data stored as text. 29 30The 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; 33the same is true for directed graphs. Furthermore, ``read_graphml`` 34will throw an exception if it encounters parallel edges and cannot add 35them to the graph. 36 37To handle attributes expressed in the GraphML format, ``read_graphml`` 38takes a dynamic_properties_ object and operates on its collection of 39property maps. The reader passes all the properties encountered to 40this object, using the GraphML attribute names as the property names, 41and with the appropriate C++ value type based on the GraphML attribute type 42definition. Graph properties are also set with the same 43dynamic_properties_ object, where the key type is the type of the graph itself. 44 45If the file contains multiple graphs, the ``graph_index`` parameter controls 46which graph will be loaded. It defaults to ``0``, meaning that the first graph 47in the file will be loaded. If ``graph_index`` is greater than or equal to the 48number of graphs in the file, an empty graph will be returned. 49 50Requirements: 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 59Where Defined 60------------- 61``<boost/graph/graphml.hpp>`` 62 63Exceptions 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 100Under certain circumstances, ``read_graphml`` will throw one of the 101above exceptions. The three concrete exceptions can all be caught 102using the general ``graph_exception`` moniker when greater precision 103is not needed. In addition, all of the above exceptions derive from 104the standard ``std::exception`` for even more generalized error 105handling. 106 107The ``bad_parallel_edge`` exception is thrown when an attempt to add a 108parallel edge to the supplied MutableGraph fails. The GraphML format 109supports parallel edges, but some BGL-compatible graph types do not. 110One example of such a graph is ``boost::adjacency_list<setS,vecS>``, 111which allows at most one edge can between any two vertices. 112 113 114The ``directed_graph_error`` exception occurs when an undirected graph 115type is passed to ``read_graph``, but the graph defined in the GraphML 116file contains at least one directed edge. 117 118The ``undirected_graph_error`` exception occurs when a directed graph 119type is passed to ``read_graph``, but the graph defined in the GraphML 120file contains at least one undirected edge. 121 122The ``parse_error`` exception occurs when a syntax error is 123encountered in the GraphML file. The error string will contain the 124line and column where the error was encountered. 125 126 127Building the GraphML reader 128----------------------------- 129To use the GraphML reader, you will need to build and link against 130the "boost_graph" library. The library can be built by following the 131`Boost Jam Build Instructions`_ for the subdirectory ``libs/graph/build``. 132 133 134Notes 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 157See Also 158-------- 159 160write_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
