Boost-Commit :

Date view	Thread view	Subject view	Author view

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."
 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.
+ 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.
 <code>shared_ptr<T></code> can be implicitly converted to <code>shared_ptr</code>
 whenever <code>T*</code> can be implicitly converted to <code>U*</code>.
 In particular, <code>shared_ptr<T></code> is implicitly convertible
@@ -119,10 +120,13 @@
 typedef see below element_type;

 <a href="#default_constructor" >shared_ptr</a>(); // never throws
+ shared_ptr(std::nullptr_t); // never throws

 template<class Y> explicit shared_ptr(Y * p);
 template<class Y, class D> shared_ptr(Y * p, D d);
 template<class Y, class D, class A> shared_ptr(Y * p, D d, A a);
+ template<class D> shared_ptr(std::nullptr_t p, D d);
+ template<class D, class A> shared_ptr(std::nullptr_t p, D d, A a);

 <a href="#destructor" >~shared_ptr</a>(); // never throws

@@ -152,6 +156,8 @@

 template<class Y, class D> shared_ptr & operator=(std::unique_ptr<Y, D> && r);

+ shared_ptr & operator=(std::nullptr_t); // never throws
+
 void reset(); // never throws

 template<class Y> void reset(Y * p);
@@ -163,19 +169,19 @@
 T & 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 & operator[]( std::ptrdiff_t i ) const; // never throws; only valid when T is an array type
+ element_type & 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 & b); // never throws

- template<class Y> bool owner_before( shared_ptr<Y> const & rhs ) const; // never throws
- template<class Y> bool owner_before( weak_ptr<Y> const & rhs ) const; // never throws
+ template<class Y> bool owner_before(shared_ptr<Y> const & rhs) const; // never throws
+ template<class Y> bool owner_before(weak_ptr<Y> const & rhs) const; // never throws
 };

 template<class T, class U>
@@ -187,6 +193,18 @@
 template<class T, class U>
 bool operator<(shared_ptr<T> const & a, shared_ptr const & b); // never throws

+ template<class T>
+ bool operator==(shared_ptr<T> const & p, std::nullptr_t); // never throws
+
+ template<class T>
+ bool operator==(std::nullptr_t, shared_ptr<T> const & p); // never throws
+
+ template<class T>
+ bool operator!=(shared_ptr<T> const & p, std::nullptr_t); // never throws
+
+ template<class T>
+ bool operator!=(std::nullptr_t, shared_ptr<T> const & p); // never throws
+
 template<class T> void swap(shared_ptr<T> & a, shared_ptr<T> & b); // never throws

 template<class T> typename shared_ptr<T>::element_type * get_pointer(shared_ptr<T> const & p); // never throws
@@ -217,7 +235,8 @@
 and <code>U</code> when <code>T</code> is <code>U[]</code> or <code>U[N]</code>.
 </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>
 Effects: Constructs an empty <code>shared_ptr</code>.
 Postconditions: <code>use_count() == 0 && get() == 0</code>.
@@ -260,7 +279,9 @@
 not have a virtual destructor, or is <code>void</code>.]
 <h3 id="deleter_constructor">constructors taking a deleter</h3>
 <pre>template<class Y, class D> shared_ptr(Y * p, D d);
-template<class Y, class D, class A> shared_ptr(Y * p, D d, A a);</pre>
+template<class Y, class D, class A> shared_ptr(Y * p, D d, A a);
+template<class D> shared_ptr(std::nullptr_t p, D d);
+template<class D, class A> shared_ptr(std::nullptr_t p, D d, A a);</pre>
 <blockquote>
 Requirements:
 <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>.
 
 Effects: Constructs a <code>shared_ptr</code> that owns the pointer <code>
- p</code> and the deleter <code>d</code>. The second constructor allocates
- memory using a copy of <code>a</code>.
+ 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>.
 Postconditions: <code>use_count() == 1 && get() == p</code>.
 Throws: <code>std::bad_alloc</code>, or an implementation-defined
 exception when a resource other than memory could not be obtained.
@@ -350,8 +371,8 @@
 <blockquote>
 Requires: <code>Y*</code> should be convertible to <code>T*</code>.
 Effects:
- 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(), del )</code>, where del 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(), del)</code>, where del 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>.
 Postconditions: <code>use_count() == 1</code>.
 Throws: <code>std::bad_alloc</code>, or an implementation-defined
