Thank you for your quick reply. I had looked at the particular page that you reference, but was confused by its contents.

I was confused by the reference documentation included with multi_index for a few reasons.

My main points of confusion came from:
Now that I understand what I am looking at a little bit better, it does look like multi_index does follow the same outline as some other boost libraries (like bimap).

That said, multi_index still looks like it has a way to go to catch up with some other libraries (Asio and Tuple, for instance), which I find much easier to use and understand.

I can see from the boost-users archive that documentation standardization has been an issue for a while (goes back to at least 2005).

I also realize that this is free software and the documentation is what it is. As a user that is used to documentation from other vendors and other styles (JavaDoc, DoxyGen, MSDN library), this documentation is severely lacking. That is a shame because I think that multi_index itself looks like a great library that should be used by as many developers as possible.


On Thu, Oct 9, 2008 at 3:50 PM, Adam Merz <> wrote:
Nick Martin writes:
> There doesn't appear to be comprehensive class reference documentation. I
> only figured out how to do simple tasks like inserting new items into the
> container by looking at the examples
> (
> My specific question (which the examples don't seem to cover) is how to tell
> when insertion fails. What if the new item's unique key constraint fails? I
> have had many other, seemingly simple questions that I would hope could be
> answered in minutes or seconds that have turned into hours of trial and error
> and combing through example programs. What other resources are out there that
> I refer to in order to use this great library?

Full reference documentation is here:

Insert behavior is documented here:

In answer to your specific question, "The return value is a pair p. p.second is
true if and only if insertion took place. On successful insertion, p.first
points to the element inserted; otherwise, p.first points to an element that
caused the insertion to be banned. Note that more than one element can be
causing insertion not to be allowed."

Boost-users mailing list