Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r82349 - trunk/libs/smart_ptr
From: pdimov_at_[hidden]
Date: 2013-01-04 09:26:58


Author: pdimov
Date: 2013-01-04 09:26:56 EST (Fri, 04 Jan 2013)
New Revision: 82349
URL: http://svn.boost.org/trac/boost/changeset/82349

Log:
Update documentation for nullptr, owner_before, explicit operator bool.
Text files modified:
   trunk/libs/smart_ptr/shared_ptr.htm | 94 +++++++++++++++++++++++++++++----------
   1 files changed, 70 insertions(+), 24 deletions(-)

Modified: trunk/libs/smart_ptr/shared_ptr.htm
==============================================================================
--- trunk/libs/smart_ptr/shared_ptr.htm (original)
+++ trunk/libs/smart_ptr/shared_ptr.htm 2013-01-04 09:26:56 EST (Fri, 04 Jan 2013)
@@ -45,9 +45,10 @@
                         to "break cycles."</p>
                 <p>The class template is parameterized on <code>T</code>, the type of the object pointed
                         to. <code>shared_ptr</code> and most of its member functions place no
- requirements on <code>T</code>; it is allowed to be an incomplete type, or <code>
- void</code>. Member functions that do place additional requirements (constructors,
- reset) are explicitly documented below.</p>
+ requirements on <code>T</code>; it is allowed to be an incomplete type, or
+ <code>void</code>. Member functions that do place additional requirements
+ (constructors, reset) are explicitly
+ documented below.</p>
                 <p><code>shared_ptr&lt;T&gt;</code> can be implicitly converted to <code>shared_ptr&lt;U&gt;</code>
                         whenever <code>T*</code> can be implicitly converted to <code>U*</code>.
                         In particular, <code>shared_ptr&lt;T&gt;</code> is implicitly convertible
@@ -119,10 +120,13 @@
       typedef <em>see below</em> element_type;
 
       <a href="#default_constructor" >shared_ptr</a>(); // never throws
+ shared_ptr(std::nullptr_t); // never throws
 
       template&lt;class Y&gt; explicit shared_ptr(Y * p);
       template&lt;class Y, class D&gt; shared_ptr(Y * p, D d);
       template&lt;class Y, class D, class A&gt; shared_ptr(Y * p, D d, A a);
+ template&lt;class D&gt; shared_ptr(std::nullptr_t p, D d);
+ template&lt;class D, class A&gt; shared_ptr(std::nullptr_t p, D d, A a);
 
       <a href="#destructor" >~shared_ptr</a>(); // never throws
 
@@ -152,6 +156,8 @@
 
       template&lt;class Y, class D&gt; shared_ptr &amp; operator=(std::unique_ptr&lt;Y, D&gt; &amp;&amp; r);
 
+ shared_ptr &amp; operator=(std::nullptr_t); // never throws
+
       void reset(); // never throws
 
       template&lt;class Y&gt; void reset(Y * p);
@@ -163,19 +169,19 @@
       T &amp; operator*() const; // never throws; only valid when T is not an array type
       T * operator->() const; // never throws; only valid when T is not an array type
 
- element_type &amp; operator[]( std::ptrdiff_t i ) const; // never throws; only valid when T is an array type
+ element_type &amp; operator[](std::ptrdiff_t i) const; // never throws; only valid when T is an array type
 
       element_type * get() const; // never throws
 
       bool unique() const; // never throws
       long use_count() const; // never throws
 
- operator unspecified-bool-type() const; // never throws
+ explicit operator bool() const; // never throws
 
       void swap(shared_ptr &amp; b); // never throws
       
- template&lt;class Y&gt; bool owner_before( shared_ptr&lt;Y&gt; const &amp; rhs ) const; // never throws
- template&lt;class Y&gt; bool owner_before( weak_ptr&lt;Y&gt; const &amp; rhs ) const; // never throws
+ template&lt;class Y&gt; bool owner_before(shared_ptr&lt;Y&gt; const &amp; rhs) const; // never throws
+ template&lt;class Y&gt; bool owner_before(weak_ptr&lt;Y&gt; const &amp; rhs) const; // never throws
   };
 
   template&lt;class T, class U&gt;
@@ -187,6 +193,18 @@
   template&lt;class T, class U&gt;
     bool operator<(shared_ptr&lt;T&gt; const &amp; a, shared_ptr&lt;U&gt; const &amp; b); // never throws
 
+ template&lt;class T&gt;
+ bool operator==(shared_ptr&lt;T&gt; const &amp; p, std::nullptr_t); // never throws
+
+ template&lt;class T&gt;
+ bool operator==(std::nullptr_t, shared_ptr&lt;T&gt; const &amp; p); // never throws
+
+ template&lt;class T&gt;
+ bool operator!=(shared_ptr&lt;T&gt; const &amp; p, std::nullptr_t); // never throws
+
+ template&lt;class T&gt;
+ bool operator!=(std::nullptr_t, shared_ptr&lt;T&gt; const &amp; p); // never throws
+
   template&lt;class T&gt; void swap(shared_ptr&lt;T&gt; &amp; a, shared_ptr&lt;T&gt; &amp; b); // never throws
 
   template&lt;class T&gt; typename shared_ptr&lt;T&gt;::element_type * get_pointer(shared_ptr&lt;T&gt; const &amp; p); // never throws
