https://svn.boost.org/trac10/ticket/6437 <p> 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. </p> <p> <a href="http://www.boost.org/doc/libs/1_48_0/libs/ptr_container/doc/ptr_multimap_adapter.html">http://www.boost.org/doc/libs/1_48_0/libs/ptr_container/doc/ptr_multimap_adapter.html</a> shows: </p> <pre class="wiki"> class ptr_multimap_adapter { // ... iterator insert( key_type&amp; k, T* x ); template&lt; class U &gt; iterator insert( const key_type&amp;, std::auto_ptr&lt;U&gt; x ); // ... } </pre><p> However, the source code shows: </p> <pre class="wiki"> std::pair&lt;iterator,bool&gt; insert( key_type&amp; key, mapped_type x ) { return insert_impl( key, x ); } template&lt; class U &gt; std::pair&lt;iterator,bool&gt; insert( const key_type&amp; key, std::auto_ptr&lt;U&gt; x ) { return insert_impl( key, x.release() ); } </pre><p> It seems there is a mismatch between the documentation and the code as to the type of the return value (iterator vs. pair). </p> <p> The following test code provides an example of what I was trying to do after reading the documentation, but obviously that didn't compile: </p> <pre class="wiki">#include &lt;boost/ptr_container/ptr_map.hpp&gt; #include &lt;string&gt; #include &lt;utility&gt; int main() { boost::ptr_map&lt;int, std::string&gt; map; boost::ptr_map&lt;int, std::string&gt;::iterator map_it; std::string* s = new std::string("one"); int i = 1; //map_it = map.insert(i, s); // Does not compile. std::pair&lt; boost::ptr_map&lt;int, std::string&gt;::iterator, bool&gt; ret = map.insert(i, s); // This compiles. } </pre><p> How is the code documentation generated? By hand? </p> <p> 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? </p> <p> Thanks. </p> en-us /htdocs/site/boost.png https://svn.boost.org/trac10/ticket/6437 Trac 1.4.3 augustin <augustin_boost@…> Mon, 23 Jan 2012 13:03:57 GMT https://svn.boost.org/trac10/ticket/6437#comment:1 https://svn.boost.org/trac10/ticket/6437#comment:1 <ul> <li><strong>summary</strong> <span class="trac-field-old">Documentation bug about ptr_multi_map_adapter::insert(...) return value</span> → <span class="trac-field-new">Documentation bug: ptr_map inherits from ptr_map_adapter, not ptr_multi_map_adapter</span> </li> </ul> <p> Oh! I am wrong above, but the documentation is also wrong! </p> <p> I confused ptr_map_adapter::insert( key_type&amp; k, T* x ) and ptr_multimap_adapter::insert( key_type&amp; k, T* x ) !! </p> <p> 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: <a href="http://www.boost.org/doc/libs/1_42_0/libs/ptr_container/doc/ptr_multimap_adapter.html">http://www.boost.org/doc/libs/1_42_0/libs/ptr_container/doc/ptr_multimap_adapter.html</a> </p> <p> Same problem with ptr_set and ptr_multi_set. </p> <p> 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. </p> <p> Lastly, back to my original topic, why do we have different return values for the following two functions (pair and iterator)? </p> <pre class="wiki">std::pair&lt;iterator,bool&gt; ptr_map_adapter::insert( key_type&amp; k, T* x ) </pre><p> and </p> <pre class="wiki"> iterator ptr_multimap_adapter::insert( key_type&amp; k, T* x ) !! </pre> Ticket