Boost Property Map Library
The Boost Property Map Library is a small library that addresses the
need to provide a generic interface for mapping between objects. Most
of the library is the interface definition, captured as a set of concepts. In addition
there are supporting category
tags and a traits class, as
well as some types that
implement the property map interface. These classes are not meant to
fulfill all mapping needs, but more to serve as an example of how to
implement the interface as well as covering a few common cases.
Property Map Concepts
The property map interface consists of a set of concepts (see
definition of "concept" in [1] and [2])
that define a general purpose mechanism for mapping key objects to
corresponding value objects, thereby hiding the details of how the
mapping is implemented from algorithms that use property maps. The
property map requirements are purposefully vague on the type of the
key and value objects to allow for the utmost flexibility. Since the
property map operations are global functions, it is possible to
overload the map functions such that nearly arbitrary property map
types and key types can be used. The interface for property maps
consists of three functions: get(), put(), and
operator[]. The following concrete example shows how the
three functions could be used to access the addresses associated with
various people.
template <class AddressMap>
void foo(AddressMap address)
{
typedef typename boost::property_traits<AddressMap>::value_type value_type;
typedef typename boost::property_traits<AddressMap>::key_type key_type;
value_type old_address, new_address;
key_type fred = "Fred";
old_address = get(address, fred);
new_address = "384 Fitzpatrick Street"
put(address, fred, new_address);
key_type joe = "Joe";
value_type& joes_address = address[joe];
joes_address = "325 Cushing Avenue";
}
For each property map object there is a set of valid keys
for which the mapping to value objects is defined. Invoking a
property map function on an invalid key results in
undefined behavior. The property map concepts do not specify how
this set of valid keys is created or modified. A function that uses a
property map must specify the expected set of valid keys in its
preconditions.
The need for property maps came out of the design of the Boost
Graph Library, whose algorithms needed an interface for accessing
properties attached to vertices and edges in a graph. In this context
the vertex and edge descriptors are the key type of the property
maps.
Several categories of property maps provide
different access capabilities:
- readable
- The associated property data can only be read.
The data is returned by-value. Many property maps defining the
problem input (such as edge weight) can be defined as readable
property maps.
- writeable
- The associated property can only be written to.
The parent array used to record the paths in a bread-first search tree
is an example of a property map that would be defined writeable.
- read/write
- The associated property can both be written and read.
The distance property use in Dijkstra's shortest paths algorithm
would need to provide both read and write capabilities.
- lvalue
- The associated property is actually represented in
memory and it is possible to get a reference to it.
The property maps in the lvalue
category also support the requirements for read/write property
maps.
There is a separate concept defined for each of the four property
map categories. These property map concepts are listed
below, with links to the documentation for each of them.
There is a tag struct for each of the categories of property
maps, which is defined in the header
<boost/property_map.hpp>.
namespace boost {
struct readable_property_map_tag { };
struct writable_property_map_tag { };
struct read_write_property_map_tag :
public readable_property_map_tag,
public writable_property_map_tag { };
struct lvalue_property_map_tag :
public read_write_property_map_tag { };
}
Similar to the std::iterator_traits class of the STL, there
is a boost::property_traits class that can be used to deduce
the types associated with a property map type: the key and value
types, and the property map category. There is a specialization
of boost::property_traits so that pointers can be used as
property map objects. In addition, the property map
functions are overloaded for pointers. These traits classes and
functions are defined in <boost/property_map.hpp>.
namespace boost {
template <class PropertyMap>
struct property_traits {
typedef typename PropertyMap::key_type key_type;
typedef typename PropertyMap::value_type value_type;
typedef typename PropertyMap::category category;
};
}
- Builtin C++ pointer types.
The following specialization of the property_traits class
and the overloads of put() and get() make it
possible to use builtin C++ pointer types as property maps. These
are defined in boost/property_map.hpp. More specifically,
it means that T* is a model of LvaluePropertyMap, given a key
type that is at least convertible std::ptrdiff_t.
namespace boost {
// specialization for using pointers as property maps
template <class T>
struct property_traits<T*> {
typedef T value_type;
typedef std::ptrdiff_t key_type;
typedef random_access_iterator_pa_tag category;
};
// overloads of the property map functions for pointers
template<>
void put(T* pmap, std::ptrdiff_t k, const T& val) { pmap[k] = val; }
template<>
const T& get(const T* pmap, std::ptrdiff_t k) { return pmap[k]; }
}
- identity_property_map
- iterator_property_map
History
The property map interface originated as data accessors in
Dietmar Kühl's Masters Thesis on generic graph algorithms. The
property map idea also appeared under the guise of decorators
in early versions of the Generic Graph Component Library (GGCL), which
is now the Boost Graph Library (BGL). The main motivation for the
property map interface was to support the access of data associated
with vertices and edges in a graph, though the applicability of
property maps goes beyond this.
Acknowledgments
Thanks go to Dietmar Kühl for coming up with this mechanism, and
thanks go to the Boost members who helped refine and improve the
property map interface. Thanks to Dave Abrahams for managing the
formal review of the BGL which included the property map library.
Notes to Implementors
Copying a property map should be inexpensive since they are often
passed by value.