boost.png (6897 bytes)scoped_array class template

The scoped_array class template stores a pointer to a dynamically allocated array. (Dynamically allocated arrays are allocated with the C++ 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_array 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 C++ standard library containers. See shared_array if scoped_array does not meet your needs.

It cannot correctly hold a pointer to a single object. See scoped_ptr for that usage.

A std::vector is an alternative to a scoped_array that is a bit heavier duty but far more flexible. A 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. T must meet the smart pointer common requirements.

Synopsis

namespace boost {

  template<class T> class scoped_array : noncopyable {

    public:
      typedef T element_type;

      explicit scoped_array(T * p = 0); // never throws
      ~scoped_array(); // never throws

      void reset(T * p = 0); // never throws

      T & operator[](std::ptrdiff_t i) const; // never throws
      T * get() const; // never throws
     
      operator unspecified-bool-type() const; // never throws

      void swap(scoped_array & b); // never throws
  };

  template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws

}

Members

element_type

typedef T element_type;

Provides the type of the stored pointer.

constructors

explicit scoped_array(T * p = 0); // never throws

Constructs a scoped_array, storing a copy of p, which must have been allocated via a C++ new[] expression or be 0. T is not required be a complete type. See the smart pointer common requirements.

destructor

~scoped_array(); // never throws

Deletes the array pointed to by the stored pointer. Note that delete[] on a pointer with a value of 0 is harmless. The guarantee that this does not throw exceptions depends on the requirement that the deleted array's objects' destructors do not throw exceptions. See the smart pointer common requirements.

reset

void reset(T * p = 0); // never throws

Deletes the array pointed to by the stored pointer and then stores a copy of p, which must have been allocated via a C++ new[] expression or be 0. The guarantee that this does not throw exceptions depends on the requirement that the deleted array's objects' destructors do not throw exceptions. See the smart pointer common requirements.

subscripting

T & operator[](std::ptrdiff_t i) const; // never throws

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; // never throws

Returns the stored pointer. T need not be a complete type. See the smart pointer common requirements.

conversions

operator unspecified-bool-type () const; // never throws

Returns an unspecified value that, when used in boolean contexts, is equivalent to get() != 0.

swap

void swap(scoped_array & b); // never throws

Exchanges the contents of the two smart pointers. T need not be a complete type. See the smart pointer common requirements.

Free Functions

swap

template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws

Equivalent to a.swap(b). Matches the interface of std::swap. Provided as an aid to generic programming.


Revised 09 January 2003

Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. Copyright 2002-2005 Peter Dimov. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.