/Src/Dependencies/Boost/boost/graph/named_graph.hpp

http://hadesmem.googlecode.com/ · C++ Header · 537 lines · 285 code · 70 blank · 182 comment · 3 complexity · 057a4975c20dd277e6d6ecec953d00c1 MD5 · raw file

  1. // Copyright (C) 2007 Douglas Gregor
  2. // Use, modification and distribution is subject to the Boost Software
  3. // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
  4. // http://www.boost.org/LICENSE_1_0.txt)
  5. // Provides support for named vertices in graphs, allowing one to more
  6. // easily associate unique external names (URLs, city names, employee
  7. // ID numbers, etc.) with the vertices of a graph.
  8. #ifndef BOOST_GRAPH_NAMED_GRAPH_HPP
  9. #define BOOST_GRAPH_NAMED_GRAPH_HPP
  10. #include <boost/config.hpp>
  11. #include <boost/type_traits/remove_cv.hpp>
  12. #include <boost/type_traits/remove_reference.hpp>
  13. #include <boost/multi_index_container.hpp>
  14. #include <boost/multi_index/hashed_index.hpp>
  15. #include <boost/multi_index/member.hpp>
  16. #include <boost/optional.hpp>
  17. #include <boost/throw_exception.hpp>
  18. #include <stdexcept> // for std::runtime_error
  19. namespace boost { namespace graph {
  20. /*******************************************************************
  21. * User-customized traits *
  22. *******************************************************************/
  23. /**
  24. * @brief Trait used to extract the internal vertex name from a vertex
  25. * property.
  26. *
  27. * To enable the use of internal vertex names in a graph type,
  28. * specialize the @c internal_vertex_name trait for your graph
  29. * property (e.g., @c a City class, which stores information about the
  30. * vertices in a road map).
  31. */
  32. template<typename VertexProperty>
  33. struct internal_vertex_name
  34. {
  35. /**
  36. * The @c type field provides a function object that extracts a key
  37. * from the @c VertexProperty. The function object type must have a
  38. * nested @c result_type that provides the type of the key. For
  39. * more information, see the @c KeyExtractor concept in the
  40. * Boost.MultiIndex documentation: @c type must either be @c void
  41. * (if @c VertexProperty does not have an internal vertex name) or
  42. * a model of @c KeyExtractor.
  43. */
  44. typedef void type;
  45. };
  46. #ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
  47. /**
  48. * Extract the internal vertex name from a @c property structure by
  49. * looking at its base.
  50. */
  51. template<typename Tag, typename T, typename Base>
  52. struct internal_vertex_name<property<Tag, T, Base> >
  53. : internal_vertex_name<Base> { };
  54. #endif
  55. /**
  56. * Construct an instance of @c VertexProperty directly from its
  57. * name. This function object should be used within the @c
  58. * internal_vertex_constructor trait.
  59. */
  60. template<typename VertexProperty>
  61. struct vertex_from_name
  62. {
  63. private:
  64. typedef typename internal_vertex_name<VertexProperty>::type extract_name_type;
  65. typedef typename remove_cv<
  66. typename remove_reference<
  67. typename extract_name_type::result_type>::type>::type
  68. vertex_name_type;
  69. public:
  70. typedef vertex_name_type argument_type;
  71. typedef VertexProperty result_type;
  72. VertexProperty operator()(const vertex_name_type& name)
  73. {
  74. return VertexProperty(name);
  75. }
  76. };
  77. /**
  78. * Throw an exception whenever one tries to construct a @c
  79. * VertexProperty instance from its name.
  80. */
  81. template<typename VertexProperty>
  82. struct cannot_add_vertex
  83. {
  84. private:
  85. typedef typename internal_vertex_name<VertexProperty>::type extract_name_type;
  86. typedef typename remove_cv<
  87. typename remove_reference<
  88. typename extract_name_type::result_type>::type>::type
  89. vertex_name_type;
  90. public:
  91. typedef vertex_name_type argument_type;
  92. typedef VertexProperty result_type;
  93. VertexProperty operator()(const vertex_name_type& name)
  94. {
  95. boost::throw_exception(std::runtime_error("add_vertex: "
  96. "unable to create a vertex from its name"));
  97. }
  98. };
  99. /**
  100. * @brief Trait used to construct an instance of a @c VertexProperty,
  101. * which is a class type that stores the properties associated with a
  102. * vertex in a graph, from just the name of that vertex property. This
  103. * operation is used when an operation is required to map from a
  104. * vertex name to a vertex descriptor (e.g., to add an edge outgoing
  105. * from that vertex), but no vertex by the name exists. The function
  106. * object provided by this trait will be used to add new vertices
  107. * based only on their names. Since this cannot be done for arbitrary
  108. * types, the default behavior is to throw an exception when this
  109. * routine is called, which requires that all named vertices be added
  110. * before adding any edges by name.
  111. */
  112. template<typename VertexProperty>
  113. struct internal_vertex_constructor
  114. {
  115. /**
  116. * The @c type field provides a function object that constructs a
  117. * new instance of @c VertexProperty from the name of the vertex (as
  118. * determined by @c internal_vertex_name). The function object shall
  119. * accept a vertex name and return a @c VertexProperty. Predefined
  120. * options include:
  121. *
  122. * @c vertex_from_name<VertexProperty>: construct an instance of
  123. * @c VertexProperty directly from the name.
  124. *
  125. * @c cannot_add_vertex<VertexProperty>: the default value, which
  126. * throws an @c std::runtime_error if one attempts to add a vertex
  127. * given just the name.
  128. */
  129. typedef cannot_add_vertex<VertexProperty> type;
  130. };
  131. #ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
  132. /**
  133. * Extract the internal vertex constructor from a @c property structure by
  134. * looking at its base.
  135. */
  136. template<typename Tag, typename T, typename Base>
  137. struct internal_vertex_constructor<property<Tag, T, Base> >
  138. : internal_vertex_constructor<Base> { };
  139. #endif
  140. /*******************************************************************
  141. * Named graph-specific metafunctions *
  142. *******************************************************************/
  143. namespace detail {
  144. /** @internal
  145. * Extracts the type of a bundled vertex property from a vertex
  146. * property. The primary template matches when we have hit the end
  147. * of the @c property<> list.
  148. */
  149. template<typename VertexProperty>
  150. struct extract_bundled_vertex
  151. {
  152. typedef VertexProperty type;
  153. };
  154. /** @internal
  155. * Recursively extract the bundled vertex property from a vertex
  156. * property.
  157. */
  158. template<typename Tag, typename T, typename Base>
  159. struct extract_bundled_vertex<property<Tag, T, Base> >
  160. : extract_bundled_vertex<Base>
  161. { };
  162. /**
  163. * We have found the bundled vertex property type, marked with
  164. * vertex_bundle_t.
  165. */
  166. template<typename T, typename Base>
  167. struct extract_bundled_vertex<property<vertex_bundle_t, T, Base> >
  168. {
  169. typedef T type;
  170. };
  171. /**
  172. * Translate @c no_property into @c error_property_not_found when we
  173. * have failed to extract a bundled vertex property type.
  174. */
  175. template<>
  176. struct extract_bundled_vertex<no_property>
  177. {
  178. typedef boost::detail::error_property_not_found type;
  179. };
  180. }
  181. /*******************************************************************
  182. * Named graph mixin *
  183. *******************************************************************/
  184. /**
  185. * named_graph is a mixin that provides names for the vertices of a
  186. * graph, including a mapping from names to vertices. Graph types that
  187. * may or may not be have vertex names (depending on the properties
  188. * supplied by the user) should use maybe_named_graph.
  189. *
  190. * Template parameters:
  191. *
  192. * Graph: the graph type that derives from named_graph
  193. *
  194. * Vertex: the type of a vertex descriptor in Graph. Note: we cannot
  195. * use graph_traits here, because the Graph is not yet defined.
  196. *
  197. * VertexProperty: the type stored with each vertex in the Graph.
  198. */
  199. template<typename Graph, typename Vertex, typename VertexProperty>
  200. class named_graph
  201. {
  202. public:
  203. /// The type of the function object that extracts names from vertex
  204. /// properties.
  205. typedef typename internal_vertex_name<VertexProperty>::type extract_name_type;
  206. /// The type of the "bundled" property, from which the name can be
  207. /// extracted.
  208. typedef typename detail::extract_bundled_vertex<VertexProperty>::type
  209. bundled_vertex_property_type;
  210. /// The type of the function object that generates vertex properties
  211. /// from names, for the implicit addition of vertices.
  212. typedef typename internal_vertex_constructor<VertexProperty>::type
  213. vertex_constructor_type;
  214. /// The type used to name vertices in the graph
  215. typedef typename remove_cv<
  216. typename remove_reference<
  217. typename extract_name_type::result_type>::type>::type
  218. vertex_name_type;
  219. /// The type of vertex descriptors in the graph
  220. typedef Vertex vertex_descriptor;
  221. private:
  222. /// Key extractor for use with the multi_index_container
  223. struct extract_name_from_vertex
  224. {
  225. typedef vertex_name_type result_type;
  226. extract_name_from_vertex(Graph& graph, const extract_name_type& extract)
  227. : graph(graph), extract(extract) { }
  228. const result_type& operator()(Vertex vertex) const
  229. {
  230. return extract(graph[vertex]);
  231. }
  232. Graph& graph;
  233. extract_name_type extract;
  234. };
  235. public:
  236. /// The type that maps names to vertices
  237. typedef multi_index::multi_index_container<
  238. Vertex,
  239. multi_index::indexed_by<
  240. multi_index::hashed_unique<multi_index::tag<vertex_name_t>,
  241. extract_name_from_vertex> >
  242. > named_vertices_type;
  243. /// The set of vertices, indexed by name
  244. typedef typename named_vertices_type::template index<vertex_name_t>::type
  245. vertices_by_name_type;
  246. /// Construct an instance of the named graph mixin, using the given
  247. /// function object to extract a name from the bundled property
  248. /// associated with a vertex.
  249. named_graph(const extract_name_type& extract = extract_name_type(),
  250. const vertex_constructor_type& vertex_constructor
  251. = vertex_constructor_type());
  252. /// Notify the named_graph that we have added the given vertex. The
  253. /// name of the vertex will be added to the mapping.
  254. void added_vertex(Vertex vertex);
  255. /// Notify the named_graph that we are removing the given
  256. /// vertex. The name of the vertex will be removed from the mapping.
  257. void removing_vertex(Vertex vertex);
  258. /// Notify the named_graph that we are clearing the graph.
  259. /// This will clear out all of the name->vertex mappings
  260. void clearing_graph();
  261. /// Retrieve the derived instance
  262. Graph& derived() { return static_cast<Graph&>(*this); }
  263. const Graph& derived() const { return static_cast<const Graph&>(*this); }
  264. /// Extract the name from a vertex property instance
  265. typename extract_name_type::result_type
  266. extract_name(const bundled_vertex_property_type& property);
  267. /// Search for a vertex that has the given property (based on its
  268. /// name)
  269. optional<vertex_descriptor>
  270. vertex_by_property(const bundled_vertex_property_type& property);
  271. /// Mapping from names to vertices
  272. named_vertices_type named_vertices;
  273. /// Constructs a vertex from the name of that vertex
  274. vertex_constructor_type vertex_constructor;
  275. };
  276. /// Helper macro containing the template parameters of named_graph
  277. #define BGL_NAMED_GRAPH_PARAMS \
  278. typename Graph, typename Vertex, typename VertexProperty
  279. /// Helper macro containing the named_graph<...> instantiation
  280. #define BGL_NAMED_GRAPH \
  281. named_graph<Graph, Vertex, VertexProperty>
  282. template<BGL_NAMED_GRAPH_PARAMS>
  283. BGL_NAMED_GRAPH::named_graph(const extract_name_type& extract,
  284. const vertex_constructor_type& vertex_constructor)
  285. : named_vertices(
  286. typename named_vertices_type::ctor_args_list(
  287. boost::make_tuple(
  288. boost::make_tuple(
  289. 0, // initial number of buckets
  290. extract_name_from_vertex(derived(), extract),
  291. boost::hash<vertex_name_type>(),
  292. std::equal_to<vertex_name_type>())))),
  293. vertex_constructor(vertex_constructor)
  294. {
  295. }
  296. template<BGL_NAMED_GRAPH_PARAMS>
  297. inline void BGL_NAMED_GRAPH::added_vertex(Vertex vertex)
  298. {
  299. named_vertices.insert(vertex);
  300. }
  301. template<BGL_NAMED_GRAPH_PARAMS>
  302. inline void BGL_NAMED_GRAPH::removing_vertex(Vertex vertex)
  303. {
  304. named_vertices.erase(vertex);
  305. }
  306. template<BGL_NAMED_GRAPH_PARAMS>
  307. inline void BGL_NAMED_GRAPH::clearing_graph()
  308. {
  309. named_vertices.clear();
  310. }
  311. template<BGL_NAMED_GRAPH_PARAMS>
  312. typename BGL_NAMED_GRAPH::extract_name_type::result_type
  313. BGL_NAMED_GRAPH::extract_name(const bundled_vertex_property_type& property)
  314. {
  315. return named_vertices.key_extractor().extract(property);
  316. }
  317. template<BGL_NAMED_GRAPH_PARAMS>
  318. optional<typename BGL_NAMED_GRAPH::vertex_descriptor>
  319. BGL_NAMED_GRAPH::
  320. vertex_by_property(const bundled_vertex_property_type& property)
  321. {
  322. return find_vertex(extract_name(property), *this);
  323. }
  324. /// Retrieve the vertex associated with the given name
  325. template<BGL_NAMED_GRAPH_PARAMS>
  326. optional<Vertex>
  327. find_vertex(typename BGL_NAMED_GRAPH::vertex_name_type const& name,
  328. const BGL_NAMED_GRAPH& g)
  329. {
  330. typedef typename BGL_NAMED_GRAPH::vertices_by_name_type
  331. vertices_by_name_type;
  332. // Retrieve the set of vertices indexed by name
  333. vertices_by_name_type const& vertices_by_name
  334. = g.named_vertices.template get<vertex_name_t>();
  335. /// Look for a vertex with the given name
  336. typename vertices_by_name_type::const_iterator iter
  337. = vertices_by_name.find(name);
  338. if (iter == vertices_by_name.end())
  339. return optional<Vertex>(); // vertex not found
  340. else
  341. return *iter;
  342. }
  343. /// Retrieve the vertex associated with the given name, or add a new
  344. /// vertex with that name if no such vertex is available.
  345. template<BGL_NAMED_GRAPH_PARAMS>
  346. Vertex
  347. add_vertex(typename BGL_NAMED_GRAPH::vertex_name_type const& name,
  348. BGL_NAMED_GRAPH& g)
  349. {
  350. if (optional<Vertex> vertex = find_vertex(name, g))
  351. /// We found the vertex, so return it
  352. return *vertex;
  353. else
  354. /// There is no vertex with the given name, so create one
  355. return add_vertex(g.vertex_constructor(name), g.derived());
  356. }
  357. /// Add an edge using vertex names to refer to the vertices
  358. template<BGL_NAMED_GRAPH_PARAMS>
  359. std::pair<typename graph_traits<Graph>::edge_descriptor, bool>
  360. add_edge(typename BGL_NAMED_GRAPH::vertex_name_type const& u_name,
  361. typename BGL_NAMED_GRAPH::vertex_name_type const& v_name,
  362. BGL_NAMED_GRAPH& g)
  363. {
  364. return add_edge(add_vertex(u_name, g.derived()),
  365. add_vertex(v_name, g.derived()),
  366. g.derived());
  367. }
  368. /// Add an edge using vertex descriptors or names to refer to the vertices
  369. template<BGL_NAMED_GRAPH_PARAMS>
  370. std::pair<typename graph_traits<Graph>::edge_descriptor, bool>
  371. add_edge(typename BGL_NAMED_GRAPH::vertex_descriptor const& u,
  372. typename BGL_NAMED_GRAPH::vertex_name_type const& v_name,
  373. BGL_NAMED_GRAPH& g)
  374. {
  375. return add_edge(u,
  376. add_vertex(v_name, g.derived()),
  377. g.derived());
  378. }
  379. /// Add an edge using vertex descriptors or names to refer to the vertices
  380. template<BGL_NAMED_GRAPH_PARAMS>
  381. std::pair<typename graph_traits<Graph>::edge_descriptor, bool>
  382. add_edge(typename BGL_NAMED_GRAPH::vertex_name_type const& u_name,
  383. typename BGL_NAMED_GRAPH::vertex_descriptor const& v,
  384. BGL_NAMED_GRAPH& g)
  385. {
  386. return add_edge(add_vertex(u_name, g.derived()),
  387. v,
  388. g.derived());
  389. }
  390. #undef BGL_NAMED_GRAPH
  391. #undef BGL_NAMED_GRAPH_PARAMS
  392. /*******************************************************************
  393. * Maybe named graph mixin *
  394. *******************************************************************/
  395. #ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
  396. /**
  397. * A graph mixin that can provide a mapping from names to vertices,
  398. * and use that mapping to simplify creation and manipulation of
  399. * graphs.
  400. */
  401. template<typename Graph, typename Vertex, typename VertexProperty,
  402. typename ExtractName
  403. = typename internal_vertex_name<VertexProperty>::type>
  404. struct maybe_named_graph : public named_graph<Graph, Vertex, VertexProperty>
  405. {
  406. };
  407. /**
  408. * A graph mixin that can provide a mapping from names to vertices,
  409. * and use that mapping to simplify creation and manipulation of
  410. * graphs. This partial specialization turns off this functionality
  411. * when the @c VertexProperty does not have an internal vertex name.
  412. */
  413. template<typename Graph, typename Vertex, typename VertexProperty>
  414. struct maybe_named_graph<Graph, Vertex, VertexProperty, void>
  415. {
  416. /// The type of the "bundled" property, from which the name can be
  417. /// extracted.
  418. typedef typename detail::extract_bundled_vertex<VertexProperty>::type
  419. bundled_vertex_property_type;
  420. /// Notify the named_graph that we have added the given vertex. This
  421. /// is a no-op.
  422. void added_vertex(Vertex) { }
  423. /// Notify the named_graph that we are removing the given
  424. /// vertex. This is a no-op.
  425. void removing_vertex(Vertex) { }
  426. /// Notify the named_graph that we are clearing the graph. This is a
  427. /// no-op.
  428. void clearing_graph() { }
  429. /// Search for a vertex that has the given property (based on its
  430. /// name). This always returns an empty optional<>
  431. optional<Vertex>
  432. vertex_by_property(const bundled_vertex_property_type&)
  433. {
  434. return optional<Vertex>();
  435. }
  436. };
  437. #else
  438. template<typename Graph, typename Vertex, typename VertexProperty,
  439. typename ExtractName
  440. = typename internal_vertex_name<VertexProperty>::type>
  441. struct maybe_named_graph
  442. {
  443. /// The type of the "bundled" property, from which the name can be
  444. /// extracted.
  445. typedef typename detail::extract_bundled_vertex<VertexProperty>::type
  446. bundled_vertex_property_type;
  447. /// Notify the named_graph that we have added the given vertex. This
  448. /// is a no-op.
  449. void added_vertex(Vertex) { }
  450. /// Notify the named_graph that we are removing the given
  451. /// vertex. This is a no-op.
  452. void removing_vertex(Vertex) { }
  453. /// Notify the named_graph that we are clearing the graph. This is a
  454. /// no-op.
  455. void clearing_graph() { }
  456. /// Search for a vertex that has the given property (based on its
  457. /// name). This always returns an empty optional<>
  458. template<typename Property>
  459. optional<Vertex>
  460. vertex_by_property(const bundled_vertex_property_type&)
  461. {
  462. return optional<Vertex>();
  463. }
  464. };
  465. #endif // BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
  466. } } // end namespace boost::graph
  467. #endif // BOOST_GRAPH_NAMED_GRAPH_HPP