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