[ceph.git] / ceph / src / boost / libs / graph / doc / read_graphml.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>Boost read_graphml</title>
<link rel="stylesheet" href="../../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="logo-read-graphml">
<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>

<!-- Copyright (C) 2006  Tiago de Paula Peixoto <tiago@forked.de>

Distributed under the Boost Software License, Version 1.0. (See
accompanying file LICENSE_1_0.txt or copy at
http://www.boost.org/LICENSE_1_0.txt)

Authors: Tiago de Paula Peixoto -->
<pre class="literal-block">
void read_graphml(std::istream&amp; in, MutableGraph&amp; graph,
                  dynamic_properties&amp; dp, size_t graph_index = 0);
</pre>
<p>The <tt class="docutils literal"><span class="pre">read_graphml</span></tt> function interprets a graph described using the
<a class="reference external" href="http://graphml.graphdrawing.org/">GraphML</a> format and builds a BGL graph that captures that
description.  Using this function, you can initialize a graph using
data stored as text.</p>
<p>The GraphML format can specify both directed and undirected graphs, and
<tt class="docutils literal"><span class="pre">read_graphml</span></tt> differentiates between the two. One must pass
<tt class="docutils literal"><span class="pre">read_graphml</span></tt> an undirected graph when reading an undirected graph;
the same is true for directed graphs. Furthermore, <tt class="docutils literal"><span class="pre">read_graphml</span></tt>
will throw an exception if it encounters parallel edges and cannot add
them to the graph.</p>
<p>To handle attributes expressed in the GraphML format, <tt class="docutils literal"><span class="pre">read_graphml</span></tt>
takes a <a class="reference external" href="../../property_map/doc/dynamic_property_map.html">dynamic_properties</a> object and operates on its collection of
property maps.  The reader passes all the properties encountered to
this object, using the GraphML attribute names as the property names,
and with the appropriate C++ value type based on the GraphML attribute type
definition. Graph properties are also set with the same
<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>
<p>If the file contains multiple graphs, the <tt class="docutils literal"><span class="pre">graph_index</span></tt> parameter controls
which graph will be loaded.  It defaults to <tt class="docutils literal"><span class="pre">0</span></tt>, meaning that the first graph
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
number of graphs in the file, an empty graph will be returned.</p>
<dl class="docutils">
<dt>Requirements:</dt>
<dd><ul class="first last simple">
<li>The type of the graph must model the <a class="reference external" href="MutableGraph.html">Mutable Graph</a> concept.</li>
<li>The type of the iterator must model the <a class="reference external" href="../../iterator/index.html">Multi-Pass Iterator</a>
concept.</li>
<li>The property map value types must be default-constructible.</li>
</ul>
</dd>
</dl>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#where-defined" id="id2">Where Defined</a></li>
<li><a class="reference internal" href="#exceptions" id="id3">Exceptions</a></li>
<li><a class="reference internal" href="#building-the-graphml-reader" id="id4">Building the GraphML reader</a></li>
<li><a class="reference internal" href="#notes" id="id5">Notes</a></li>
<li><a class="reference internal" href="#see-also" id="id6">See Also</a></li>
</ul>
</div>
<div class="section" id="where-defined">
<h1><a class="toc-backref" href="#id2">Where Defined</a></h1>
<p><tt class="docutils literal"><span class="pre">&lt;boost/graph/graphml.hpp&gt;</span></tt></p>
</div>
<div class="section" id="exceptions">
<h1><a class="toc-backref" href="#id3">Exceptions</a></h1>
<pre class="literal-block">
struct graph_exception : public std::exception {
  virtual ~graph_exception() throw();
  virtual const char* what() const throw() = 0;
};

struct bad_parallel_edge : public graph_exception {
  std::string from;
  std::string to;

  bad_parallel_edge(const std::string&amp;, const std::string&amp;);
  virtual ~bad_parallel_edge() throw();
  const char* what() const throw();
};

struct directed_graph_error : public graph_exception {
  virtual ~directed_graph_error() throw();
  virtual const char* what() const throw();
};

struct undirected_graph_error : public graph_exception {
  virtual ~undirected_graph_error() throw();
  virtual const char* what() const throw();
};

struct parse_error : public graph_exception {
  parse_error(const std::string&amp;);
  virtual ~parse_error() throw() {}
  virtual const char* what() const throw();
  std::string statement;
  std::string error;
};
</pre>
<p>Under certain circumstances, <tt class="docutils literal"><span class="pre">read_graphml</span></tt> will throw one of the
above exceptions.  The three concrete exceptions can all be caught
using the general <tt class="docutils literal"><span class="pre">graph_exception</span></tt> moniker when greater precision
is not needed.  In addition, all of the above exceptions derive from
the standard <tt class="docutils literal"><span class="pre">std::exception</span></tt> for even more generalized error
handling.</p>
<p>The <tt class="docutils literal"><span class="pre">bad_parallel_edge</span></tt> exception is thrown when an attempt to add a
parallel edge to the supplied MutableGraph fails.  The GraphML format
supports parallel edges, but some BGL-compatible graph types do not.
One example of such a graph is <tt class="docutils literal"><span class="pre">boost::adjacency_list&lt;setS,vecS&gt;</span></tt>,
which allows at most one edge can between any two vertices.</p>
<p>The <tt class="docutils literal"><span class="pre">directed_graph_error</span></tt> exception occurs when an undirected graph
type is passed to <tt class="docutils literal"><span class="pre">read_graph</span></tt>, but the graph defined in the GraphML
file contains at least one directed edge.</p>
<p>The <tt class="docutils literal"><span class="pre">undirected_graph_error</span></tt> exception occurs when a directed graph
type is passed to <tt class="docutils literal"><span class="pre">read_graph</span></tt>,  but the graph defined in the GraphML
file contains at least one undirected edge.</p>
<p>The <tt class="docutils literal"><span class="pre">parse_error</span></tt> exception occurs when a syntax error is
encountered in the GraphML file. The error string will contain the
line and column where the error was encountered.</p>
</div>
<div class="section" id="building-the-graphml-reader">
<h1><a class="toc-backref" href="#id4">Building the GraphML reader</a></h1>
<p>To use the GraphML reader, you will need to build and link against
the &quot;boost_graph&quot; library. The library can be built by following the
<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>
</div>
<div class="section" id="notes">
<h1><a class="toc-backref" href="#id5">Notes</a></h1>
<blockquote>
<ul class="simple">
<li>On successful reading of a graph, every vertex and edge will have
an associated value for every respective edge and vertex property
encountered while interpreting the graph.  These values will be set
using the <tt class="docutils literal"><span class="pre">dynamic_properties</span></tt> object.  Some properties may be
<tt class="docutils literal"><span class="pre">put</span></tt> multiple times during the course of reading in order to
ensure the GraphML semantics.  Those edges and vertices that are
not explicitly given a value for a property (and that property has
no default) will be given the default constructed value of the
value type.  <strong>Be sure that property map value types are default
constructible.</strong></li>
<li>Nested graphs are supported as long as they are exactly of the same
type as the root graph, i.e., are also directed or undirected. Note
that since nested graphs are not directly supported by BGL, they
are in fact completely ignored when building the graph, and the
internal vertices or edges are interpreted as belonging to the root
graph.</li>
<li>Hyperedges and Ports are not supported.</li>
</ul>
</blockquote>
</div>
<div class="section" id="see-also">
<h1><a class="toc-backref" href="#id6">See Also</a></h1>
<p><a class="reference external" href="write_graphml.html">write_graphml</a></p>
</div>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2012-11-12 22:25 UTC.
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.

</div>
</body>
</html>
Commit	Line	Data
7c673cae FG	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>