[ceph.git] / ceph / src / boost / libs / smart_ptr / scoped_array.htm

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
    <head>
        <title>scoped_array</title>
        <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    </head>
        <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
        <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png" 
            width="277" align="middle" border="0">scoped_array 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&lt;class T&gt; class scoped_array : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {

    public:
      typedef T <a href="#element_type">element_type</a>;

      explicit <a href="#ctor">scoped_array</a>(T * p = 0); // never throws
      <a href="#destructor">~scoped_array</a>(); // never throws

      void <a href="#reset">reset</a>(T * p = 0); // never throws

      T &amp; <a href="#operator[]">operator[]</a>(std::ptrdiff_t i) const; // never throws
      T * <a href="#get">get</a>() const; // never throws
     
      operator <A href="#conversions" ><i>unspecified-bool-type</i></A>() const; // never throws

      void <a href="#swap">swap</a>(scoped_array &amp; b); // never throws
  };

  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

}</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="destructor">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>
            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 &amp; 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="conversions">conversions</a></h3>
        <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
        <p>Returns an unspecified value that, when used in boolean contexts, is equivalent 
            to <code>get() != 0</code>.</p>
        <h3><a name="swap">swap</a></h3>
        <pre>void swap(scoped_array &amp; 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&lt;class T&gt; void swap(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; 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>$Date$</p>
        <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. 
            Copyright 2002-2005 Peter Dimov. Distributed under the Boost Software License, Version 
            1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or 
            copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
    </body>
</html>
Commit	Line	Data
7c673cae FG	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<class T> 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 & <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 & b); // never throws
	53	};
	54
	55	template<class T> void <a href="#free-swap">swap</a>(scoped_array<T> & a, scoped_array<T> & 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 & 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 & 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<class T> void swap(scoped_array<T> & a, scoped_array<T> & 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>