Re: [boost] [Bimap] Review

From: Fernando Cacciola (fernando_cacciola_at_[hidden])
Date: 2007-03-05 10:30:27

Matias Capeletto wrote:
> On 2/23/07, Fernando Cacciola <fernando_cacciola_at_[hidden]> wrote:
>> Hello Matias,
>>
>> 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.
>
OK.
Focus on what exactly "signture compatible" means.
That's actually one of those terms that convey an idea concisely, but 
diffusedly at the same time.

One interprets that each and every member function has the same signature, 
but then wonders, is exactly like that?
I would make that clear.

>> 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.

Great

> 2) I am not sure about the two colored arrows.

I was thinking that the legends for the left/right maps were colored 
accordingly.

> 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.
>
Fine with me. But notice that you have a strong idea that this view is 
"above" (judging from other posts)
That's actually artificial. Is not as natural as the left/right view 
(because then Venn's are physically left/right).
It's OK to present it like that if you wish, but keep in mind that is an 
artificial POV that you just have choosen.

>> 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"?
>
The problem is that the concept of a "standard mapping framework" isn't 
sufficiently standard, so you can't just speak of it as if it where an 
implicitely defined term.

So, I would phrase it like that, but also, and before, I would spend a 
page-or a couple of paragraphs-formally presenting "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?
>
Somewhat, yes.
I think you don't need the qualification at all, you can just address your 
framework directly.

>
>> 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?
>
Becasue there nothing *directly* being first or second in a map.
Except the pair type that is used in some of its member functions.

ALso, what does it adds to the understanding of what you are trying to show?

>> 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"
>
And in such a "standard framework" there isn't any explicit "set type".
OTOH,  it's a good idea to think of it that way, but then you need to 
present it that way in the docs before this picture is shown.

>> 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.
>
Then say so.

>
> 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.
>
Btw, you can do so dynamically (that is, over an already constructed and 
filled bimap), or do you mean that you can define another bimap type that 
uses a different collection type?
I couldn't tell that from the minitutorial.

Well, the review period is over and I haven't got the time to go over the 
rest of it...

I will anyway try to get involved in the ongoing discussions though.

Best

Fernando