Re: [boost] Re: Property_map docs

From: Jeremy Siek (jsiek_at_[hidden])
Date: 2002-11-11 00:08:38

Hi Edward,

On Sun, 10 Nov 2002, Edward Diener wrote:
eddiel> OK, here are some questions regarding the property map library;
eddiel>
eddiel> 1) What is a property map ? Is it a template class, a class, a
eddiel> template function, a function ?

It is a "concept", as the term is used in the SGI STL docs:
http://www.sgi.com/tech/stl/stl_introduction.html
It has to do with specifying the contract between generic algorithms
(function templates) and the user of such algorithms.

If you were looking for some useful concrete component to implement some
kind of mapping, then I'm afraid you will be disappointed in the property
map library.

eddiel> 2) What does the word "property" mean in the context of the name ?

Here by property we mean something that is associated with some object. I
know this is vague, but there just is not much to the property map
concept.

eddiel> 3) What is the difference between property map and std::map<> ?

std::map<> is a class. property map is a concept (well, a collection
of concepts). You can use the boost::associative_property_map
adaptor to adapt std::map<> into a type that *models* property map.

eddiel> 4) How does one use a property map ?

You write function templates with template parameters that
have property map as their requirement.

eddiel> 5) How does one create a property map of one's own ?

Create a class and then define get(), put() and operator[]
function for the class.

eddiel> 6) What are the prototypes for the get(), put(), and operator[]
eddiel> functions, and are these really global functions as the doc
eddiel> suggests or are they functions in the boost namespace ?

They can live anywhere that argument dependent lookup can find them, which
means just about anywhere.

eddiel> 7) What do the various categories actually do for property maps ?

Like the iterator tags in the C++ std, they allow function templates to
dispatch to different code depending on the category of the property map.

eddiel> I do not believe that any of these questions are answered clearly
eddiel> in the property map documentation although they are all basic
eddiel> points which should be explained to the end user. I know there is
eddiel> a concept there of mapping keys to values but beyond that the
eddiel> documentation seems abstruse at best and needlessly irritating at
eddiel> worst.
eddiel>
eddiel> Please Boosters <g>, think about explaining your ideas to the
eddiel> programming world in ways that they understand and can use, rather
eddiel> than in metaprogramming terminology which only a select few know.
eddiel> Good documentation is as important, in its own way, as good code.

I've taken another look at the docs, and I'm afraid I do not see a lot of
room for improvement. The docs say pretty much what I said above, and
include links to resources where one can learn more about generic
programming.

The property map library is by nature abstract. The main point of the
library is not to provide concrete classes, but instead to describe a
whole family of classes so that they can be used interchangeably in
function templates (generic algorithms).

The property map library is for generic programming, and is described
using the terminology of generic programming. If you aren't doing generic
programming, then you don't need the property map library.

Regards,
Jeremy

----------------------------------------------------------------------
 Jeremy Siek                          http://php.indiana.edu/~jsiek/
 Ph.D. Student, Indiana Univ. B'ton   email: jsiek_at_[hidden]
 C++ Booster (http://www.boost.org)   office phone: [phone]
----------------------------------------------------------------------