| //// |
| 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. |
| |
| See accompanying file LICENSE_1_0.txt or copy at |
| http://www.boost.org/LICENSE_1_0.txt |
| //// |
| |
| [#scoped_array] |
| # scoped_array: Scoped Array Ownership |
| :toc: |
| :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 |
| |
| `scoped_array` is defined in `<boost/smart_ptr/scoped_array.hpp>`. |
| |
| ``` |
| 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; |
| } |
| ``` |
| |
| ## 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`. |