Re: [boost] [Bimap] Review

From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-02-25 00:05:07

On 2/23/07, Fernando Cacciola <fernando_cacciola_at_[hidden]> wrote:
> Hello Matias,
>
> Here's a partial review, focused on the first things I observed so far.
> 1.
> The very first thing I see is a nice bold question: "What is a bimap?"
> However, everything that follows doesn't feel like a good answer. Is more
> like the explanation of the missing answer.
> For such a concrete question I would expect a concrete answer like: "A Bimap
> is a data structure that represents bidirectional relations between elements
> of two collections", or something like that.

Reading it again, I was left with your same feeling. I will answer
that question. :)

> Furthermore, at this introductory point in the tutorial, the very first
> mention of "bm.left" should IMHO be closely followed by its definition, yet
> the statement "is signature compatible with std::map<A,B>" is a bit
> simplistic at that.
> The same goes for bm.right and 'bm' itself.

It has to be simple because it is a one minute tutorial, but I think
it can be good to expend a paragraph at this point.

> 2.
> The next thing one sees is the nice diagram. It's so nice that it sticks and
> weights in the understanding of the nature of a bimap. Even if one reads
> through the text, the picture drives the understanding. At least that's how
> it works in my head.
> However, it's a bit misleading, and I finally figured what, IMHO, is wrong
> with this picture :) Bare with me...
> ...
> In the end, there are three ballons all intersecting at the region
> containing the Veen diagrams, expressing the fact
> that a bimap<> offers three views over the same thing.

Here it is a link to your modified version:
http://matias.capeletto.googlepages.com/simple.bimap.2.png

1) I like the new big balloons, you were right about that.
2) I am not sure about the two colored arrows.
3) I do not like the fact that the label for the "above" view is now
at the "bottom" of the picture, but as you said now you look at the
sides first. Maybe we can leave it above but make it smaller and
achieve the same effect.

> 4.The following is from the second tutorial page (headed "The Tutorial")
>
> 4.a.It says:
>
> "New concepts are however presented to extend the mapping framework to
> bidirectional maps"
>
> That is confusing because at that point of the reading, there is no such
> thing as "a mapping framework". I would say "the std map class" instead.

Will it be OK to replace it for "to extend the standard mapping framework"?

> 4.b.
>
> The expression "new framework" is also confusing.
> A "new" something must relate to an "old" soemthing, and boost::bimap, IMO,
> should NOT be seen as something "new" while std::map as something old.
> I would say "the Bimap framework" instead (this applies to many other pages
> in the docs)

Do you think that the word "new" will make people believe that this
framework will replace the standard one?

> 4.d.
>
> Here's the first time the expression "set type" is used.
> This expression is used all over the documentation but there is problem: the
> term "set" is not defined so one is forced to imagine its definition. Is it
> an STL set? Is it a mathematical set? Does it have special requirements?
>
> Granted, one eventually realizes you meant a mathematical set instead of an
> STL set, but even then, Bimap is purposedly designed to relax all such
> requirements, even uniqueness, so I think a better word for this concept is
> "collection".
>
> The reason is that you can actually use a vector for this type, which can
> hardly be considered as representing a mathematical set (because it doesn't
> guarantee uniqueness).

I used collection at some point and then change it to "set". I can not
recall the reason for this switch right now. It may be better to roll
back this decision.

> 5.
> Here's an analysis of the "standard mapping framework" picture (following
> the same ideas as before);
>
> 5.a.The ballow should enclose both Venn diagrams since a map contains both
> elements.

Ok.

> 5.b.The words "first/second" on top of std::map are confusing IMO. I would
> remove them.

Why do you think they are confusing?

> 5.c.In a std::map there is no explicit "set type" for the collection of
> keys, so at this point the label to it is confusing. I would removed it.

But the picture is not about std::map, it is about the standard
mapping framework that includes std::multimap, std::unordered_map,
etc...
The label std::map could be replaced for "standard map"

> 6.
> After the picture you read "this is not wrong.".
> What isn't?

The framework.
But the phrase can be better. I wanted to say that in many use cases,
when you only need to see the mapping from the left side, it is better
to use the standard maps.

As a side note you can use a unconstrained_set_of
typedef bimap<A,unconstrained_set_of<B>> bimap_type.
to achieve almost the same performance of the standard map, and if
later you need to look from the right side, you can change the
typedef.

> 7.
> In the introduction of the standard mapping framework, the idea of a map
> seen as an overlay of two "set types" is presented, but unfortunately quite
> superficially.
> This way of looking at it great, but is also a bit novel since the "standard
> framework" doesn't speak of left and right sets at all.
> Thus, besides what I mentioned before about replacing "set" by "collection",
> I think you should add an entire page explicitely presenting the idea, at a
> conceptual level, that a map is the overlay of two collections. Much before
> the standard mapping framework is introduced.

Yes, I will do it. This concept must be clear from the beginning.

> That's all for now.. but there's more.

Thanks a lot!
Best regards
Matias