@@ -401,7 +422,12 @@
template<class Y> shared_ptr & operator=(std::auto_ptr<Y> && r);
template<class Y, class D> shared_ptr & operator=(std::unique_ptr<Y, D> && r);</pre>
 <blockquote>
- Effects: Equivalent to <code>shared_ptr( std::move(r) ).swap(*this)</code>.
+ Effects: Equivalent to <code>shared_ptr(std::move(r)).swap(*this)</code>.
+ Returns: <code>*this</code>.
+ </blockquote>
+ <pre>shared_ptr & operator=(std::nullptr_t); // never throws</pre>
+ <blockquote>
+ Effects: Equivalent to <code>shared_ptr().swap(*this)</code>.
 Returns: <code>*this</code>.
 </blockquote>
 <h3 id="reset">reset</h3>
@@ -438,11 +464,11 @@
 Returns: the stored pointer.
 Throws: nothing.
 </blockquote>
- <pre>element_type & operator[]( std::ptrdiff_t i ) const; // never throws</pre>
+ <pre>element_type & operator[](std::ptrdiff_t i) const; // never throws</pre>
 <blockquote>
 Requirements: <code>T</code> should be an array type. The stored pointer must not be 0.
 <code>i >= 0</code>. If <code>T</code> is <code>U[N]</code>, <code>i < N</code>.
- Returns: <code>get()[ i ]</code>.
+ Returns: <code>get()[i]</code>.
 Throws: nothing.
 </blockquote>
 <h3 id="get">get</h3>
@@ -471,15 +497,12 @@
 for debugging and testing purposes, not for production code.
 </blockquote>
 <h3 id="conversions">conversions</h3>
- <pre>operator unspecified-bool-type () const; // never throws</pre>
+ <pre>explicit operator bool() const; // never throws</pre>
 <blockquote>
- Returns: an unspecified value that, when used in boolean contexts, is
- equivalent to <code>get() != 0</code>.
+ Returns: <code>get() != 0</code>.
 Throws: nothing.
 Notes: This conversion operator allows <code>shared_ptr</code> objects to be
- used in boolean contexts, like <code>if (p && p->valid()) {}</code>.
- The actual target type is typically a pointer to a member function, avoiding
- many of the implicit conversion pitfalls.
+ used in boolean contexts, like <code>if(p && p->valid()) {}</code>.
 </blockquote>
 [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 @@
 Effects: Exchanges the contents of the two smart pointers.
 Throws: nothing.
 </blockquote>
+ <h3 id="owner_before">swap</h3>
+ <pre>template<class Y> bool owner_before(shared_ptr<Y> const & rhs) const; // never throws
+template<class Y> bool owner_before(weak_ptr<Y> const & rhs) const; // never throws</pre>
+ <blockquote>
+ Effects: See the description of operator<.
+ Throws: nothing.
+ </blockquote>
 <h2 id="functions">Free Functions</h2>
 <h3 id="comparison">comparison</h3>
 <pre>template<class T, class U>
@@ -504,6 +534,22 @@
 Returns: <code>a.get() != b.get()</code>.
 Throws: nothing.
 </blockquote>
+ <pre>template<class T>
+ bool operator==(shared_ptr<T> const & p, std::nullptr_t); // never throws
+template<class T>
+ bool operator==(std::nullptr_t, shared_ptr<T> const & p); // never throws</pre>
+ <blockquote>
+ Returns: <code>p.get() == 0</code>.
+ Throws: nothing.
+ </blockquote>
+ <pre>template<class T>
+ bool operator!=(shared_ptr<T> const & p, std::nullptr_t); // never throws
+template<class T>
+ bool operator!=(std::nullptr_t, shared_ptr<T> const & p); // never throws</pre>
+ <blockquote>
+ Returns: <code>p.get() != 0</code>.
+ Throws: nothing.
+ </blockquote>
 <pre>template<class T, class U>
 bool operator<(shared_ptr<T> const & a, shared_ptr const & b); // never throws</pre>
 <blockquote>
@@ -743,7 +789,7 @@
 
 A. Automatic conversion is believed to be too error prone.
 
- Q. Why does <code>shared_ptr</code> supply use_count()?
+ Q. Why does <code>shared_ptr</code> supply <code>use_count()</code>?
 
 A. 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 @@
 
 <hr />
 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.
 </body>

Date view	Thread view	Subject view	Author view

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