1//// 2Copyright 1999 Greg Colvin and Beman Dawes 3Copyright 2002 Darin Adler 4Copyright 2002-2005, 2017 Peter Dimov 5 6Distributed under the Boost Software License, Version 1.0. 7 8See accompanying file LICENSE_1_0.txt or copy at 9http://www.boost.org/LICENSE_1_0.txt 10//// 11 12[#scoped_array] 13# scoped_array: Scoped Array Ownership 14:toc: 15:toc-title: 16:idprefix: scoped_array_ 17 18## Description 19 20The `scoped_array` class template stores a pointer to a dynamically allocated array. 21(Dynamically allocated arrays are allocated with the {cpp} `new[]` expression.) The array 22pointed to is guaranteed to be deleted, either on destruction of the `scoped_array`, 23or via an explicit `reset`. 24 25The `scoped_array` template is a simple solution for simple needs. It supplies a basic 26"resource acquisition is initialization" facility, without shared-ownership or 27transfer-of-ownership semantics. Both its name and enforcement of semantics 28(by being noncopyable) signal its intent to retain ownership solely within the current scope. 29Because it is noncopyable, it is safer than `shared_ptr<T[]>` for pointers which should not be copied. 30 31Because `scoped_array` is so simple, in its usual implementation every operation is as fast as a 32built-in array pointer and it has no more space overhead that a built-in array pointer. 33 34It cannot be used in {cpp} standard library containers. See `shared_ptr<T[]>` if `scoped_array` 35does not meet your needs. 36 37It cannot correctly hold a pointer to a single object. See `scoped_ptr` for that usage. 38 39`std::vector` is an alternative to `scoped_array` that is a bit heavier duty but far more flexible. 40`boost::array` is an alternative that does not use dynamic allocation. 41 42The class template is parameterized on `T`, the type of the object pointed to. 43 44## Synopsis 45 46`scoped_array` is defined in `<boost/smart_ptr/scoped_array.hpp>`. 47 48``` 49namespace boost { 50 51 template<class T> class scoped_array { 52 private: 53 54 scoped_array(scoped_array const &); 55 scoped_array & operator=(scoped_array const &); 56 57 void operator==( scoped_array const& ) const; 58 void operator!=( scoped_array const& ) const; 59 60 public: 61 62 typedef T element_type; 63 64 explicit scoped_array(T * p = 0) noexcept; 65 ~scoped_array() noexcept; 66 67 void reset(T * p = 0) noexcept; 68 69 T & operator[](std::ptrdiff_t i) const noexcept; 70 T * get() const noexcept; 71 72 explicit operator bool () const noexcept; 73 74 void swap(scoped_array & b) noexcept; 75 }; 76 77 template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b) noexcept; 78 79 template<class T> 80 bool operator==( scoped_array<T> const & p, std::nullptr_t ) noexcept; 81 template<class T> 82 bool operator==( std::nullptr_t, scoped_array<T> const & p ) noexcept; 83 84 template<class T> 85 bool operator!=( scoped_array<T> const & p, std::nullptr_t ) noexcept; 86 template<class T> 87 bool operator!=( std::nullptr_t, scoped_array<T> const & p ) noexcept; 88} 89``` 90 91## Members 92 93### element_type 94 95 typedef T element_type; 96 97Provides the type of the stored pointer. 98 99### constructors 100 101 explicit scoped_array(T * p = 0) noexcept; 102 103Constructs a `scoped_array`, storing a copy of `p`, which must have been 104allocated via a {cpp} `new[]` expression or be 0. `T` is not required be a complete type. 105 106### destructor 107 108 ~scoped_array() noexcept; 109 110Deletes the array pointed to by the stored pointer. Note that `delete[]` on a pointer with 111a value of 0 is harmless. `T` must be complete, and `delete[]` on the stored pointer must 112not throw exceptions. 113 114### reset 115 116 void reset(T * p = 0) noexcept; 117 118Deletes the array pointed to by the stored pointer and then stores a copy of `p`, 119which must have been allocated via a {cpp} `new[]` expression or be 0. `T` must be complete, 120and `delete[]` on the stored pointer must not throw exceptions. 121 122### subscripting 123 124 T & operator[](std::ptrdiff_t i) const noexcept; 125 126Returns a reference to element `i` of the array pointed to by the stored pointer. 127Behavior is undefined and almost certainly undesirable if the stored pointer is 0, 128or if `i` is less than 0 or is greater than or equal to the number of elements in 129the array. 130 131### get 132 133 T * get() const noexcept; 134 135Returns the stored pointer. `T` need not be a complete type. 136 137### conversions 138 139 explicit operator bool () const noexcept; 140 141Returns `get() != 0`. 142 143NOTE: On C++03 compilers, the return value is of an unspecified type. 144 145### swap 146 147 void swap(scoped_array & b) noexcept; 148 149Exchanges the contents of the two smart pointers. `T` need not be a complete type. 150 151## Free Functions 152 153### swap 154 155 template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b) noexcept; 156 157Equivalent to `a.swap(b)`. 158 159### comparisons 160 161 template<class T> 162 bool operator==( scoped_array<T> const & p, std::nullptr_t ) noexcept; 163 164 template<class T> 165 bool operator==( std::nullptr_t, scoped_array<T> const & p ) noexcept; 166 167Returns `p.get() == nullptr`. 168 169 template<class T> 170 bool operator!=( scoped_array<T> const & p, std::nullptr_t ) noexcept; 171 172 template<class T> 173 bool operator!=( std::nullptr_t, scoped_array<T> const & p ) noexcept; 174 175Returns `p.get() != nullptr`. 176