Documentation bug: ptr_map inherits from ptr_map_adapter, not ptr_multi_map_adapter

[augustin <augustin_boost@…>]

It seems that the documentation for ptr_multi_map_adatpter is wrong as there is a discrepancy with the code. I am a beginner, so if I am wrong, please gently explain why.

http://www.boost.org/doc/libs/1_48_0/libs/ptr_container/doc/ptr_multimap_adapter.html shows:

    class ptr_multimap_adapter 
    {
        // ...
        iterator  insert( key_type& k, T* x ); 
        template< class U >
        iterator  insert( const key_type&, std::auto_ptr<U> x );  
        // ...
     }

However, the source code shows:

        std::pair<iterator,bool> insert( key_type& key, mapped_type x )
        {
            return insert_impl( key, x );
        }

        template< class U >
        std::pair<iterator,bool> insert( const key_type& key, std::auto_ptr<U> x )
        {
            return insert_impl( key, x.release() );
        }

It seems there is a mismatch between the documentation and the code as to the type of the return value (iterator vs. pair).

The following test code provides an example of what I was trying to do after reading the documentation, but obviously that didn't compile:

#include <boost/ptr_container/ptr_map.hpp>
#include <string>
#include <utility>

int main() {
        boost::ptr_map<int, std::string> map;
        boost::ptr_map<int, std::string>::iterator map_it;
        std::string* s = new std::string("one");
        int i = 1;
        //map_it = map.insert(i, s); // Does not compile.
        std::pair< boost::ptr_map<int, std::string>::iterator, bool> ret = map.insert(i, s); // This compiles.
}

How is the code documentation generated? By hand?

While learning how to use ptr_container, I have often wished there were more extensive documentation and examples on how to use ptr_map. If the above is indeed a documentation bug, can you use this opportunity to add a sample code section on how to create, insert and retrieve elements with a ptr_map?

Thanks.

[augustin <augustin_boost@…>]

Oh! I am wrong above, but the documentation is also wrong!

I confused ptr_map_adapter::insert( key_type& k, T* x ) and ptr_multimap_adapter::insert( key_type& k, T* x ) !!

ptr_map inherits from ptr_map_adapter and not ptr_multimap_adapter. However, the layout of the documentation makes it appear that it's the opposite: ptr_map is a leaf on the ptr_multimap_adapter branch: http://www.boost.org/doc/libs/1_42_0/libs/ptr_container/doc/ptr_multimap_adapter.html

Same problem with ptr_set and ptr_multi_set.

Also, still in the documentation, the 'branch' is named 'ptr_multi_map_adapter' instead of 'ptr_multimap_adapter' (notice the extra underscore, compared to the actual class name). This could be another source of confusion.

Lastly, back to my original topic, why do we have different return values for the following two functions (pair and iterator)?

std::pair<iterator,bool>  ptr_map_adapter::insert( key_type& k, T* x ) 

and

iterator ptr_multimap_adapter::insert( key_type& k, T* x ) !!