libs/graph/doc/read_graphml.rst

   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