| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
|---|
| 2 | <html> |
|---|
| 3 | <head> |
|---|
| 4 | <title>shared_array</title> |
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 6 | </head> |
|---|
| 7 | <body bgcolor="#ffffff" text="#000000"> |
|---|
| 8 | <h1><A href="../../index.htm"><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" |
|---|
| 9 | border="0"></A>shared_array class template</h1> |
|---|
| 10 | <p>The <b>shared_array</b> class template stores a pointer to a dynamically |
|---|
| 11 | allocated array. (Dynamically allocated array are allocated with the C++ <b>new[]</b> |
|---|
| 12 | expression.) The object pointed to is guaranteed to be deleted when the last <b>shared_array</b> |
|---|
| 13 | pointing to it is destroyed or reset.</p> |
|---|
| 14 | <p>Every <b>shared_array</b> meets the <b>CopyConstructible</b> and <b>Assignable</b> |
|---|
| 15 | requirements of the C++ Standard Library, and so can be used in standard |
|---|
| 16 | library containers. Comparison operators are supplied so that <b>shared_array</b> |
|---|
| 17 | works with the standard library's associative containers.</p> |
|---|
| 18 | <p>Normally, a <b>shared_array</b> cannot correctly hold a pointer to an object |
|---|
| 19 | that has been allocated with the non-array form of <STRONG>new</STRONG>. See <a href="shared_ptr.htm"> |
|---|
| 20 | <b>shared_ptr</b></a> for that usage.</p> |
|---|
| 21 | <p>Because the implementation uses reference counting, cycles of <b>shared_array</b> |
|---|
| 22 | instances will not be reclaimed. For example, if <b>main()</b> holds a <b>shared_array</b> |
|---|
| 23 | to <b>A</b>, which directly or indirectly holds a <b>shared_array</b> back to <b>A</b>, |
|---|
| 24 | <b>A</b>'s use count will be 2. Destruction of the original <b>shared_array</b> |
|---|
| 25 | will leave <b>A</b> dangling with a use count of 1.</p> |
|---|
| 26 | <p>A <b>shared_ptr</b> to a <b>std::vector</b> is an alternative to a <b>shared_array</b> |
|---|
| 27 | that is a bit heavier duty but far more flexible.</p> |
|---|
| 28 | <p>The class template is parameterized on <b>T</b>, the type of the object pointed |
|---|
| 29 | to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements"> |
|---|
| 30 | common requirements</a>.</p> |
|---|
| 31 | <h2>Synopsis</h2> |
|---|
| 32 | <pre>namespace boost { |
|---|
| 33 | |
|---|
| 34 | template<class T> class shared_array { |
|---|
| 35 | |
|---|
| 36 | public: |
|---|
| 37 | typedef T <a href="#element_type">element_type</a>; |
|---|
| 38 | |
|---|
| 39 | explicit <a href="#constructors">shared_array</a>(T * p = 0); |
|---|
| 40 | template<class D> <a href="#constructors">shared_array</a>(T * p, D d); |
|---|
| 41 | <a href="#destructor">~shared_array</a>(); // never throws |
|---|
| 42 | |
|---|
| 43 | <a href="#constructors">shared_array</a>(shared_array const & r); // never throws |
|---|
| 44 | |
|---|
| 45 | shared_array & <a href="#assignment">operator=</a>(shared_array const & r); // never throws |
|---|
| 46 | |
|---|
| 47 | void <a href="#reset">reset</a>(T * p = 0); |
|---|
| 48 | template<class D> void <a href="#reset">reset</a>(T * p, D d); |
|---|
| 49 | |
|---|
| 50 | T & <a href="#indexing">operator[]</a>(std::ptrdiff_t i) const() const; // never throws |
|---|
| 51 | T * <a href="#get">get</a>() const; // never throws |
|---|
| 52 | |
|---|
| 53 | bool <a href="#unique">unique</a>() const; // never throws |
|---|
| 54 | long <a href="#use_count">use_count</a>() const; // never throws |
|---|
| 55 | |
|---|
| 56 | operator <A href="#conversions" ><i>unspecified-bool-type</i></A>() const; // never throws |
|---|
| 57 | |
|---|
| 58 | void <a href="#swap">swap</a>(shared_array<T> & b); // never throws |
|---|
| 59 | }; |
|---|
| 60 | |
|---|
| 61 | template<class T> |
|---|
| 62 | bool <a href="#comparison">operator==</a>(shared_array<T> const & a, shared_array<T> const & b); // never throws |
|---|
| 63 | template<class T> |
|---|
| 64 | bool <a href="#comparison">operator!=</a>(shared_array<T> const & a, shared_array<T> const & b); // never throws |
|---|
| 65 | template<class T> |
|---|
| 66 | bool <a href="#comparison">operator<</a>(shared_array<T> const & a, shared_array<T> const & b); // never throws |
|---|
| 67 | |
|---|
| 68 | template<class T> void <a href="#free-swap">swap</a>(shared_array<T> & a, shared_array<T> & b); // never throws |
|---|
| 69 | |
|---|
| 70 | }</pre> |
|---|
| 71 | <h2>Members</h2> |
|---|
| 72 | <h3><a name="element_type">element_type</a></h3> |
|---|
| 73 | <pre>typedef T element_type;</pre> |
|---|
| 74 | <p>Provides the type of the stored pointer.</p> |
|---|
| 75 | <h3><a name="constructors">constructors</a></h3> |
|---|
| 76 | <pre>explicit shared_array(T * p = 0);</pre> |
|---|
| 77 | <p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b>, which must be a |
|---|
| 78 | pointer to an array that was allocated via a C++ <b>new[]</b> expression or be |
|---|
| 79 | 0. Afterwards, the <a href="#use_count">use count</a> is 1 (even if p == 0; see <a href="#destructor"> |
|---|
| 80 | ~shared_array</a>). The only exception which may be thrown by this |
|---|
| 81 | constructor is <b>std::bad_alloc</b>. If an exception is thrown, <b>delete[] p</b> |
|---|
| 82 | is called.</p> |
|---|
| 83 | <pre>template<class D> shared_array(T * p, D d);</pre> |
|---|
| 84 | <p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b> and of <b>d</b>. |
|---|
| 85 | Afterwards, the <a href="#use_count">use count</a> is 1. <b>D</b>'s copy |
|---|
| 86 | constructor and destructor must not throw. When the the time comes to delete |
|---|
| 87 | the array pointed to by <b>p</b>, the object <b>d</b> is used in the statement <b>d(p)</b>. |
|---|
| 88 | Invoking the object <b>d</b> with parameter <b>p</b> in this way must not |
|---|
| 89 | throw. The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>. |
|---|
| 90 | If an exception is thrown, <b>d(p)</b> is called.</p> |
|---|
| 91 | <pre>shared_array(shared_array const & r); // never throws</pre> |
|---|
| 92 | <p>Constructs a <b>shared_array</b>, as if by storing a copy of the pointer stored |
|---|
| 93 | in <b>r</b>. Afterwards, the <a href="#use_count">use count</a> for all copies |
|---|
| 94 | is 1 more than the initial use count.</p> |
|---|
| 95 | <h3><a name="destructor">destructor</a></h3> |
|---|
| 96 | <pre>~shared_array(); // never throws</pre> |
|---|
| 97 | <p>Decrements the <a href="#use_count">use count</a>. Then, if the use count is 0, |
|---|
| 98 | deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on |
|---|
| 99 | a pointer with a value of 0 is harmless. <b>T</b> need not be a complete type. |
|---|
| 100 | The guarantee that this does not throw exceptions depends on the requirement |
|---|
| 101 | that the deleted object's destructor does not throw exceptions. See the smart |
|---|
| 102 | pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> |
|---|
| 103 | <h3><a name="assignment">assignment</a></h3> |
|---|
| 104 | <pre>shared_array & operator=(shared_array const & r); // never throws</pre> |
|---|
| 105 | <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>, |
|---|
| 106 | then replaces this <b>shared_array</b> with the new one, destroying the |
|---|
| 107 | replaced object.</p> |
|---|
| 108 | <h3><a name="reset">reset</a></h3> |
|---|
| 109 | <pre>void reset(T * p = 0);</pre> |
|---|
| 110 | <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>, |
|---|
| 111 | then replaces this <b>shared_array</b> with the new one, destroying the |
|---|
| 112 | replaced object. The only exception which may be thrown is <b>std::bad_alloc</b>. |
|---|
| 113 | If an exception is thrown, <b>delete[] p</b> is called.</p> |
|---|
| 114 | <pre>template<class D> void reset(T * p, D d);</pre> |
|---|
| 115 | <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>, |
|---|
| 116 | then replaces this <b>shared_array</b> with the new one, destroying the |
|---|
| 117 | replaced object. <b>D</b>'s copy constructor must not throw. The only exception |
|---|
| 118 | which may be thrown is <b>std::bad_alloc</b>. If an exception is thrown, <b>d(p)</b> |
|---|
| 119 | is called.</p> |
|---|
| 120 | <h3><a name="indexing">indexing</a></h3> |
|---|
| 121 | <pre>T & operator[](std::ptrdiff_t i) const; // never throws</pre> |
|---|
| 122 | <p>Returns a reference to element <b>i</b> of the array pointed to by the stored |
|---|
| 123 | pointer. Behavior is undefined and almost certainly undesirable if the stored |
|---|
| 124 | pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the |
|---|
| 125 | number of elements in the array.</p> |
|---|
| 126 | <h3><a name="get">get</a></h3> |
|---|
| 127 | <pre>T * get() const; // never throws</pre> |
|---|
| 128 | <p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart |
|---|
| 129 | pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> |
|---|
| 130 | <h3><a name="unique">unique</a></h3> |
|---|
| 131 | <pre>bool unique() const; // never throws</pre> |
|---|
| 132 | <p>Returns true if no other <b>shared_array</b> is sharing ownership of the stored |
|---|
| 133 | pointer, false otherwise. <b>T</b> need not be a complete type. See the smart |
|---|
| 134 | pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p> |
|---|
| 135 | <h3><a name="use_count">use_count</a></h3> |
|---|
| 136 | <pre>long use_count() const; // never throws</pre> |
|---|
| 137 | <p>Returns the number of <b>shared_array</b> objects sharing ownership of the |
|---|
| 138 | stored pointer. <b>T</b> need not be a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements"> |
|---|
| 139 | common requirements</a>.</p> |
|---|
| 140 | <p>Because <b>use_count</b> is not necessarily efficient to implement for |
|---|
| 141 | implementations of <b>shared_array</b> that do not use an explicit reference |
|---|
| 142 | count, it might be removed from some future version. Thus it should be used for |
|---|
| 143 | debugging purposes only, and not production code.</p> |
|---|
| 144 | <h3><a name="conversions">conversions</a></h3> |
|---|
| 145 | <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre> |
|---|
| 146 | <p>Returns an unspecified value that, when used in boolean contexts, is equivalent |
|---|
| 147 | to <code>get() != 0</code>.</p> |
|---|
| 148 | <h3><a name="swap">swap</a></h3> |
|---|
| 149 | <pre>void swap(shared_ptr & b); // never throws</pre> |
|---|
| 150 | <p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a |
|---|
| 151 | complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common |
|---|
| 152 | requirements</a>.</p> |
|---|
| 153 | <h2><a name="functions">Free Functions</a></h2> |
|---|
| 154 | <h3><a name="comparison">comparison</a></h3> |
|---|
| 155 | <pre>template<class T> |
|---|
| 156 | bool operator==(shared_array<T> const & a, shared_array<T> const & b); // never throws |
|---|
| 157 | template<class T> |
|---|
| 158 | bool operator!=(shared_array<T> const & a, shared_array<T> const & b); // never throws |
|---|
| 159 | template<class T> |
|---|
| 160 | bool operator<(shared_array<T> const & a, shared_array<T> const & b); // never throws</pre> |
|---|
| 161 | <p>Compares the stored pointers of the two smart pointers. <b>T</b> need not be a |
|---|
| 162 | complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common |
|---|
| 163 | requirements</a>.</p> |
|---|
| 164 | <p>The <b>operator<</b> overload is provided to define an ordering so that <b>shared_array</b> |
|---|
| 165 | objects can be used in associative containers such as <b>std::map</b>. The |
|---|
| 166 | implementation uses <b>std::less<T *></b> to perform the comparison. This |
|---|
| 167 | ensures that the comparison is handled correctly, since the standard mandates |
|---|
| 168 | that relational operations on pointers are unspecified (5.9 [expr.rel] |
|---|
| 169 | paragraph 2) but <b>std::less<></b> on pointers is well-defined (20.3.3 |
|---|
| 170 | [lib.comparisons] paragraph 8).</p> |
|---|
| 171 | <h3><a name="free-swap">swap</a></h3> |
|---|
| 172 | <pre>template<class T> |
|---|
| 173 | void swap(shared_array<T> & a, shared_array<T> & b) // never throws</pre> |
|---|
| 174 | <p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>. |
|---|
| 175 | Provided as an aid to generic programming.</p> |
|---|
| 176 | <hr> |
|---|
| 177 | <p>Revised |
|---|
| 178 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan --> |
|---|
| 179 | 09 January 2003<!--webbot bot="Timestamp" endspan i-checksum="32310" --></p> |
|---|
| 180 | <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. |
|---|
| 181 | Copyright 2002-2005 Peter Dimov. Permission to copy, use, modify, sell and |
|---|
| 182 | distribute this document is granted provided this copyright notice appears in |
|---|
| 183 | all copies. This document is provided "as is" without express or implied |
|---|
| 184 | warranty, and with no claim as to its suitability for any purpose.</p> |
|---|
| 185 | </body> |
|---|
| 186 | </html> |
|---|
