libs/smart_ptr/shared_array.htm

   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 text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
   8         <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
   9             width="277" align="middle" border="0">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&lt;class T&gt; 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&lt;class D&gt; <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 &amp; r); // never throws
  44
  45       shared_array &amp; <a href="#assignment">operator=</a>(shared_array const &amp; r); // never throws
  46
  47       void <a href="#reset">reset</a>(T * p = 0);
  48       template&lt;class D&gt; void <a href="#reset">reset</a>(T * p, D d);
  49
  50       T &amp; <a href="#indexing">operator[]</a>(std::ptrdiff_t i) 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&lt;T&gt; &amp; b); // never throws
  59   };
  60
  61   template&lt;class T&gt;
  62     bool <a href="#comparison">operator==</a>(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
  63   template&lt;class T&gt;
  64     bool <a href="#comparison">operator!=</a>(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
  65   template&lt;class T&gt;
  66     bool <a href="#comparison">operator&lt;</a>(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
  67
  68   template&lt;class T&gt; void <a href="#free-swap">swap</a>(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; 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&lt;class D&gt; 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 &amp; 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 &amp; operator=(shared_array const &amp; 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&lt;class D&gt; 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 &amp; 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 &amp; 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&lt;class T&gt;
 156   bool operator==(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
 157 template&lt;class T&gt;
 158   bool operator!=(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
 159 template&lt;class T&gt;
 160   bool operator&lt;(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; 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&lt;</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&lt;T *&gt;</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&lt;&gt;</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&lt;class T&gt;
 173   void swap(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; 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>$Date$</p>
 178         <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
 179             Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version
 180             1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
 181             copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
 182     </body>
 183 </html>