@@ -217,7 +235,8 @@
                 and <code>U</code> when <code>T</code> is <code>U[]</code> or <code>U[N]</code>.</p>
                 </blockquote>
                 <h3 id="default_constructor">default constructor</h3>
- <pre>shared_ptr(); // never throws</pre>
+ <pre>shared_ptr(); // never throws
+shared_ptr(std::nullptr_t); // never throws</pre>
                 <blockquote>
                         <p><b>Effects:</b> Constructs an <em>empty</em> <code>shared_ptr</code>.</p>
                         <p><b>Postconditions:</b> <code>use_count() == 0 &amp;&amp; get() == 0</code>.</p>
@@ -260,7 +279,9 @@
                                 not have a virtual destructor, or is <code>void</code>.]</em></p>
                 <h3 id="deleter_constructor">constructors taking a deleter</h3>
                 <pre>template&lt;class Y, class D&gt; shared_ptr(Y * p, D d);
-template&lt;class Y, class D, class A&gt; shared_ptr(Y * p, D d, A a);</pre>
+template&lt;class Y, class D, class A&gt; shared_ptr(Y * p, D d, A a);
+template&lt;class D&gt; shared_ptr(std::nullptr_t p, D d);
+template&lt;class D, class A&gt; shared_ptr(std::nullptr_t p, D d, A a);</pre>
                 <blockquote>
                         <p><b>Requirements:</b>
                             <code>D</code> must be <code>CopyConstructible</code>. The copy constructor and destructor
@@ -273,8 +294,8 @@
                             otherwise, <code>Y*</code> must be convertible to <code>T*</code>.
                         </p>
                         <p><b>Effects:</b> Constructs a <code>shared_ptr</code> that <em>owns</em> the pointer <code>
- p</code> and the deleter <code>d</code>. The second constructor allocates
- memory using a copy of <code>a</code>.</p>
+ p</code> and the deleter <code>d</code>. The constructors taking an allocator <code>a</code>
+ allocate memory using a copy of <code>a</code>.</p>
                         <p><b>Postconditions:</b> <code>use_count() == 1 &amp;&amp; get() == p</code>.</p>
                         <p><b>Throws:</b> <code>std::bad_alloc</code>, or an implementation-defined
                                 exception when a resource other than memory could not be obtained.</p>
@@ -350,8 +371,8 @@
                 <blockquote>
                         <p><b>Requires:</b> <code>Y*</code> should be convertible to <code>T*</code>.</p>
                         <p><b>Effects:</b>
- Equivalent to <code>shared_ptr( r.release(), r.get_deleter() )</code> when <code>D</code> is not a reference type.
- Otherwise, equivalent to <code>shared_ptr( r.release(), <em>del</em> )</code>, where <em>del</em> is a deleter
+ Equivalent to <code>shared_ptr(r.release(), r.get_deleter())</code> when <code>D</code> is not a reference type.
+ Otherwise, equivalent to <code>shared_ptr(r.release(), <em>del</em>)</code>, where <em>del</em> is a deleter
                             that stores the reference <code>rd</code> returned from <code>r.get_deleter()</code> and <code>del(p)</code> calls <code>rd(p)</code>.</p>
                         <p><b>Postconditions:</b> <code>use_count() == 1</code>.</p>
                         <p><b>Throws:</b> <code>std::bad_alloc</code>, or an implementation-defined
@@ -401,7 +422,12 @@
 template&lt;class Y&gt; shared_ptr &amp; operator=(std::auto_ptr&lt;Y&gt; &amp;&amp; r);
 template&lt;class Y, class D&gt; shared_ptr &amp; operator=(std::unique_ptr&lt;Y, D&gt; &amp;&amp; r);</pre>
                 <blockquote>
- <p><b>Effects:</b> Equivalent to <code>shared_ptr( std::move(r) ).swap(*this)</code>.</p>
+ <p><b>Effects:</b> Equivalent to <code>shared_ptr(std::move(r)).swap(*this)</code>.</p>
+ <p><b>Returns:</b> <code>*this</code>.</p>
+ </blockquote>
+ <pre>shared_ptr &amp; operator=(std::nullptr_t); // never throws</pre>
+ <blockquote>
+ <p><b>Effects:</b> Equivalent to <code>shared_ptr().swap(*this)</code>.</p>
                         <p><b>Returns:</b> <code>*this</code>.</p>
                 </blockquote>
                 <h3 id="reset">reset</h3>
@@ -438,11 +464,11 @@
                         <p><b>Returns:</b> the stored pointer.</p>
                         <p><b>Throws:</b> nothing.</p>
                 </blockquote>
