diff --git a/doc/smart_ptr/scoped_array.adoc b/doc/smart_ptr/scoped_array.adoc index 3fbc835..7a755c7 100644 --- a/doc/smart_ptr/scoped_array.adoc +++ b/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` 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` 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 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 void swap(scoped_array & a, scoped_array & b) noexcept; + +template bool operator==( scoped_array const & p, std::nullptr_t ) noexcept; +template bool operator==( std::nullptr_t, scoped_array const & p ) noexcept; + +template bool operator!=( scoped_array const & p, std::nullptr_t ) noexcept; +template bool operator!=( std::nullptr_t, scoped_array 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 void swap(scoped_array & a, scoped_array & b) noexcept; + +Equivalent to `a.swap(b)`. + +### comparisons + + template bool operator==( scoped_array const & p, std::nullptr_t ) noexcept; + + template bool operator==( std::nullptr_t, scoped_array const & p ) noexcept; + +Returns `p.get() == nullptr`. + + template bool operator!=( scoped_array const & p, std::nullptr_t ) noexcept; + + template bool operator!=( std::nullptr_t, scoped_array const & p ) noexcept; + +Returns `p.get() != nullptr`. diff --git a/doc/smart_ptr/scoped_ptr.adoc b/doc/smart_ptr/scoped_ptr.adoc index d60df72..dcd616c 100644 --- a/doc/smart_ptr/scoped_ptr.adoc +++ b/doc/smart_ptr/scoped_ptr.adoc @@ -75,6 +75,12 @@ public: template void swap(scoped_ptr & a, scoped_ptr & b) noexcept; +template bool operator==( scoped_ptr const & p, std::nullptr_t ) noexcept; +template bool operator==( std::nullptr_t, scoped_ptr const & p ) noexcept; + +template bool operator!=( scoped_ptr const & p, std::nullptr_t ) noexcept; +template bool operator!=( std::nullptr_t, scoped_ptr 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 bool operator==( scoped_ptr const & p, std::nullptr_t ) noexcept; + + template bool operator==( std::nullptr_t, scoped_ptr const & p ) noexcept; + +Returns `p.get() == nullptr`. + + template bool operator!=( scoped_ptr const & p, std::nullptr_t ) noexcept; + + template bool operator!=( std::nullptr_t, scoped_ptr const & p ) noexcept; + +Returns `p.get() != nullptr`. + ## Example Here's an example that uses `scoped_ptr`.