[Boost-users] unordered_map documentation (was RE: Correct use of unordered_map)

Subject: [Boost-users] unordered_map documentation (was RE: Correct use of unordered_map)
From: John Dlugosz (JDlugosz_at_[hidden])
Date: 2009-09-03 11:30:38

> Sort of, but you're missing the important point that a range (the STL
> jargon for what you call set, 

I thought the STL was going to be adopting the "range" concepts from the STL range library.  That is, a range will be a begin-end iterator pair or something that behaves like that.

> ...but remember that insert can invalidate
> iterators

OK, I missed that.

> I'm the person for the boost documentation. But you should remember
> that all this documentation assumes familiarity with the STL concepts
> - which most of what you're talking about comes from. Looking at the
> documentation it probably could do with a bit more of a discussion of
> what it means to be 'unordered' but I don't think it's the correct
> place to document how iterators work - it should be enough to say
> they're forward iterators and perhaps link to an explanation of what a
> forward iterator is.
> 
> Daniel

Reading it through from the beginning...
"An unordered associative container that associates unique keys with another value."

Key has equivalence relation (only).

member begin returns "An iterator referring to the first element of the container"

"first" contradicts "unordered".  There is no meaning for first.

The iterator has a difference type.  It doesn't say what kind of iterator it is, but I assume forward_iterator as the broadest, since input_iterator and output_iterator would not be applicable.

So, do elements have a definite and unchanging order in the container, or can different iterations produce different orders?  The latter gives maximum freedom to the implementation, but is more difficult to define properly.  If the former, just saying that would fix the issues I have with the current definitions.

(BTW, the HREF to n2691 is dead)

To suggest a concrete example, you might insert, "Although no relation is supplied for the key type, for purposes of iteration the elements will appear to have a definite order that is determined by the implementation.  This order may be changed by any function that invalidates iterators, including insert and rehash."

That certainly describes the Boost class.  But should the C++ standard have more freedom?  The draft standard I've seen does include the bucket exposing functions, so maybe it is locked into this one implementation.

TradeStation Group, Inc. is a publicly-traded holding company (NASDAQ GS: TRAD) of three operating subsidiaries, TradeStation Securities, Inc. (Member NYSE, FINRA, SIPC and NFA), TradeStation Technologies, Inc., a trading software and subscription company, and TradeStation Europe Limited, a United Kingdom, FSA-authorized introducing brokerage firm. None of these companies provides trading or investment advice, recommendations or endorsements of any kind. The information transmitted is intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited. If you received this in error, please contact the sender and delete the material from any computer.