[API] Add convenience headers for property maps

Open
#471 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
50/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
cpp
Domain
backend-api-design

Research direction

Start by reading boost/graph/properties.hpp and the listed boost/property_map and boost/graph/property_maps headers to map the existing includes and namespaces. Confirm the intended convenience-header scope and namespace behavior; done should provide a single documented include for the property-map types without requiring users to know the split between libraries.

Written by the indexing model from the issue text.

Description

beginner friendly

Problem

As I am rewriting the documentation for the property map system, I find the current way to navigate headers rather complex:

Header Contents
<boost/graph/properties.hpp> Internal property tags (vertex_index, edge_weight, ...), get(tag, g)
<boost/property_map/property_map.hpp> iterator_property_map, static_property_map, associative_property_map, dummy_property_map
<boost/property_map/vector_property_map.hpp> vector_property_map
<boost/property_map/function_property_map.hpp> make_function_property_map
<boost/property_map/transform_value_property_map.hpp> make_transform_value_property_map
<boost/graph/property_maps/constant_property_map.hpp> constant_property_map, make_constant_property
<boost/graph/property_maps/null_property_map.hpp> null_property_map, make_null_property

Property map types are split across two libraries: boost/graph/ (internal properties, constant/null maps) and boost/property_map/ (the generic adaptors). This split is an implementation detail users should not have to think about.

Solution

I am thinking about a convenience header that pulls those in an uniformize the namespaces. That would reduce the friction for newcomers, and we can leave this previous table in the documentation if more experimented users want to trim dependencies ?

#include <boost/graph/properties.hpp>   // 374 lines pulls the PM library and its BGL extensions
   //   boost/property_map/property_map.hpp (iterator_, static_, assoc_, dummy_)
   //   boost/graph/property_maps/constant_property_map.hpp
   //   boost/graph/property_maps/null_property_map.hpp
#include <boost/property_map/vector_property_map.hpp>  // 96 lines
#include <boost/property_map/function_property_map.hpp>  // 66 lines
#include <boost/property_map/transform_value_property_map.hpp>  // 67 lines

If I understood correctly, all of the underlying types live in the boost:: namespace so we are good namespace-wise.

Dominant language
C++
Stars
395
Forks
239
Avg merge
18h 50m
Merged PRs (30d)
20

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from boostorg/graph

All issues in boostorg/graph

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.