forked from boostorg/smart_ptr
Documentation fixes (reflecting Dave Abrahams' comments)
[SVN r15382]
This commit is contained in:
Peter Dimov committed
1 parent
4ea6decc7d
commit
0f05f41306
3 files changed
+242
-319
No files matched your search
+89
-123
@@ -1,53 +1,38 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
<title>scoped_array</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF" text="#000000">
|
||||
|
||||
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86"><a name="scoped_array">scoped_array</a> class template</h1>
|
||||
|
||||
<p>The <b>scoped_array</b> class template stores a pointer to a dynamically allocated
|
||||
array. (Dynamically allocated arrays are allocated with the C++ <b>new[]</b>
|
||||
expression.) The array pointed to is guaranteed to be deleted,
|
||||
either on destruction of the <b>scoped_array</b>, or via an explicit <b>reset</b>.</p>
|
||||
|
||||
<p>The <b>scoped_array</b> template is a simple solution for simple
|
||||
needs. It supplies a basic "resource acquisition is
|
||||
initialization" facility, without shared-ownership or transfer-of-ownership
|
||||
semantics. Both its name and enforcement of semantics (by being
|
||||
<a href="../utility/utility.htm#class noncopyable">noncopyable</a>)
|
||||
signal its intent to retain ownership solely within the current scope.
|
||||
Because it is <a href="../utility/utility.htm#class noncopyable">noncopyable</a>, it is
|
||||
safer than <b>shared_array</b> for pointers which should not be copied.</p>
|
||||
|
||||
<p>Because <b>scoped_array</b> is so simple, in its usual implementation
|
||||
every operation is as fast as a built-in array pointer and it has no
|
||||
more space overhead that a built-in array pointer.</p>
|
||||
|
||||
<p>It cannot be used in C++ standard library containers.
|
||||
See <a href="shared_array.htm"><b>shared_array</b></a>
|
||||
if <b>scoped_array</b> does not meet your needs.</p>
|
||||
|
||||
<p>It cannot correctly hold a pointer to a single object.
|
||||
See <a href="scoped_ptr.htm"><b>scoped_ptr</b></a>
|
||||
for that usage.</p>
|
||||
|
||||
<p>A <b>std::vector</b> is an alternative to a <b>scoped_array</b> that is
|
||||
a bit heavier duty but far more flexible.
|
||||
A <b>boost::array</b> is an alternative that does not use dynamic allocation.</p>
|
||||
|
||||
<p>The class template is parameterized on <b>T</b>, the type of the object
|
||||
pointed to. <b>T</b> must meet the smart pointer
|
||||
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
||||
|
||||
<h2>Synopsis</h2>
|
||||
|
||||
<pre>namespace boost {
|
||||
<head>
|
||||
<title>scoped_array</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</head>
|
||||
<body bgcolor="#ffffff" text="#000000">
|
||||
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86"><a name="scoped_array">scoped_array</a>
|
||||
class template</h1>
|
||||
<p>The <b>scoped_array</b> class template stores a pointer to a dynamically
|
||||
allocated array. (Dynamically allocated arrays are allocated with the C++ <b>new[]</b>
|
||||
expression.) The array pointed to is guaranteed to be deleted, either on
|
||||
destruction of the <b>scoped_array</b>, or via an explicit <b>reset</b>.</p>
|
||||
<p>The <b>scoped_array</b> template is a simple solution for simple needs. It
|
||||
supplies a basic "resource acquisition is initialization" facility, without
|
||||
shared-ownership or transfer-of-ownership semantics. Both its name and
|
||||
enforcement of semantics (by being <a href="../utility/utility.htm#class noncopyable">
|
||||
noncopyable</a>) signal its intent to retain ownership solely within the
|
||||
current scope. Because it is <a href="../utility/utility.htm#class noncopyable">noncopyable</a>,
|
||||
it is safer than <b>shared_array</b> for pointers which should not be copied.</p>
|
||||
<p>Because <b>scoped_array</b> is so simple, in its usual implementation every
|
||||
operation is as fast as a built-in array pointer and it has no more space
|
||||
overhead that a built-in array pointer.</p>
|
||||
<p>It cannot be used in C++ standard library containers. See <a href="shared_array.htm">
|
||||
<b>shared_array</b></a> if <b>scoped_array</b> does not meet your needs.</p>
|
||||
<p>It cannot correctly hold a pointer to a single object. See <a href="scoped_ptr.htm"><b>scoped_ptr</b></a>
|
||||
for that usage.</p>
|
||||
<p>A <b>std::vector</b> is an alternative to a <b>scoped_array</b> that is a bit
|
||||
heavier duty but far more flexible. A <b>boost::array</b> is an alternative
|
||||
that does not use dynamic allocation.</p>
|
||||
<p>The class template is parameterized on <b>T</b>, the type of the object pointed
|
||||
to. <b>T</b> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">
|
||||
common requirements</a>.</p>
|
||||
<h2>Synopsis</h2>
|
||||
<pre>namespace boost {
|
||||
|
||||
template<typename T> class scoped_array : <a href="../utility/utility.htm#noncopyable">noncopyable</a> {
|
||||
|
||||
@@ -59,7 +44,7 @@ pointed to. <b>T</b> must meet the smart pointer
|
||||
|
||||
void <a href="#reset">reset</a>(T * p = 0); // never throws
|
||||
|
||||
T & <a href="#operator[]">operator[]</a>(std::size_t i) const; // never throws
|
||||
T & <a href="#operator[]">operator[]</a>(std::ptrdiff_t i) const; // never throws
|
||||
T * <a href="#get">get</a>() const; // never throws
|
||||
|
||||
void <a href="#swap">swap</a>(scoped_array & b); // never throws
|
||||
@@ -68,78 +53,59 @@ pointed to. <b>T</b> must meet the smart pointer
|
||||
template<typename T> void <a href="#free-swap">swap</a>(scoped_array<T> & a, scoped_array<T> & b); // never throws
|
||||
|
||||
}</pre>
|
||||
|
||||
<h2>Members</h2>
|
||||
|
||||
<h3>
|
||||
<a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<p>Provides the type of the stored pointer.</p>
|
||||
|
||||
<h3><a name="ctor">constructors</a></h3>
|
||||
<pre>explicit scoped_array(T * p = 0); // never throws</pre>
|
||||
<p>Constructs a <b>scoped_array</b>, storing a copy of <b>p</b>, which must
|
||||
have been allocated via a C++ <b>new</b>[] expression or be 0.
|
||||
<b>T</b> is not required be a complete type.
|
||||
See the smart pointer
|
||||
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
||||
|
||||
<h3><a name="~scoped_array">destructor</a></h3>
|
||||
<pre>~scoped_array(); // never throws</pre>
|
||||
<p>Deletes the array pointed to by the stored pointer.
|
||||
Note that <b>delete[]</b> on a pointer with a value of 0 is harmless.
|
||||
The guarantee that this does not throw exceptions depends on the requirement that the
|
||||
deleted array's objects' destructors do not throw exceptions.
|
||||
See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
||||
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset(T * p = 0); // never throws</pre>
|
||||
<p>If p is not equal to the stored pointer, deletes the array pointed to by the
|
||||
stored pointer and then stores a copy of p, which must have been allocated via a
|
||||
C++ <b>new[]</b> expression or be 0.
|
||||
The guarantee that this does not throw exceptions depends on the requirement that the
|
||||
deleted array's objects' destructors do not throw exceptions.
|
||||
See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
||||
|
||||
<h3><a name="operator[]">subscripting</a></h3>
|
||||
<pre>T & operator[](std::size_t i) const; // never throws</pre>
|
||||
<p>Returns a reference to element <b>i</b> of the array pointed to by the
|
||||
stored pointer.
|
||||
Behavior is undefined and almost certainly undesirable if the stored pointer is 0,
|
||||
or if <b>i</b> is less than 0 or is greater than or equal to the number of elements
|
||||
in the array.</p>
|
||||
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<p>Returns the stored pointer.
|
||||
<b>T</b> need not be a complete type.
|
||||
See the smart pointer
|
||||
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
||||
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(scoped_array & b); // never throws</pre>
|
||||
<p>Exchanges the contents of the two smart pointers.
|
||||
<b>T</b> need not be a complete type.
|
||||
See the smart pointer
|
||||
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
||||
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<typename T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws</pre>
|
||||
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
|
||||
Provided as an aid to generic programming.</p>
|
||||
|
||||
<hr>
|
||||
|
||||
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan-->1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="13964"--></p>
|
||||
|
||||
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
|
||||
Permission to copy, use, modify, sell and distribute this document is granted
|
||||
provided this copyright notice appears in all copies.
|
||||
This document is provided "as is" without express or implied warranty,
|
||||
and with no claim as to its suitability for any purpose.</p>
|
||||
|
||||
</body>
|
||||
|
||||
<h2>Members</h2>
|
||||
<h3>
|
||||
<a name="element_type">element_type</a></h3>
|
||||
<pre>typedef T element_type;</pre>
|
||||
<p>Provides the type of the stored pointer.</p>
|
||||
<h3><a name="ctor">constructors</a></h3>
|
||||
<pre>explicit scoped_array(T * p = 0); // never throws</pre>
|
||||
<p>Constructs a <b>scoped_array</b>, storing a copy of <b>p</b>, which must have
|
||||
been allocated via a C++ <b>new</b>[] expression or be 0. <b>T</b> is not
|
||||
required be a complete type. See the smart pointer <a href="smart_ptr.htm#Common requirements">
|
||||
common requirements</a>.</p>
|
||||
<h3><a name="~scoped_array">destructor</a></h3>
|
||||
<pre>~scoped_array(); // never throws</pre>
|
||||
<p>Deletes the array pointed to by the stored pointer. Note that <b>delete[]</b> on
|
||||
a pointer with a value of 0 is harmless. The guarantee that this does not throw
|
||||
exceptions depends on the requirement that the deleted array's objects'
|
||||
destructors do not throw exceptions. See the smart pointer <a href="smart_ptr.htm#Common requirements">
|
||||
common requirements</a>.</p>
|
||||
<h3><a name="reset">reset</a></h3>
|
||||
<pre>void reset(T * p = 0); // never throws</pre>
|
||||
<p>If p is not equal to the stored pointer, deletes the array pointed to by the
|
||||
stored pointer and then stores a copy of p, which must have been allocated via
|
||||
a C++ <b>new[]</b> expression or be 0. The guarantee that this does not throw
|
||||
exceptions depends on the requirement that the deleted array's objects'
|
||||
destructors do not throw exceptions. See the smart pointer <a href="smart_ptr.htm#Common requirements">
|
||||
common requirements</a>.</p>
|
||||
<h3><a name="operator[]">subscripting</a></h3>
|
||||
<pre>T & operator[](std::ptrdiff_t i) const; // never throws</pre>
|
||||
<p>Returns a reference to element <b>i</b> of the array pointed to by the stored
|
||||
pointer. Behavior is undefined and almost certainly undesirable if the stored
|
||||
pointer is 0, or if <b>i</b> is less than 0 or is greater than or equal to the
|
||||
number of elements in the array.</p>
|
||||
<h3><a name="get">get</a></h3>
|
||||
<pre>T * get() const; // never throws</pre>
|
||||
<p>Returns the stored pointer. <b>T</b> need not be a complete type. See the smart
|
||||
pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
|
||||
<h3><a name="swap">swap</a></h3>
|
||||
<pre>void swap(scoped_array & b); // never throws</pre>
|
||||
<p>Exchanges the contents of the two smart pointers. <b>T</b> need not be a
|
||||
complete type. See the smart pointer <a href="smart_ptr.htm#Common requirements">common
|
||||
requirements</a>.</p>
|
||||
<h2><a name="functions">Free Functions</a></h2>
|
||||
<h3><a name="free-swap">swap</a></h3>
|
||||
<pre>template<typename T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws</pre>
|
||||
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
|
||||
Provided as an aid to generic programming.</p>
|
||||
<hr>
|
||||
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan-->
|
||||
1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="13964"--></p>
|
||||
<p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
|
||||
Permission to copy, use, modify, sell and distribute this document is granted
|
||||
provided this copyright notice appears in all copies. This document is provided
|
||||
"as is" without express or implied warranty, and with no claim as to its
|
||||
suitability for any purpose.</p>
|
||||
</body>
|
||||
</html>
|
||||
Reference in new issue
Block a user