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<class T> 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 & <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 & b); // never throws |
---|
52 | }; |
---|
53 | |
---|
54 | template<class T> void <a href="#free-swap">swap</a>(scoped_array<T> & a, scoped_array<T> & 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 & 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 & 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<class T> void swap(scoped_array<T> & a, scoped_array<T> & 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> |
---|