libs/smart_ptr/scoped_array.htm

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3     <head>
   4         <title>scoped_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">scoped_array class template</h1>
  10         <p>The <b>scoped_array</b> class template stores a pointer to a dynamically
  11             allocated array. (Dynamically allocated arrays are allocated with the C++ <b>new[]</b>
  12             expression.) The array pointed to is guaranteed to be deleted, either on
  13             destruction of the <b>scoped_array</b>, or via an explicit <b>reset</b>.</p>
  14         <p>The <b>scoped_array</b> template is a simple solution for simple needs. It
  15             supplies a basic "resource acquisition is initialization" facility, without
  16             shared-ownership or transfer-of-ownership semantics. Both its name and
  17             enforcement of semantics (by being <a href="../utility/utility.htm#Class_noncopyable">
  18             noncopyable</a>) signal its intent to retain ownership solely within the
  19             current scope. Because it is <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a>,
  20             it is safer than <b>shared_array</b> for pointers which should not be copied.</p>
  21         <p>Because <b>scoped_array</b> is so simple, in its usual implementation every
  22             operation is as fast as a built-in array pointer and it has no more space
  23             overhead that a built-in array pointer.</p>
  24         <p>It cannot be used in C++ standard library containers. See <a href="shared_array.htm">
  25             <b>shared_array</b></a> if <b>scoped_array</b> does not meet your needs.</p>
  26         <p>It cannot correctly hold a pointer to a single object. See <a href="scoped_ptr.htm"><b>scoped_ptr</b></a>
  27             for that usage.</p>
  28         <p>A <b>std::vector</b> is an alternative to a <b>scoped_array</b> that is a bit
  29             heavier duty but far more flexible. A <b>boost::array</b> is an alternative
  30             that does not use dynamic allocation.</p>
  31         <p>The class template is parameterized on <b>T</b>, the type of the object pointed
  32             to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements">
  33             common requirements</a>.</p>
  34         <h2>Synopsis</h2>
  35         <pre>namespace boost {
  36
  37   template&lt;class T&gt; class scoped_array : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {
  38
  39     public:
  40       typedef T <a href="#element_type">element_type</a>;
  41
  42       explicit <a href="#ctor">scoped_array</a>(T * p = 0); // never throws
  43       <a href="#destructor">~scoped_array</a>(); // never throws
  44
  45       void <a href="#reset">reset</a>(T * p = 0); // never throws
  46
  47       T &amp; <a href="#operator[]">operator[]</a>(std::ptrdiff_t i) const; // never throws
  48       T * <a href="#get">get</a>() const; // never throws
  49
  50       operator <A href="#conversions" ><i>unspecified-bool-type</i></A>() const; // never throws
  51
  52       void <a href="#swap">swap</a>(scoped_array &amp; b); // never throws
  53   };
  54
  55   template&lt;class T&gt; void <a href="#free-swap">swap</a>(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws
  56
  57 }</pre>
  58         <h2>Members</h2>
  59         <h3>
  60             <a name="element_type">element_type</a></h3>
  61         <pre>typedef T element_type;</pre>
  62         <p>Provides the type of the stored pointer.</p>
  63         <h3><a name="ctor">constructors</a></h3>
  64         <pre>explicit scoped_array(T * p = 0); // never throws</pre>
  65         <p>Constructs a <b>scoped_array</b>, storing a copy of <b>p</b>, which must have
  66             been allocated via a C++ <b>new</b>[] expression or be 0. <b>T</b> is not
  67             required be a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">
  68             common requirements</a>.</p>
  69         <h3><a name="destructor">destructor</a></h3>
  70         <pre>~scoped_array(); // never throws</pre>
  71         <p>Deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on
  72             a pointer with a value of 0 is harmless. The guarantee that this does not throw
  73             exceptions depends on the requirement that the deleted array's objects'
  74             destructors do not throw exceptions. See the smart pointer <a href="smart_ptr.htm#common_requirements">
  75             common requirements</a>.</p>
  76         <h3><a name="reset">reset</a></h3>
  77         <pre>void reset(T * p = 0); // never throws</pre>
  78         <p>
  79             Deletes the array pointed to by the stored pointer and then stores a copy of p,
  80             which must have been allocated via a C++ <b>new[]</b> expression or be 0. The
  81             guarantee that this does not throw exceptions depends on the requirement that
  82             the deleted array's objects' destructors do not throw exceptions. See the smart
  83             pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
  84         <h3><a name="operator[]">subscripting</a></h3>
  85         <pre>T &amp; operator[](std::ptrdiff_t i) const; // never throws</pre>
  86         <p>Returns a reference to element <b>i</b> of the array pointed to by the stored
  87             pointer. Behavior is undefined and almost certainly undesirable if the stored
  88             pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the
  89             number of elements in the array.</p>
  90         <h3><a name="get">get</a></h3>
  91         <pre>T * get() const; // never throws</pre>
  92         <p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart
  93             pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
  94         <h3><a name="conversions">conversions</a></h3>
  95         <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
  96         <p>Returns an unspecified value that, when used in boolean contexts, is equivalent
  97             to <code>get() != 0</code>.</p>
  98         <h3><a name="swap">swap</a></h3>
  99         <pre>void swap(scoped_array &amp; b); // never throws</pre>
 100         <p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a
 101             complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common
 102             requirements</a>.</p>
 103         <h2><a name="functions">Free Functions</a></h2>
 104         <h3><a name="free-swap">swap</a></h3>
 105         <pre>template&lt;class T&gt; void swap(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws</pre>
 106         <p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
 107             Provided as an aid to generic programming.</p>
 108         <hr>
 109         <p>$Date$</p>
 110         <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
 111             Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version
 112             1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
 113             copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
 114     </body>
 115 </html>