Add scoped_array.adoc

doc/smart_ptr/scoped_array.adoc

@@ -1,5 +1,7 @@
 ////
-Copyright 2017 Peter Dimov
+Copyright 1999 Greg Colvin and Beman Dawes
+Copyright 2002 Darin Adler
+Copyright 2002-2005, 2017 Peter Dimov
 
 Distributed under the Boost Software License, Version 1.0.
 
@@ -13,3 +15,154 @@ http://www.boost.org/LICENSE_1_0.txt
 :toc-title:
 :idprefix: scoped_array_
 
+## Description
+
+The `scoped_array` class template stores a pointer to a dynamically allocated array.
+(Dynamically allocated arrays are allocated with the {cpp} `new[]` expression.) The array
+pointed to is guaranteed to be deleted, either on destruction of the `scoped_array`,
+or via an explicit `reset`.
+
+The `scoped_array` 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  noncopyable) signal its intent to retain ownership solely within the current scope.
+Because it is noncopyable, it is safer than `shared_ptr<T[]>` for pointers which should not be copied.
+
+Because `scoped_array` 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.
+
+It cannot be used in {cpp} standard library containers. See `shared_ptr<T[]>` if `scoped_array`
+does not meet your needs.
+
+It cannot correctly hold a pointer to a single object. See `scoped_ptr` for that usage.
+
+`std::vector` is an alternative to `scoped_array` that is a bit heavier duty but far more flexible.
+`boost::array` is an alternative that does not use dynamic allocation.
+
+The class template is parameterized on `T`, the type of the object pointed to.
+
+## Synopsis
+
+```
+namespace boost
+{
+
+template<class T> class scoped_array
+{
+private:
+
+    scoped_array(scoped_array const &);
+    scoped_array & operator=(scoped_array const &);
+
+    void operator==( scoped_array const& ) const;
+    void operator!=( scoped_array const& ) const;
+
+public:
+
+    typedef T element_type;
+
+    explicit scoped_array(T * p = 0) noexcept;
+    ~scoped_array() noexcept;
+
+    void reset(T * p = 0) noexcept;
+
+    T & operator[](std::ptrdiff_t i) const noexcept;
+    T * get() const noexcept;
+
+    explicit operator bool () const noexcept;
+
+    void swap(scoped_array & b) noexcept;
+};
+
+template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b) noexcept;
+
+template<class T> bool operator==( scoped_array<T> const & p, std::nullptr_t ) noexcept;
+template<class T> bool operator==( std::nullptr_t, scoped_array<T> const & p ) noexcept;
+
+template<class T> bool operator!=( scoped_array<T> const & p, std::nullptr_t ) noexcept;
+template<class T> bool operator!=( std::nullptr_t, scoped_array<T> const & p ) noexcept;
+
+} // namespace boost
+```
+
+## Members
+
+### element_type
+
+    typedef T element_type;
+
+Provides the type of the stored pointer.
+
+### constructors
+
+    explicit scoped_array(T * p = 0) noexcept;
+
+Constructs a `scoped_array`, storing a copy of `p`, which must have been
+allocated via a {cpp} `new[]` expression or be 0. `T` is not required be a complete type.
+
+### destructor
+
+    ~scoped_array() noexcept;
+
+Deletes the array pointed to by the stored pointer. Note that `delete[]` on a pointer with
+a value of 0 is harmless. `T` must be complete, and `delete[]` on the stored pointer must
+not throw exceptions.
+
+### reset
+
+    void reset(T * p = 0) noexcept;
+
+Deletes the array pointed to by the stored pointer and then stores a copy of `p`,
+which must have been allocated via a {cpp} `new[]` expression or be 0. `T` must be complete,
+and `delete[]` on the stored pointer must not throw exceptions.
+
+### subscripting
+
+    T & operator[](std::ptrdiff_t i) const noexcept;
+
+Returns a reference to element `i` of the array pointed to by the stored pointer.
+Behavior is undefined and almost certainly undesirable if the stored pointer is 0,
+or if `i` is less than 0 or is greater than or equal to the number of elements in
+the array.
+
+### get
+
+    T * get() const noexcept;
+
+Returns the stored pointer. `T` need not be a complete type.
+
+### conversions
+
+    explicit operator bool () const noexcept;
+
+Returns `get() != 0`.
+
+NOTE: On C++03 compilers, the return value is of an unspecified type.
+
+### swap
+
+    void swap(scoped_array & b) noexcept;
+
+Exchanges the contents of the two smart pointers. `T` need not be a complete type.
+
+## Free Functions
+
+### swap
+
+    template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b) noexcept;
+
+Equivalent to `a.swap(b)`.
+
+### comparisons
+
+    template<class T> bool operator==( scoped_array<T> const & p, std::nullptr_t ) noexcept;
+
+    template<class T> bool operator==( std::nullptr_t, scoped_array<T> const & p ) noexcept;
+
+Returns `p.get() == nullptr`.
+
+    template<class T> bool operator!=( scoped_array<T> const & p, std::nullptr_t ) noexcept;
+
+    template<class T> bool operator!=( std::nullptr_t, scoped_array<T> const & p ) noexcept;
+
+Returns `p.get() != nullptr`.

doc/smart_ptr/scoped_ptr.adoc

@@ -75,6 +75,12 @@ public:
 
 template<class T> void swap(scoped_ptr<T> & a, scoped_ptr<T> & b) noexcept;
 
+template<class T> bool operator==( scoped_ptr<T> const & p, std::nullptr_t ) noexcept;
+template<class T> bool operator==( std::nullptr_t, scoped_ptr<T> const & p ) noexcept;
+
+template<class T> bool operator!=( scoped_ptr<T> const & p, std::nullptr_t ) noexcept;
+template<class T> bool operator!=( std::nullptr_t, scoped_ptr<T> const & p ) noexcept;
+
 } // namespace boost
 ```
 
@@ -131,6 +137,8 @@ Returns the stored pointer. `T` need not be a complete type.
 
 Returns `get() != 0`.
 
+NOTE: On C++03 compilers, the return value is of an unspecified type.
+
 ### swap
 
     void swap(scoped_ptr & b) noexcept;
@@ -145,6 +153,20 @@ Exchanges the contents of the two smart pointers. `T` need not be a complete typ
 
 Equivalent to `a.swap(b)`.
 
+### comparisons
+
+    template<class T> bool operator==( scoped_ptr<T> const & p, std::nullptr_t ) noexcept;
+
+    template<class T> bool operator==( std::nullptr_t, scoped_ptr<T> const & p ) noexcept;
+
+Returns `p.get() == nullptr`.
+
+    template<class T> bool operator!=( scoped_ptr<T> const & p, std::nullptr_t ) noexcept;
+
+    template<class T> bool operator!=( std::nullptr_t, scoped_ptr<T> const & p ) noexcept;
+
+Returns `p.get() != nullptr`.
+
 ## Example
 
 Here's an example that uses `scoped_ptr`.