]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ++++++++++++++++++++++++++++++++++ |
2 | |Boost| Pointer Container Library | |
3 | ++++++++++++++++++++++++++++++++++ | |
4 | ||
5 | .. |Boost| image:: boost.png | |
6 | ||
7 | Conventions | |
8 | +++++++++++ | |
9 | ||
10 | There are a few design decisions that will affect how the classes are | |
11 | used. Besides these the classes are much like normal standard containers | |
12 | and provides almost the same interface. The new conventions are: | |
13 | ||
14 | .. contents:: :local: | |
15 | ||
16 | Null pointers are not allowed by default | |
17 | ---------------------------------------- | |
18 | ||
19 | If the user tries to insert the null pointer, the operation will throw a | |
20 | ``bad_pointer`` exception (see `Example 1 <examples.html>`_). | |
21 | ||
22 | Use `nullable <reference.html#class-nullable>`_ to allow null pointers. | |
23 | ||
24 | Please notice that all preconditions of the form :: | |
25 | ||
26 | x != 0; | |
27 | ||
28 | are not active when the you have instantiated a container | |
29 | with ``nullable<T>`` as in :: | |
30 | ||
31 | boost::ptr_vector< boost::nullable<animal> > vec; | |
32 | vec.push_back( 0 ); // ok | |
33 | ||
34 | All default iterators apply an extra layer of indirection | |
35 | --------------------------------------------------------- | |
36 | ||
37 | This is done to | |
38 | make the containers easier and safer to use. It promotes a kind of | |
39 | pointer-less programming and the user of a class needs not worry about | |
40 | pointers except when allocating them (see `Example 2 <examples.html>`_). Iterators that | |
41 | provide access to the naked pointers are also provided since they might be | |
42 | useful in rare cases. For example, whenever ``begin()`` returns an iterator, | |
43 | ``ptr_begin()`` will return an iterator that allows one to iterate over the | |
44 | stored pointers. | |
45 | ||
46 | All comparison operations are done on the pointed to objects and not at the pointer level | |
47 | ----------------------------------------------------------------------------------------- | |
48 | ||
49 | For example, in ``ptr_set<T>`` the ordering is by default done by | |
50 | ``boost::ptr_less<T>`` which compares the indirected pointers. | |
51 | Similarly, ``operator==()`` for ``container<Foo>`` compares all objects | |
52 | with ``operator==(const Foo&, const Foo&)``. | |
53 | ||
54 | ||
55 | Stored elements are required to be `Cloneable <reference.html#the-Cloneable-concept>`_ for a subset of the operations | |
56 | --------------------------------------------------------------------------------------------------------------------- | |
57 | ||
58 | This is because most polymorphic objects cannot be copied directly, but | |
59 | they can often be so by a use of a member function (see `Example 4 <examples.html>`_). Often | |
60 | it does not even make sense to clone an object in which case a large | |
61 | subset of the operations are still workable. | |
62 | ||
63 | Whenever objects are inserted into a container, they are cloned before insertion | |
64 | -------------------------------------------------------------------------------- | |
65 | ||
66 | This is necessary because all pointer containers take ownerships of stored objects | |
67 | (see `Example 5 <examples.html>`_). | |
68 | ||
69 | Whenever pointers are inserted into a container, ownership is transferred to the container | |
70 | ------------------------------------------------------------------------------------------ | |
71 | ||
72 | All containers take ownership of the stored pointers and therefore a | |
73 | container needs to have its own copies (see `Example 5 <examples.html>`_). | |
74 | ||
75 | Ownership can be transferred from a container on a per pointer basis | |
76 | -------------------------------------------------------------------- | |
77 | ||
78 | This can of course also be convenient. Whenever it happens, an | |
79 | ``SmartContainer::auto_type`` object is used to provide an exception-safe transfer | |
80 | (see `Example 6 <examples.html>`_). | |
81 | ||
82 | Ownership can be transferred from a container to another container on a per iterator range basis | |
83 | ------------------------------------------------------------------------------------------------ | |
84 | ||
85 | This makes it possible to exchange data safely between different pointer | |
86 | containers without cloning the objects again (see `Example 7 <examples.html>`_). | |
87 | ||
88 | A container can be cheaply returned from functions either by making a clone or by giving up ownership of the container | |
89 | ---------------------------------------------------------------------------------------------------------------------- | |
90 | ||
91 | Two special member functions, ``clone()`` and ``release()``, both return an | |
92 | ``auto_ptr<SmartContainer>`` which can be assigned to another pointer container. This | |
93 | effectively reduces the cost of returning a container to one | |
94 | heap-allocation plus a call to ``swap()`` (see `Example 3 <examples.html>`_). | |
95 | ||
96 | Iterators are invalidated as in the corresponding standard container | |
97 | -------------------------------------------------------------------- | |
98 | ||
99 | Because the containers in this library wrap standard containers, the | |
100 | rules for invalidation of iterators are the same as the rules | |
101 | of the corresponding standard container. | |
102 | ||
103 | For example, for both ``boost::ptr_vector<T>`` and ``std::vector<U>`` | |
104 | insertion and deletion only invalidates the deleted | |
105 | element and elements following it; all elements before the inserted/deleted | |
106 | element remain valid. | |
107 | ||
108 | .. raw:: html | |
109 | ||
110 | <hr> | |
111 | ||
112 | **Navigate:** | |
113 | ||
114 | - `home <ptr_container.html>`_ | |
115 | - `reference <reference.html>`_ | |
116 | ||
117 | .. raw:: html | |
118 | ||
119 | <hr> | |
120 | ||
121 | :Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__). | |
122 | ||
123 | __ http://www.boost.org/LICENSE_1_0.txt | |
124 | ||
125 |