]>
Commit | Line | Data |
---|---|---|
1 | <?xml version="1.0" encoding="utf-8" ?> | |
2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
3 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> | |
4 | <head> | |
5 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> | |
6 | <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> | |
7 | <title>Boost read_graphml</title> | |
8 | <link rel="stylesheet" href="../../../rst.css" type="text/css" /> | |
9 | </head> | |
10 | <body> | |
11 | <div class="document" id="logo-read-graphml"> | |
12 | <h1 class="title"><a class="reference external" href="../../../index.htm"><img align="middle" alt="Boost" class="align-middle" src="../../../boost.png" /></a> <tt class="docutils literal"><span class="pre">read_graphml</span></tt></h1> | |
13 | ||
14 | <!-- Copyright (C) 2006 Tiago de Paula Peixoto <tiago@forked.de> | |
15 | ||
16 | Distributed under the Boost Software License, Version 1.0. (See | |
17 | accompanying file LICENSE_1_0.txt or copy at | |
18 | http://www.boost.org/LICENSE_1_0.txt) | |
19 | ||
20 | Authors: Tiago de Paula Peixoto --> | |
21 | <pre class="literal-block"> | |
22 | void read_graphml(std::istream& in, MutableGraph& graph, | |
23 | dynamic_properties& dp, size_t graph_index = 0); | |
24 | </pre> | |
25 | <p>The <tt class="docutils literal"><span class="pre">read_graphml</span></tt> function interprets a graph described using the | |
26 | <a class="reference external" href="http://graphml.graphdrawing.org/">GraphML</a> 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.</p> | |
29 | <p>The GraphML format can specify both directed and undirected graphs, and | |
30 | <tt class="docutils literal"><span class="pre">read_graphml</span></tt> differentiates between the two. One must pass | |
31 | <tt class="docutils literal"><span class="pre">read_graphml</span></tt> an undirected graph when reading an undirected graph; | |
32 | the same is true for directed graphs. Furthermore, <tt class="docutils literal"><span class="pre">read_graphml</span></tt> | |
33 | will throw an exception if it encounters parallel edges and cannot add | |
34 | them to the graph.</p> | |
35 | <p>To handle attributes expressed in the GraphML format, <tt class="docutils literal"><span class="pre">read_graphml</span></tt> | |
36 | takes a <a class="reference external" href="../../property_map/doc/dynamic_property_map.html">dynamic_properties</a> object and operates on its collection of | |
37 | property maps. The reader passes all the properties encountered to | |
38 | this object, using the GraphML attribute names as the property names, | |
39 | and with the appropriate C++ value type based on the GraphML attribute type | |
40 | definition. Graph properties are also set with the same | |
41 | <a class="reference external" href="../../property_map/doc/dynamic_property_map.html">dynamic_properties</a> object, where the key type is the type of the graph itself.</p> | |
42 | <p>If the file contains multiple graphs, the <tt class="docutils literal"><span class="pre">graph_index</span></tt> parameter controls | |
43 | which graph will be loaded. It defaults to <tt class="docutils literal"><span class="pre">0</span></tt>, meaning that the first graph | |
44 | in the file will be loaded. If <tt class="docutils literal"><span class="pre">graph_index</span></tt> is greater than or equal to the | |
45 | number of graphs in the file, an empty graph will be returned.</p> | |
46 | <dl class="docutils"> | |
47 | <dt>Requirements:</dt> | |
48 | <dd><ul class="first last simple"> | |
49 | <li>The type of the graph must model the <a class="reference external" href="MutableGraph.html">Mutable Graph</a> concept.</li> | |
50 | <li>The type of the iterator must model the <a class="reference external" href="../../iterator/index.html">Multi-Pass Iterator</a> | |
51 | concept.</li> | |
52 | <li>The property map value types must be default-constructible.</li> | |
53 | </ul> | |
54 | </dd> | |
55 | </dl> | |
56 | <div class="contents topic" id="contents"> | |
57 | <p class="topic-title first">Contents</p> | |
58 | <ul class="simple"> | |
59 | <li><a class="reference internal" href="#where-defined" id="id2">Where Defined</a></li> | |
60 | <li><a class="reference internal" href="#exceptions" id="id3">Exceptions</a></li> | |
61 | <li><a class="reference internal" href="#building-the-graphml-reader" id="id4">Building the GraphML reader</a></li> | |
62 | <li><a class="reference internal" href="#notes" id="id5">Notes</a></li> | |
63 | <li><a class="reference internal" href="#see-also" id="id6">See Also</a></li> | |
64 | </ul> | |
65 | </div> | |
66 | <div class="section" id="where-defined"> | |
67 | <h1><a class="toc-backref" href="#id2">Where Defined</a></h1> | |
68 | <p><tt class="docutils literal"><span class="pre"><boost/graph/graphml.hpp></span></tt></p> | |
69 | </div> | |
70 | <div class="section" id="exceptions"> | |
71 | <h1><a class="toc-backref" href="#id3">Exceptions</a></h1> | |
72 | <pre class="literal-block"> | |
73 | struct graph_exception : public std::exception { | |
74 | virtual ~graph_exception() throw(); | |
75 | virtual const char* what() const throw() = 0; | |
76 | }; | |
77 | ||
78 | struct bad_parallel_edge : public graph_exception { | |
79 | std::string from; | |
80 | std::string to; | |
81 | ||
82 | bad_parallel_edge(const std::string&, const std::string&); | |
83 | virtual ~bad_parallel_edge() throw(); | |
84 | const char* what() const throw(); | |
85 | }; | |
86 | ||
87 | struct directed_graph_error : public graph_exception { | |
88 | virtual ~directed_graph_error() throw(); | |
89 | virtual const char* what() const throw(); | |
90 | }; | |
91 | ||
92 | struct undirected_graph_error : public graph_exception { | |
93 | virtual ~undirected_graph_error() throw(); | |
94 | virtual const char* what() const throw(); | |
95 | }; | |
96 | ||
97 | struct parse_error : public graph_exception { | |
98 | parse_error(const std::string&); | |
99 | virtual ~parse_error() throw() {} | |
100 | virtual const char* what() const throw(); | |
101 | std::string statement; | |
102 | std::string error; | |
103 | }; | |
104 | </pre> | |
105 | <p>Under certain circumstances, <tt class="docutils literal"><span class="pre">read_graphml</span></tt> will throw one of the | |
106 | above exceptions. The three concrete exceptions can all be caught | |
107 | using the general <tt class="docutils literal"><span class="pre">graph_exception</span></tt> moniker when greater precision | |
108 | is not needed. In addition, all of the above exceptions derive from | |
109 | the standard <tt class="docutils literal"><span class="pre">std::exception</span></tt> for even more generalized error | |
110 | handling.</p> | |
111 | <p>The <tt class="docutils literal"><span class="pre">bad_parallel_edge</span></tt> exception is thrown when an attempt to add a | |
112 | parallel edge to the supplied MutableGraph fails. The GraphML format | |
113 | supports parallel edges, but some BGL-compatible graph types do not. | |
114 | One example of such a graph is <tt class="docutils literal"><span class="pre">boost::adjacency_list<setS,vecS></span></tt>, | |
115 | which allows at most one edge can between any two vertices.</p> | |
116 | <p>The <tt class="docutils literal"><span class="pre">directed_graph_error</span></tt> exception occurs when an undirected graph | |
117 | type is passed to <tt class="docutils literal"><span class="pre">read_graph</span></tt>, but the graph defined in the GraphML | |
118 | file contains at least one directed edge.</p> | |
119 | <p>The <tt class="docutils literal"><span class="pre">undirected_graph_error</span></tt> exception occurs when a directed graph | |
120 | type is passed to <tt class="docutils literal"><span class="pre">read_graph</span></tt>, but the graph defined in the GraphML | |
121 | file contains at least one undirected edge.</p> | |
122 | <p>The <tt class="docutils literal"><span class="pre">parse_error</span></tt> 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.</p> | |
125 | </div> | |
126 | <div class="section" id="building-the-graphml-reader"> | |
127 | <h1><a class="toc-backref" href="#id4">Building the GraphML reader</a></h1> | |
128 | <p>To use the GraphML reader, you will need to build and link against | |
129 | the "boost_graph" library. The library can be built by following the | |
130 | <a class="reference external" href="../../../more/getting_started.html#Build_Install">Boost Jam Build Instructions</a> for the subdirectory <tt class="docutils literal"><span class="pre">libs/graph/build</span></tt>.</p> | |
131 | </div> | |
132 | <div class="section" id="notes"> | |
133 | <h1><a class="toc-backref" href="#id5">Notes</a></h1> | |
134 | <blockquote> | |
135 | <ul class="simple"> | |
136 | <li>On successful reading of a graph, every vertex and edge will have | |
137 | an associated value for every respective edge and vertex property | |
138 | encountered while interpreting the graph. These values will be set | |
139 | using the <tt class="docutils literal"><span class="pre">dynamic_properties</span></tt> object. Some properties may be | |
140 | <tt class="docutils literal"><span class="pre">put</span></tt> multiple times during the course of reading in order to | |
141 | ensure the GraphML semantics. Those edges and vertices that are | |
142 | not explicitly given a value for a property (and that property has | |
143 | no default) will be given the default constructed value of the | |
144 | value type. <strong>Be sure that property map value types are default | |
145 | constructible.</strong></li> | |
146 | <li>Nested graphs are supported as long as they are exactly of the same | |
147 | type as the root graph, i.e., are also directed or undirected. Note | |
148 | that since nested graphs are not directly supported by BGL, they | |
149 | are in fact completely ignored when building the graph, and the | |
150 | internal vertices or edges are interpreted as belonging to the root | |
151 | graph.</li> | |
152 | <li>Hyperedges and Ports are not supported.</li> | |
153 | </ul> | |
154 | </blockquote> | |
155 | </div> | |
156 | <div class="section" id="see-also"> | |
157 | <h1><a class="toc-backref" href="#id6">See Also</a></h1> | |
158 | <p><a class="reference external" href="write_graphml.html">write_graphml</a></p> | |
159 | </div> | |
160 | </div> | |
161 | <div class="footer"> | |
162 | <hr class="footer" /> | |
163 | Generated on: 2012-11-12 22:25 UTC. | |
164 | Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. | |
165 | ||
166 | </div> | |
167 | </body> | |
168 | </html> |