Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/smart_ptr/scoped_array.htm @ 20

Last change on this file since 20 was 12, checked in by landauf, 18 years ago

added boost

File size: 6.3 KB
Line 
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 bgcolor="#ffffff" text="#000000">
8                <h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86"><a name="scoped_array">scoped_array</a>
9                        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
18        <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a>) signal its intent to retain ownership solely within the
19                        current scope. Because it is
20        <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a>,
21                        it is safer than <b>shared_array</b> for pointers which should not be copied.</p>
22                <p>Because <b>scoped_array</b> is so simple, in its usual implementation every
23                        operation is as fast as a built-in array pointer and it has no more space
24                        overhead that a built-in array pointer.</p>
25                <p>It cannot be used in C++ standard library containers. See <a href="shared_array.htm">
26                                <b>shared_array</b></a> if <b>scoped_array</b> does not meet your needs.</p>
27                <p>It cannot correctly hold a pointer to a single object. See <a href="scoped_ptr.htm"><b>scoped_ptr</b></a>
28                        for that usage.</p>
29                <p>A <b>std::vector</b> is an alternative to a <b>scoped_array</b> that is a bit
30                        heavier duty but far more flexible. A <b>boost::array</b> is an alternative
31                        that does not use dynamic allocation.</p>
32                <p>The class template is parameterized on <b>T</b>, the type of the object pointed
33                        to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#common_requirements">
34                                common requirements</a>.</p>
35                <h2>Synopsis</h2>
36                <pre>namespace boost {
37
38  template&lt;class T&gt; class scoped_array : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {
39
40    public:
41      typedef T <a href="#element_type">element_type</a>;
42
43      explicit <a href="#ctor">scoped_array</a>(T * p = 0); // never throws
44      <a href="#destructor">~scoped_array</a>(); // never throws
45
46      void <a href="#reset">reset</a>(T * p = 0); // never throws
47
48      T &amp; <a href="#operator[]">operator[]</a>(std::ptrdiff_t i) const; // never throws
49      T * <a href="#get">get</a>() const; // never throws
50     
51      void <a href="#swap">swap</a>(scoped_array &amp; b); // never throws
52  };
53
54  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
55
56}</pre>
57                <h2>Members</h2>
58                <h3>
59                        <a name="element_type">element_type</a></h3>
60                <pre>typedef T element_type;</pre>
61                <p>Provides the type of the stored pointer.</p>
62                <h3><a name="ctor">constructors</a></h3>
63                <pre>explicit scoped_array(T * p = 0); // never throws</pre>
64                <p>Constructs a <b>scoped_array</b>, storing a copy of <b>p</b>, which must have
65                        been allocated via a C++ <b>new</b>[] expression or be 0. <b>T</b> is not
66                        required be a complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">
67                                common requirements</a>.</p>
68                <h3><a name="destructor">destructor</a></h3>
69                <pre>~scoped_array(); // never throws</pre>
70                <p>Deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on
71                        a pointer with a value of 0 is harmless. The guarantee that this does not throw
72                        exceptions depends on the requirement that the deleted array's objects'
73                        destructors do not throw exceptions. See the smart pointer <a href="smart_ptr.htm#common_requirements">
74                                common requirements</a>.</p>
75                <h3><a name="reset">reset</a></h3>
76                <pre>void reset(T * p = 0); // never throws</pre>
77                <p>
78                        Deletes the array pointed to by the stored pointer and then stores a copy of p,
79                        which must have been allocated via a C++ <b>new[]</b> expression or be 0. The
80                        guarantee that this does not throw exceptions depends on the requirement that
81                        the deleted array's objects' destructors do not throw exceptions. See the smart
82                        pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
83                <h3><a name="operator[]">subscripting</a></h3>
84                <pre>T &amp; operator[](std::ptrdiff_t i) const; // never throws</pre>
85                <p>Returns a reference to element <b>i</b> of the array pointed to by the stored
86                        pointer. Behavior is undefined and almost certainly undesirable if the stored
87                        pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the
88                        number of elements in the array.</p>
89                <h3><a name="get">get</a></h3>
90                <pre>T * get() const; // never throws</pre>
91                <p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart
92                        pointer <a href="smart_ptr.htm#common_requirements">common requirements</a>.</p>
93                <h3><a name="swap">swap</a></h3>
94                <pre>void swap(scoped_array &amp; b); // never throws</pre>
95                <p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a
96                        complete type. See the smart pointer <a href="smart_ptr.htm#common_requirements">common
97                                requirements</a>.</p>
98                <h2><a name="functions">Free Functions</a></h2>
99                <h3><a name="free-swap">swap</a></h3>
100                <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>
101                <p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
102                        Provided as an aid to generic programming.</p>
103                <hr>
104                <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan-->09 January 2003<!--webbot bot="Timestamp" endspan i-checksum="32310"--></p>
105                <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
106                        Permission to copy, use, modify, sell and distribute this document is granted
107                        provided this copyright notice appears in all copies. This document is provided
108                        "as is" without express or implied warranty, and with no claim as to its
109                        suitability for any purpose.</p>
110        </body>
111</html>
Note: See TracBrowser for help on using the repository browser.