1 2++++++++++++++++++++++++++++++++++ 3 |Boost| Pointer Container Library 4++++++++++++++++++++++++++++++++++ 5 6.. |Boost| image:: boost.png 7 8 9 10:Authors: Thorsten Ottosen 11:Contact: nesotto@cs.aau.dk or tottosen@dezide.com 12:Organizations: `Department of Computer Science`_, Aalborg University, and `Dezide Aps`_ 13:date: 27th of October 2007 14:Copyright: Thorsten Ottosen 2004-2007. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). 15 16__ http://www.boost.org/LICENSE_1_0.txt 17 18.. _`Department of Computer Science`: http://www.cs.aau.dk 19.. _`Dezide Aps`: http://www.dezide.com 20 21======== 22Overview 23======== 24 25Boost.Pointer Container provides containers for holding heap-allocated 26objects in an exception-safe manner and with minimal overhead. 27The aim of the library is in particular to make OO programming 28easier in C++ by establishing a standard set of classes, methods 29and designs for dealing with OO specific problems 30 31* Motivation_ 32* Tutorial_ 33* Reference_ 34* `Usage guidelines`_ 35* Examples_ 36* `Library headers`_ 37* FAQ_ 38* `Upgrading from Boost v. 1.33.*`_ 39* `Upgrading from Boost v. 1.34.*`_ 40* `Upgrading from Boost v. 1.35.*`_ 41* `Upgrading from Boost v. 1.66.*`_ 42* `Future Developments`_ 43* Acknowledgements_ 44* References_ 45 46.. 47 - `Conventions <conventions.html>`_ 48 - `The Clonable Concept <reference.html#the-clonable-concept>`_ 49 - `The Clone Allocator Concept <reference.html#the-clone-allocator-concept>`_ 50 - `Pointer container adapters <reference.html#pointer-container-adapters>`_ 51 - `Sequence container classes <reference.html#sequence-containers>`_ 52 53 - `ptr_vector <ptr_vector.html>`_ 54 - `ptr_deque <ptr_deque.html>`_ 55 - `ptr_list <ptr_list.html>`_ 56 - `ptr_array <ptr_array.html>`_ 57 - `Associative container classes <reference.html#associative-containers>`_ 58 59 - `ptr_set <ptr_set.html>`_ 60 - `ptr_multiset <ptr_multiset.html>`_ 61 - `ptr_map <ptr_map.html>`_ 62 - `ptr_multimap <ptr_multimap.html>`_ 63 - `Indirected functions <indirect_fun.html>`_ 64 - `Class nullable <reference.html#class-nullable>`_ 65 - `Exception classes <reference.html#exception-classes>`_ 66 67 68 69.. _Tutorial: tutorial.html 70 71 72.. _Reference: reference.html 73 74.. _`Usage guidelines`: guidelines.html 75 76.. _Examples: examples.html 77 78.. _`Library headers`: headers.html 79 80.. _FAQ: faq.html 81 82 83========== 84Motivation 85========== 86 87Whenever a programmer wants to have a container of pointers to 88heap-allocated objects, there is usually only one exception-safe way: 89to make a container of smart pointers like `boost::shared_ptr <../../smart_ptr/shared_ptr.htm>`_ 90This approach is suboptimal if 91 921. the stored objects are not shared, but owned exclusively, or 93 94.. 95 962. the overhead implied by smart pointers is inappropriate 97 98This library therefore provides standard-like containers that are for storing 99heap-allocated or `cloned <reference.html#the-clonable-concept>`_ objects (or in case of a map, the mapped object must be 100a heap-allocated or cloned object). For each of the standard 101containers there is a pointer container equivalent that takes ownership of 102the objects in an exception safe manner. In this respect the library is intended 103to solve the so-called 104`polymorphic class problem <faq.html#what-is-the-polymorphic-class-problem>`_. 105 106 107The advantages of pointer containers are 108 1091. Exception-safe pointer storage and manipulation. 110 111.. 112 1132. Notational convenience compared to the use of containers of pointers. 114 115.. 116 1173. Can be used for types that are neither Assignable nor Copy Constructible. 118 119.. 120 1214. No memory-overhead as containers of smart pointers can have (see [11]_ and [12]_). 122 123.. 124 1255. Usually faster than using containers of smart pointers (see [11]_ and [12]_). 126 127.. 128 1296. The interface is slightly changed towards the domain of pointers 130 instead of relying on the normal value-based interface. For example, 131 now it is possible for ``pop_back()`` to return the removed element. 132 133.. 134 1357. Propagates constness such that one cannot modify the objects via a ``const_iterator``. 136 137.. 138 1398. Built-in support for deep-copy semantics via the `the Clonable concept`__ 140 141.. __: reference.html#the-clonable-concept 142 143The disadvantages are 144 1451. Less flexible than containers of smart pointers like `boost::shared_ptr <../../smart_ptr/shared_ptr.htm>`_ 146 147When you do need shared semantics, this library is not what you need. 148 149==================================== 150 Upgrading from Boost v. ``1.33.*`` 151==================================== 152 153If you upgrade from one of these versions of Boost, then there has been one 154major interface change: map iterators now mimic iterators from ``std::map``. 155Previously you may have written :: 156 157 for( boost::ptr_map<std::string,T>::iterator i = m.begin(), e = m.end(); 158 i != e; ++i ) 159 { 160 std::cout << "key:" << i.key(); 161 std::cout << "value:" << *i; 162 i->foo(); // call T::foo() 163 } 164 165and this now needs to be converted into :: 166 167 for( boost::ptr_map<std::string,T>::iterator i = m.begin(), e = m.end(); 168 i != e; ++i ) 169 { 170 std::cout << "key:" << i->first; 171 std::cout << "value:" << *i->second; 172 i->second->foo(); // call T::foo() 173 } 174 175Apart from the above change, the library now also introduces 176 177- ``std::auto_ptr<T>`` overloads:: 178 179 std::auto_ptr<T> p( new T ); 180 container.push_back( p ); 181 182- Derived-to-Base conversion in ``transfer()``:: 183 184 boost::ptr_vector<Base> vec; 185 boost::ptr_list<Derived> list; 186 ... 187 vec.transfer( vec.begin(), list ); // now ok 188 189Also note that `Boost.Assign <../../assign/index.html>`_ introduces better support 190for pointer containers. 191 192==================================== 193 Upgrading from Boost v. ``1.34.*`` 194==================================== 195 196Serialization has now been made optional thanks to Sebastian Ramacher. 197You simply include ``<boost/ptr_container/serialize.hpp>`` or perhaps 198just one of the more specialized headers. 199 200All containers are now copy-constructible and assignable. So you can e.g. now 201do:: 202 203 boost::ptr_vector<Derived> derived = ...; 204 boost::ptr_vector<Base> base( derived ); 205 base = derived; 206 207As the example shows, derived-to-base class conversions are also allowed. 208 209A few general functions have been added:: 210 211 VoidPtrContainer& base(); 212 const VoidPtrContainer& base() const; 213 214These allow direct access to the wrapped container which is 215sometimes needed when you want to provide extra functionality. 216 217A few new functions have been added to sequences:: 218 219 void resize( size_type size ); 220 void resize( size_type size, T* to_clone ); 221 222``ptr_vector<T>`` has a few new helper functions to integrate better with C-arrays:: 223 224 void transfer( iterator before, T** from, size_type size, bool delete_from = true ); 225 T** c_array(); 226 227Finally, you can now also "copy" and "assign" an ``auto_type`` ptr by calling ``move()``:: 228 229 boost::ptr_vector<T>::auto_type move_ptr = ...; 230 return boost::ptr_container::move( move_ptr ); 231 232==================================== 233 Upgrading from Boost v. ``1.35.*`` 234==================================== 235 236The library has been fairly stable, but a few new containers have been supported: 237 238- ``boost::ptr_unordered_set<T>`` in ``<boost/ptr_container/ptr_unordered_set.hpp>`` 239 240- ``boost::ptr_unordered_map<Key,T>`` in ``<boost/ptr_container/ptr_unordered_map.hpp>`` 241 242- ``boost::ptr_circular_buffer<T>`` in ``<boost/ptr_container/ptr_circular_buffer.hpp>`` 243 244There are no docs for these classes yet, but they are almost identical to 245``boost::ptr_set<T>``, ``boost::ptr_map<Key,T>`` and ``boost::ptr_array<T,N>``, respectively. 246The underlying containers stem from the two boost libraries 247 248- `Boost.Unordered <../../unordered/index.html>`_ 249 250- `Boost.Circular Buffer <../../circular_buffer/index.html>`_ 251 252Furthermore, `insert iterators <ptr_inserter.html>`_ have been added. 253 254 255 256=================================== 257Upgrading from Boost v. ``1.66.*`` 258=================================== 259 260Starting with Boost v. ``1.67.0``, Boost.Pointer Container will use 261`Boost.Config <../../config/index.html>`_ to conditionally provide 262``std::unique_ptr``-based interfaces in addition to, or instead of, 263interfaces using ``std::auto_ptr``. Details 264are on the `Compatible Smart Pointer <compatible_smart_ptr.html>`_ 265page, which also explains the convention in this documentation of using 266 267.. parsed-literal:: 268 *compatible-smart-ptr*\ <T> 269 270to indicate such conditional interfaces. 271 272For C++98/03 users, this change has no observable effect. 273 274For C++11/14 users, there is no effect on existing code that used 275previous versions of Boost.Pointer Container, but now all function 276overloads taking an ``std::auto_ptr`` parameter are accompanied by an 277overload taking ``std::unique_ptr``. In the case of return types, 278``std::auto_ptr`` is still always used. Note however that until C++17, 279it is possible to construct ``std::unique_ptr<T>`` implicitly from 280``std::auto_ptr<T>``. Thus, users are free to modernize their code by 281replacing any explicit mention of ``std::auto_ptr`` with 282``std::unique_ptr``. This change falls just short of a 283search-and-replace conversion, as it is possible that some code may 284have relied on ``std::auto_ptr`` being copyable. But such situations 285will result in compile-time errors which should be easy to fix. 286 287Although ``std::auto_ptr`` is formally removed as of ISO C++17, 288certain compiler or standard library vendors have chosen to leave it 289in for backwards compatibility. For compilers and standard libraries 290where this is *not* the case, C++17 compilation of code using 291Boost.Pointer Container is not possible with Boost v. ``1.66.*`` or 292earlier. This situation is fixed as of Boost v. ``1.67.0``. 293 294===================== 295 Future Developments 296===================== 297 298There are indications that the ``void*`` implementation has a slight 299performance overhead compared to a ``T*`` based implementation. Furthermore, a 300``T*`` based implementation is so much easier to use type-safely 301with algorithms. Therefore I anticipate to move to a ``T*`` based implementation. 302 303Furthermore, the clone allocator might be allowed to have state. 304This design requires some thought, so if you have good ideas and use-cases' 305for this, please don't hesitate to contact me. 306 307Also, support for Boost.Interprocess is on the todo list. 308 309There has been a few request for ``boost::ptr_multi_index_container<T,...>``. 310I investigated how difficult it would be, and it did turn out to be difficult, albeit 311not impossible. But I don't have the resources to implement this beast 312for years to come, so if someone really needs this container, I suggest that they 313talk with me in private about how it can be done. 314 315================ 316Acknowledgements 317================ 318 319The following people have been very helpful: 320 321- Bj�rn D. Rasmussen for unintentionally motivating me to start this library 322- Pavel Vozenilek for asking me to make the adapters 323- David Abrahams for the ``indirect_fun`` design 324- Pavol Droba for being review manager 325- Ross Boylan for trying out a prototype for real 326- Felipe Magno de Almeida for giving fedback based on using the 327 library in production code even before the library was part of boost 328- Jonathan Turkanis for supplying his ``move_ptr`` framework 329 which is used internally 330- Stefan Slapeta and Howard Hinnant for Metrowerks support 331- Russell Hind for help with Borland compatibility 332- Jonathan Wakely for his great help with GCC compatibility and bug fixes 333- Pavel Chikulaev for comments and bug-fixes 334- Andreas Hommel for fixing the nasty Metrowerks bug 335- Charles Brockman for his many comments on the documentation 336- Sebastian Ramacher for implementing the optional serialization support 337 338========== 339References 340========== 341 342.. [1] Matt Austern: `"The Standard Librarian: Containers of Pointers"`__ , C/C++ Users Journal Experts Forum. 343 344__ http://www.cuj.com/documents/s=7990/cujcexp1910austern/ 345 346.. [2] Bjarne Stroustrup, "The C++ Programming Language", `Appendix E: "Standard-Library Exception Safety"`__ 347 348__ http://www.research.att.com/~bs/3rd_safe.pdf 349 350.. [3] Herb Sutter, "Exceptional C++". 351.. [4] Herb Sutter, "More Exceptional C++". 352.. [5] Kevlin Henney: `"From Mechanism to Method: The Safe Stacking of Cats"`__ , C++ Experts Forum, February 2002. 353 354__ http://www.cuj.com/documents/s=7986/cujcexp2002henney/henney.htm 355 356.. [6] Some of the few earlier attempts of pointer containers I have seen are the rather interesting NTL_ and the 357 pointainer_. 358 As of this writing both libraries are not exceptions-safe and can leak. 359 360.. [7] INTERNATIONAL STANDARD, Programming languages --- C++, ISO/IEC 14882, 1998. See section 23 in particular. 361.. [8] C++ Standard Library Closed Issues List (Revision 27), 362 Item 218, `Algorithms do not use binary predicate objects for default comparisons`__. 363 364__ http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-closed.html#218 365 366.. [9] C++ Standard Library Active Issues List (Revision 27), 367 Item 226, `User supplied specializations or overloads of namespace std function templates`__. 368 369__ http://gcc.gnu.org/onlinedocs/libstdc++/ext/lwg-active.html#226 370 371.. [10] Harald Nowak, "A remove_if for vector", C/C++ Users Journal, July 2001. 372.. [11] Boost smart pointer timings__ 373 374__ http://www.boost.org/libs/smart_ptr/smarttests.htm 375 376.. [12] NTL_: Array vs std::vector and boost::shared_ptr 377.. [13] Kevlin Henney, `Null Object`__, 2002. 378 379__ http://www.two-sdg.demon.co.uk/curbralan/papers/europlop/NullObject.pdf 380 381.. _NTL: http://www.ntllib.org/asp.html 382.. _pointainer: http://ootips.org/yonat/4dev/pointainer.h 383 384 385.. raw:: html 386 387 <hr> 388 389:Copyright: Thorsten Ottosen 2004-2006. 390 391