- <pre>element_type &amp; operator[]( std::ptrdiff_t i ) const; // never throws</pre>
+ <pre>element_type &amp; operator[](std::ptrdiff_t i) const; // never throws</pre>
                 <blockquote>
                         <p><b>Requirements:</b> <code>T</code> should be an array type. The stored pointer must not be 0.
                             <code>i &gt;= 0</code>. If <code>T</code> is <code>U[N]</code>, <code>i &lt; N</code>.</p>
- <p><b>Returns:</b> <code>get()[ i ]</code>.</p>
+ <p><b>Returns:</b> <code>get()[i]</code>.</p>
                         <p><b>Throws:</b> nothing.</p>
                 </blockquote>
                 <h3 id="get">get</h3>
@@ -471,15 +497,12 @@
                                 for debugging and testing purposes, not for production code.</p>
                 </blockquote>
                 <h3 id="conversions">conversions</h3>
- <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
+ <pre>explicit operator bool() const; // never throws</pre>
                 <blockquote>
- <p><b>Returns:</b> an unspecified value that, when used in boolean contexts, is
- equivalent to <code>get() != 0</code>.</p>
+ <p><b>Returns:</b> <code>get() != 0</code>.</p>
                         <p><b>Throws:</b> nothing.</p>
                         <p><b>Notes:</b> This conversion operator allows <code>shared_ptr</code> objects to be
- used in boolean contexts, like <code>if (p &amp;&amp; p-&gt;valid()) {}</code>.
- The actual target type is typically a pointer to a member function, avoiding
- many of the implicit conversion pitfalls.</p>
+ used in boolean contexts, like <code>if(p &amp;&amp; p-&gt;valid()) {}</code>.</p>
                 </blockquote>
                 <p><em>[The conversion to bool is not merely syntactic sugar. It allows <code>shared_ptr</code>s
                                 to be declared in conditions when using dynamic_pointer_cast
@@ -490,6 +513,13 @@
                         <p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
                         <p><b>Throws:</b> nothing.</p>
                 </blockquote>
+ <h3 id="owner_before">swap</h3>
+ <pre>template&lt;class Y&gt; bool owner_before(shared_ptr&lt;Y&gt; const &amp; rhs) const; // never throws
+template&lt;class Y&gt; bool owner_before(weak_ptr&lt;Y&gt; const &amp; rhs) const; // never throws</pre>
+ <blockquote>
+ <p><b>Effects:</b> See the description of operator<.</p>
+ <p><b>Throws:</b> nothing.</p>
+ </blockquote>
                 <h2 id="functions">Free Functions</h2>
                 <h3 id="comparison">comparison</h3>
                 <pre>template&lt;class T, class U&gt;
@@ -504,6 +534,22 @@
                         <p><b>Returns:</b> <code>a.get() != b.get()</code>.</p>
                         <p><b>Throws:</b> nothing.</p>
                 </blockquote>
+ <pre>template&lt;class T&gt;
+ bool operator==(shared_ptr&lt;T&gt; const &amp; p, std::nullptr_t); // never throws
+template&lt;class T&gt;
+ bool operator==(std::nullptr_t, shared_ptr&lt;T&gt; const &amp; p); // never throws</pre>
+ <blockquote>
+ <p><b>Returns:</b> <code>p.get() == 0</code>.</p>
+ <p><b>Throws:</b> nothing.</p>
+ </blockquote>
+ <pre>template&lt;class T&gt;
+ bool operator!=(shared_ptr&lt;T&gt; const &amp; p, std::nullptr_t); // never throws
+template&lt;class T&gt;
+ bool operator!=(std::nullptr_t, shared_ptr&lt;T&gt; const &amp; p); // never throws</pre>
+ <blockquote>
+ <p><b>Returns:</b> <code>p.get() != 0</code>.</p>
+ <p><b>Throws:</b> nothing.</p>
+ </blockquote>
                 <pre>template&lt;class T, class U&gt;
   bool operator&lt;(shared_ptr&lt;T&gt; const &amp; a, shared_ptr&lt;U&gt; const &amp; b); // never throws</pre>
                 <blockquote>
@@ -743,7 +789,7 @@
                 <p>
                         <b>A.</b> Automatic conversion is believed to be too error prone.
                 </p>
- <p><b>Q.</b> Why does <code>shared_ptr</code> supply use_count()?</p>
+ <p><b>Q.</b> Why does <code>shared_ptr</code> supply <code>use_count()</code>?</p>
                 <p>
                         <b>A.</b> As an aid to writing test cases and debugging displays. One of the
                         progenitors had <code>use_count()</code>, and it was useful in tracking down bugs in a
@@ -783,7 +829,7 @@
                 </p>
                 <hr />
                 <p><small>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
- Copyright 2002-2005, 2012 Peter Dimov. Distributed under the Boost Software License,
+ Copyright 2002-2005, 2012, 2013 Peter Dimov. Distributed under the Boost Software License,
                                 Version 1.0. See accompanying file LICENSE_1_0.txt
                                 or copy at http://www.boost.org/LICENSE_1_0.txt.</small></p>
         </body>


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk