GraphML :: Boost.Graph Documentation

# GraphML

Read and write graphs in the GraphML XML format.

Defined in `<boost/graph/graphml.hpp>`
Linking: `read_graphml` requires `libboost_graph`. `write_graphml` is header-only.

| By default, `dynamic_properties` throws `property_not_found` if the file contains an attribute that was not registered. To silently skip unknown attributes, pass `ignore_other_properties` to the constructor:

    dynamic_properties dp(ignore_other_properties);
    // All other attributes in the file are silently ignored

## Example

    #include <boost/graph/adjacency_list.hpp>
    #include <boost/graph/graphml.hpp>
    #include <iostream>
    #include <sstream>

    struct City { std::string name; };
    struct Road { int weight; };

    int main() {
        using namespace boost;
        using Graph = adjacency_list<vecS, vecS, directedS, City, Road>;

        // --- Write ---
        Graph g(3);
        g[0].name = "Paris";
        g[1].name = "Lyon";
        g[2].name = "Marseille";
        add_edge(0, 1, Road{10}, g);
        add_edge(1, 2, Road{20}, g);
        add_edge(0, 2, Road{30}, g);

        dynamic_properties dp;
        dp.property("name", get(&City::name, g));
        dp.property("weight", get(&Road::weight, g));

        std::ostringstream xml;
        write_graphml(xml, g, dp, true);
        std::cout << "=== GraphML output ===\n" << xml.str() << "\n";

        // --- Read back ---
        Graph g2;
        dynamic_properties dp2;
        dp2.property("name", get(&City::name, g2));
        dp2.property("weight", get(&Road::weight, g2));

        std::istringstream in(xml.str());
        read_graphml(in, g2, dp2);

        std::cout << "=== Read back ===\n";
        std::cout << num_vertices(g2) << " vertices, "
                  << num_edges(g2) << " edges\n";
        for (auto v : make_iterator_range(vertices(g2))) {
            std::cout << "  " << g2[v].name << "\n";
        }
    }

    === GraphML output ===
    <?xml version="1.0" encoding="UTF-8"?>
    <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
      <key id="key0" for="node" attr.name="name" attr.type="string" />
      <key id="key1" for="edge" attr.name="weight" attr.type="int" />
      <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
        <node id="n0">
          <data key="key0">Paris</data>
        </node>
        <node id="n1">
          <data key="key0">Lyon</data>
        </node>
        <node id="n2">
          <data key="key0">Marseille</data>
        </node>
        <edge id="e0" source="n0" target="n1">
          <data key="key1">10</data>
        </edge>
        <edge id="e1" source="n0" target="n2">
          <data key="key1">30</data>
        </edge>
        <edge id="e2" source="n1" target="n2">
          <data key="key1">20</data>
        </edge>
      </graph>
    </graphml>

    === Read back ===
    3 vertices, 3 edges
      Paris
      Lyon
      Marseille

## read_graphml

    template <typename MutableGraph>
    void read_graphml(std::istream& in, MutableGraph& graph,
                      dynamic_properties& dp,
                      size_t graph_index = 0);

Direction | Parameter | Description
--- | --- | ---
IN | `std::istream& in` | GraphML-formatted XML input
OUT | `MutableGraph& graph` | Populated graph. Must model MutableGraph. Directionality must match the `edgedefault` attribute in the GraphML file.
IN/OUT | `dynamic_properties& dp` | Maps GraphML attribute names to property maps. Attribute types (string, int, double, …​) are determined by the GraphML `<key>` declarations.
IN | `graph_index` | Which graph to load if the file contains multiple `<graph>` elements. Default: 0 (the first graph). If `graph_index` is greater than or equal to the number of graphs in the file, an empty graph is returned.

| Nested graphs are not supported as distinct BGL entities. Nested vertices and edges are added to the root graph.

| Hyperedges and ports are not supported.

## write_graphml

### (1) Default vertex index

    template <typename Graph>
    void write_graphml(std::ostream& out, const Graph& g,
                       const dynamic_properties& dp,
                       bool ordered_vertices = false);

### (2) Custom vertex index

    template <typename Graph, typename VertexIndexMap>
    void write_graphml(std::ostream& out, const Graph& g,
                       VertexIndexMap vertex_index,
                       const dynamic_properties& dp,
                       bool ordered_vertices = false);

Direction | Parameter | Description
--- | --- | ---
OUT | `std::ostream& out` | Output stream
IN | `const Graph& g` | Must model VertexListGraph.
IN | `const dynamic_properties& dp` | All registered properties are emitted as GraphML attributes.
IN | `ordered_vertices` | If `true`, sets `parse.nodeids="canonical"` in the output (vertex order matches indices). If `false`, sets `parse.nodeids="free"`.
IN | `VertexIndexMap vertex_index` | Only needed if the graph has no built-in `vertex_index` property.

## Throws

Exception | When
--- | ---
`parse_error` | The input is not valid GraphML XML
`directed_graph_error` | GraphML contains directed edges but graph type is undirected
`undirected_graph_error` | GraphML contains undirected edges but graph type is directed
`bad_parallel_edge` | GraphML contains a parallel edge but graph type does not allow them