Teuchos::ArrayRefCountPtr< T > Class Template Reference
[Teuchos Memory Management Utilities]

Array reference-counted pointer class. More...

#include <Teuchos_ArrayRefCountPtrDecl.hpp>

List of all members.

Public Types

Public types

typedef T element_type

typedef Teuchos_Index Ordinal

Public Member Functions

Constructors/Initializers

ArrayRefCountPtr (ENull null_arg=null)

Initialize ArrayRefCountPtr<T> to NULL.

ArrayRefCountPtr (const ArrayRefCountPtr< T > &r_ptr)

Initialize from another ArrayRefCountPtr<T> object.

~ArrayRefCountPtr ()

Removes a reference to a dynamically allocated array and possibly deletes the array if owned.

ArrayRefCountPtr< T > & operator= (const ArrayRefCountPtr< T > &r_ptr)

Copy the pointer to the referenced array and increment the reference count.

Object/Pointer Access Functions

T * operator-> () const

Pointer (->) access to members of underlying object for current position.

T & operator * () const

Dereference the underlying object for the current pointer position.

T * get () const

Get the raw C++ pointer to the underlying object.

T & operator[] (Ordinal offset) const

Random object access.

Pointer Arithmetic Functions

ArrayRefCountPtr< T > & operator++ ()

Prefix increment of pointer (i.e. ++ptr).

ArrayRefCountPtr< T > operator++ (int)

Postfix increment of pointer (i.e. ptr++).

ArrayRefCountPtr< T > & operator-- ()

Prefix deincrement of pointer (i.e. --ptr).

ArrayRefCountPtr< T > operator-- (int)

Postfix deincrement of pointer (i.e. ptr--).

ArrayRefCountPtr< T > & operator+= (Ordinal offset)

Pointer integer increment (i.e. ptr+=offset).

ArrayRefCountPtr< T > & operator-= (Ordinal offset)

Pointer integer increment (i.e. ptr-=offset).

ArrayRefCountPtr< T > operator+ (Ordinal offset) const

Pointer integer increment (i.e. ptr+offset).

ArrayRefCountPtr< T > operator- (Ordinal offset) const

Pointer integer deincrement (i.e. ptr-offset).

Views

ArrayRefCountPtr< const T > getConst () const

Return object for only const access to data.

ArrayRefCountPtr< T > subview (Ordinal lowerOffset, Ordinal size) const

Return a view of a contiguous range of elements.

General query functions

int count () const

Return the number of ArrayRefCountPtr<> objects that have a reference to the underlying pointer that is being shared.

template<class T2>

bool shares_resource (const ArrayRefCountPtr< T2 > &r_ptr) const

Returns true if the smart pointers share the same underlying reference-counted object.

Ordinal lowerOffset () const

Return the lower offset to valid data.

Ordinal upperOffset () const

Return the upper offset to valid data.

Ordinal size () const

The total number of items in the managed array (i.e. upperOffset()-lowerOffset()+1).

Standard Container-Like Functions

const_iterator begin () const

Return an iterator to beginning of the array of data.

const_iterator end () const

Return an iterator to past the end of the array of data.

Ownership

T * release ()

Release the ownership of the underlying array.

void set_has_ownership ()

Give this and other ArrayRefCountPtr<> objects ownership of the underlying referenced array to delete it.

bool has_ownership () const

Returns true if this has ownership of object pointed to by this->get() in order to delete it.

Assertion Functions.

const ArrayRefCountPtr< T > & assert_not_null () const

Throws std::logic_error if this->get()==NULL, otherwise returns reference to *this.

const ArrayRefCountPtr< T > & assert_in_range (Ordinal lowerOffset, Ordinal size) const

Throws std::logic_error if this->get()==NULL orthis->get()!=NULL && (lowerOffset < this->lowerOffset() || this->upperOffset() < upperOffset, otherwise returns reference to *this.

Related Functions

(Note that these are not member functions.)

ArrayRefCountPtr< T > arcp (T *p, typename ArrayRefCountPtr< T >::Ordinal lowerOffset, typename ArrayRefCountPtr< T >::Ordinal size, bool owns_mem=true)

Wraps a preallocated array of data with the assumption to call the array version of delete.

ArrayRefCountPtr< T > arcp (T *p, typename ArrayRefCountPtr< T >::Ordinal lowerOffset, typename ArrayRefCountPtr< T >::Ordinal size, Dealloc_T dealloc, bool owns_mem)

Wraps a preallocated array of data and uses a templated deallocation strategy object to define deletion .

ArrayRefCountPtr< T > arcp (typename ArrayRefCountPtr< T >::Ordinal size)

Allocate a new array just given a dimension.

ArrayRefCountPtr< T > arcp (const RefCountPtr< std::vector< T > > &v)

Wrap an std::vector<T> object as an ArrayRefCountPtr<T> object.

ArrayRefCountPtr< const T > arcp (const RefCountPtr< const std::vector< T > > &v)

Wrap a const std::vector<T> object as an ArrayRefCountPtr<const T> object.

RefCountPtr< std::vector<
T > > get_std_vector (const ArrayRefCountPtr< T > &ptr)

Get an std::vector<T> object out of an ArrayRefCountPtr<T> object that was created using the arcp() above to wrap the vector in the first place..

RefCountPtr< const std::vector<
T > > get_std_vector (const ArrayRefCountPtr< const T > &ptr)

Get a const std::vector<T> object out of an ArrayRefCountPtr<const T> object that was created using the arcp() above to wrap the vector in the first place.

bool is_null (const ArrayRefCountPtr< T > &p)

Returns true if p.get()==NULL.

bool operator== (const ArrayRefCountPtr< T > &p, ENull)

Returns true if p.get()==NULL.

bool operator!= (const ArrayRefCountPtr< T > &p, ENull)

Returns true if p.get()!=NULL.

bool operator== (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool operator!= (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool operator< (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool operator<= (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool operator> (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool operator>= (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

ArrayRefCountPtr< T2 > arcp_reinterpret_cast (const ArrayRefCountPtr< T1 > &p1)

Reinterpret cast of underlying ArrayRefCountPtr type from T1* to T2*.

ArrayRefCountPtr< T2 > arcp_implicit_cast (const ArrayRefCountPtr< T1 > &p1)

Implicit case the underlying ArrayRefCountPtr type from T1* to T2*.

void set_extra_data (const T1 &extra_data, const std::string &name, ArrayRefCountPtr< T2 > *p, EPrePostDestruction destroy_when=POST_DESTROY, bool force_unique=true)

Set extra data associated with a ArrayRefCountPtr object.

T1 & get_extra_data (ArrayRefCountPtr< T2 > &p, const std::string &name)

Get a non-const reference to extra data associated with a ArrayRefCountPtr object.

const T1 & get_extra_data (const ArrayRefCountPtr< T2 > &p, const std::string &name)

Get a const reference to extra data associated with a ArrayRefCountPtr object.

T1 * get_optional_extra_data (ArrayRefCountPtr< T2 > &p, const std::string &name)

Get a pointer to non-const extra data (if it exists) associated with a ArrayRefCountPtr object.

const T1 * get_optional_extra_data (const ArrayRefCountPtr< T2 > &p, const std::string &name)

Get a pointer to const extra data (if it exists) associated with a ArrayRefCountPtr object.

Dealloc_T & get_dealloc (ArrayRefCountPtr< T > &p)

Return a non-const reference to the underlying deallocator object.

const Dealloc_T & get_dealloc (const ArrayRefCountPtr< T > &p)

Return a const reference to the underlying deallocator object.

Dealloc_T * get_optional_dealloc (ArrayRefCountPtr< T > &p)

Return a pointer to the underlying non-const deallocator object if it exists.

const Dealloc_T * get_optional_dealloc (const ArrayRefCountPtr< T > &p)

Return a pointer to the underlying const deallocator object if it exists.

std::ostream & operator<< (std::ostream &out, const ArrayRefCountPtr< T > &p)

Output stream inserter.

Detailed Description

template<class T>
class Teuchos::ArrayRefCountPtr< T >

Array reference-counted pointer class.

This is a reference-counted class similar to RefCountPtr except that it is designed to use reference counting to manage an array of objects that use value semantics. Managing an array of objects is very different from managing a pointer to an individual, possibly polymorphic, object. For example, while implicit conversions from derived to base types is a good thing when dealing with pointers to single objects, it is a very bad thing when working with arrays of objects. Therefore, this class contains those capabilities of raw pointers that are good dealing with arrays of objects but excludes those that are bad, such as implicit conversions from derived to base types.

Note that all access will be checked at runtime to avoid reading invalid memory if HAVE_TEUCHOS_ARRAY_BOUNDSCHECK is defined which it is if --enable-teuchos-abc is given to the configure script. In order to be able to check access, every ArrayRefCountPtr must be constructed given a range. When HAVE_TEUCHOS_ARRAY_BOUNDSCHECK is defined, this class simply does not give up a raw pointer or raw reference to any internally referenced object if that object does not fall with the range of valid data.

ToDo: Finish documentation!

Definition at line 63 of file Teuchos_ArrayRefCountPtrDecl.hpp.

Member Typedef Documentation

template<class T>

typedef T Teuchos::ArrayRefCountPtr< T >::element_type

Definition at line 70 of file Teuchos_ArrayRefCountPtrDecl.hpp.

template<class T>

typedef Teuchos_Index Teuchos::ArrayRefCountPtr< T >::Ordinal

Definition at line 72 of file Teuchos_ArrayRefCountPtrDecl.hpp.

Constructor & Destructor Documentation

template<class T>

Teuchos::ArrayRefCountPtr< T >::ArrayRefCountPtr ( ENull null_arg = null ) [inline]

Initialize ArrayRefCountPtr<T> to NULL.
This allows clients to write code like:
ArrayRefCountPtr<int> p = null;
or
ArrayRefCountPtr<int> p;
and construct to NULL
Definition at line 60 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE Teuchos::ArrayRefCountPtr< T >::ArrayRefCountPtr ( const ArrayRefCountPtr< T > & r_ptr )

Initialize from another ArrayRefCountPtr<T> object.
After construction, this and r_ptr will reference the same array.
This form of the copy constructor is required even though the below more general templated version is sufficient since some compilers will generate this function automatically which will give an incorrect implementation.
Postconditions:

this->get() == r_ptr.get()

this->count() == r_ptr.count()

this->has_ownership() == r_ptr.has_ownership()

If r_ptr.get() != NULL then r_ptr.count() is incremented by 1

Definition at line 69 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE Teuchos::ArrayRefCountPtr< T >::~ArrayRefCountPtr ( )

Removes a reference to a dynamically allocated array and possibly deletes the array if owned.
Deallocates array if this->has_ownership() == true and this->count() == 1. If this->count() == 1 but this->has_ownership() == false then the array is not deleted (usually using delete []). If this->count() > 1 then the internal reference count shared by all the other related ArrayRefCountPtr<...> objects for this shared array is deincremented by one. If this->get() == NULL then nothing happens.
Definition at line 79 of file Teuchos_ArrayRefCountPtr.hpp.

Member Function Documentation

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > & Teuchos::ArrayRefCountPtr< T >::operator= ( const ArrayRefCountPtr< T > & r_ptr )

Copy the pointer to the referenced array and increment the reference count.
If this->has_ownership() == true and this->count() == 1 before this operation is called, then the array will be deleted prior to binding to the pointer (possibly NULL) pointed to in r_ptr. Assignment to self (i.e. this->get() == r_ptr.get()) is harmless and this function does nothing.
Postconditions:

this->get() == r_ptr.get()

this->count() == r_ptr.count()

this->has_ownership() == r_ptr.has_ownership()

If r_ptr.get() != NULL then r_ptr.count() is incremented by 1

Definition at line 92 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

T * Teuchos::ArrayRefCountPtr< T >::operator-> ( ) const [inline]

Pointer (->) access to members of underlying object for current position.
Preconditions:

this->get() != NULL

this->lowerOffset() <= 0

this->upperOffset() >= 0

Definition at line 114 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

T & Teuchos::ArrayRefCountPtr< T >::operator * ( ) const [inline]

Dereference the underlying object for the current pointer position.
Preconditions:

this->get() != NULL

this->lowerOffset() <= 0

this->upperOffset() >= 0

Definition at line 124 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

T * Teuchos::ArrayRefCountPtr< T >::get ( ) const [inline]

Get the raw C++ pointer to the underlying object.
Preconditions:

[*this != null] this->lowerOffset() <= 0

[*this != null] this->upperOffset() >= 0

Definition at line 134 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE T & Teuchos::ArrayRefCountPtr< T >::operator[] ( Ordinal offset ) const

Random object access.
Preconditions:

this->get() != NULL

this->lowerOffset() <= offset && offset <= this->upperOffset()

Definition at line 146 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > & Teuchos::ArrayRefCountPtr< T >::operator++ ( )

Prefix increment of pointer (i.e. ++ptr).
Does nothing if this->get() == NULL.
Postconditions:

[this->get()!=NULL] this->get() is incremented by 1

[this->get()!=NULL] this->lowerOffset() is deincremented by 1

[this->get()!=NULL] this->upperOffset() is deincremented by 1

Definition at line 158 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > Teuchos::ArrayRefCountPtr< T >::operator++ ( int )

Postfix increment of pointer (i.e. ptr++).
Does nothing if this->get() == NULL.
Postconditions:

this->get() is incremented by 1

this->lowerOffset() is deincremented by 1

this->upperOffset() is deincremented by 1

Definition at line 170 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > & Teuchos::ArrayRefCountPtr< T >::operator-- ( )

Prefix deincrement of pointer (i.e. --ptr).
Does nothing if this->get() == NULL.
Postconditions:

[this->get()!=NULL] this->get() is deincremented by 1

[this->get()!=NULL] this->lowerOffset() is incremented by 1

[this->get()!=NULL] this->upperOffset() is incremented by 1

Definition at line 179 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > Teuchos::ArrayRefCountPtr< T >::operator-- ( int )

Postfix deincrement of pointer (i.e. ptr--).
Does nothing if this->get() == NULL.
Postconditions:

this->get() is dincremented by 1

this->lowerOffset() is incremented by 1

this->upperOffset() is incremented by 1

Definition at line 191 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > & Teuchos::ArrayRefCountPtr< T >::operator+= ( Ordinal offset )

Pointer integer increment (i.e. ptr+=offset).
Does nothing if this->get() == NULL.
Postconditions:

[this->get()!=NULL] this->get() is incremented by offset

[this->get()!=NULL] this->lowerOffset() is deincremented by offset

[this->get()!=NULL] this->upperOffset() is deincremented by offset

Definition at line 200 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > & Teuchos::ArrayRefCountPtr< T >::operator-= ( Ordinal offset )

Pointer integer increment (i.e. ptr-=offset).
Does nothing if this->get() == NULL.
Postconditions:

[this->get()!=NULL] this->get() is deincremented by offset

[this->get()!=NULL] this->lowerOffset() is incremented by offset

[this->get()!=NULL] this->upperOffset() is incremented by offset

Definition at line 212 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > Teuchos::ArrayRefCountPtr< T >::operator+ ( Ordinal offset ) const

Pointer integer increment (i.e. ptr+offset).
Returns a null pointer if this->get() == NULL.
Postconditions:

[this->get()!=NULL] return->get() == this->get() + offset

[this->get()!=NULL] return->lowerOffset() == this->lowerOffset() - offset

[this->get()!=NULL] return->upperOffset() == this->upperOffset() - offset

Note that since implicit conversion of ArrayRefCountPtr<T> objects is not allowed that it does not help at all to make this function into a non-member function.
Definition at line 224 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > Teuchos::ArrayRefCountPtr< T >::operator- ( Ordinal offset ) const

Pointer integer deincrement (i.e. ptr-offset).
Returns a null pointer if this->get() == NULL.
Postconditions:

[this->get()!=NULL] return->get() == this->get() - offset

[this->get()!=NULL] return->lowerOffset() == this->lowerOffset() + offset

[this->get()!=NULL] return->upperOffset() == this->upperOffset() + offset

Note that since implicit conversion of ArrayRefCountPtr<T> objects is not allowed that it does not help at all to make this function into a non-member function.
Definition at line 233 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< const T > Teuchos::ArrayRefCountPtr< T >::getConst ( ) const

Return object for only const access to data.
This function should compile only successfully if the type T is not already declared const!
Definition at line 244 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T > Teuchos::ArrayRefCountPtr< T >::subview ( Ordinal lowerOffset,

Ordinal size

) const

Return a view of a contiguous range of elements.
Preconditions:

this->get() != NULL

this->lowerOffset() <= lowerOffset

lowerOffset + size - 1 <= this->upperOffset()

Postconditions:

return->get() == this->get() + lowerOffset

return->lowerOffset() == 0

return->upperOffset() == size-1

Definition at line 253 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE int Teuchos::ArrayRefCountPtr< T >::count ( ) const

Return the number of ArrayRefCountPtr<> objects that have a reference to the underlying pointer that is being shared.

Returns:
If this->get() == NULL then this function returns 0. Otherwise, this function returns > 0.

Definition at line 269 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

template<class T2>

REFCOUNTPTR_INLINE bool Teuchos::ArrayRefCountPtr< T >::shares_resource ( const ArrayRefCountPtr< T2 > & r_ptr ) const

Returns true if the smart pointers share the same underlying reference-counted object.
This method does more than just check if this->get() == r_ptr.get(). It also checks to see if the underlying reference counting machinery is the same.
Definition at line 278 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T >::Ordinal Teuchos::ArrayRefCountPtr< T >::lowerOffset ( ) const

Return the lower offset to valid data.

Definition at line 289 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T >::Ordinal Teuchos::ArrayRefCountPtr< T >::upperOffset ( ) const

Return the upper offset to valid data.

Definition at line 297 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T >::Ordinal Teuchos::ArrayRefCountPtr< T >::size ( ) const

The total number of items in the managed array (i.e. upperOffset()-lowerOffset()+1).

Definition at line 305 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T >::const_iterator Teuchos::ArrayRefCountPtr< T >::begin ( ) const

Return an iterator to beginning of the array of data.
If HAVE_TEUCHOS_ARRAY_BOUNDSCHECK is defined then the iterator returned is an ArrayRefCountPtr<T> object and all operations are checked at runtime. When HAVE_TEUCHOS_ARRAY_BOUNDSCHECK is not defined, the a raw pointer T* is returned for fast execution.
Postconditions:

[this->get()!=NULL] &*return == this->get()

[this->get()==NULL] return == (null or NULL)

Definition at line 314 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE ArrayRefCountPtr< T >::const_iterator Teuchos::ArrayRefCountPtr< T >::end ( ) const

Return an iterator to past the end of the array of data.
If HAVE_TEUCHOS_ARRAY_BOUNDSCHECK is defined then the iterator returned is an ArrayRefCountPtr<T> object and all operations are checked at runtime. When HAVE_TEUCHOS_ARRAY_BOUNDSCHECK is not defined, the a raw pointer T* is returned for fast execution.
Postconditions:

[this->get()!=NULL] &*end == this->get()+(this->upperOffset()+1)

[this->get()==NULL] return == (null or NULL)

Definition at line 326 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE T * Teuchos::ArrayRefCountPtr< T >::release ( )

Release the ownership of the underlying array.
After this function is called then the client is responsible for deleting the returned pointer no matter how many ref_count_ptr<T> objects have a reference to it. If this->get() == NULL, then this call is meaningless.
Note that this function does not have the exact same semantics as does auto_ptr<T>::release(). In auto_ptr<T>::release(), this is set to NULL while here in ArrayRefCountPtr<T>:: release() only an ownership flag is set and this still points to the same array. It would be difficult to duplicate the behavior of auto_ptr<T>::release() for this class.
Postconditions:

this->has_ownership() == false

Returns:
Returns the value of this->get()

Definition at line 339 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE void Teuchos::ArrayRefCountPtr< T >::set_has_ownership ( )

Give this and other ArrayRefCountPtr<> objects ownership of the underlying referenced array to delete it.
See ~ArrayRefCountPtr() above. This function does nothing if this->get() == NULL.
Postconditions:

If this->get() == NULL then

this->has_ownership() == false (always!).

else

this->has_ownership() == true

Definition at line 348 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

REFCOUNTPTR_INLINE bool Teuchos::ArrayRefCountPtr< T >::has_ownership ( ) const

Returns true if this has ownership of object pointed to by this->get() in order to delete it.
See ~ArrayRefCountPtr() above.

Returns:
If this->get() == NULL then this function always returns false. Otherwise the value returned from this function depends on which function was called most recently, if any; set_has_ownership() (true) or release() (false).

Definition at line 356 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

const ArrayRefCountPtr< T > & Teuchos::ArrayRefCountPtr< T >::assert_not_null ( ) const [inline]

Throws std::logic_error if this->get()==NULL, otherwise returns reference to *this.

Definition at line 368 of file Teuchos_ArrayRefCountPtr.hpp.

template<class T>

const ArrayRefCountPtr< T > & Teuchos::ArrayRefCountPtr< T >::assert_in_range ( Ordinal lowerOffset,

Ordinal size

) const [inline]

Throws std::logic_error if this->get()==NULL orthis->get()!=NULL && (lowerOffset < this->lowerOffset() || this->upperOffset() < upperOffset, otherwise returns reference to *this.

Definition at line 377 of file Teuchos_ArrayRefCountPtr.hpp.

Friends And Related Function Documentation

template<class T>

ArrayRefCountPtr< T > arcp ( T * p,

typename ArrayRefCountPtr< T >::Ordinal lowerOffset,

typename ArrayRefCountPtr< T >::Ordinal size,

bool owns_mem = true

) [related]

Wraps a preallocated array of data with the assumption to call the array version of delete.

template<class T>

ArrayRefCountPtr< T > arcp ( T * p,

typename ArrayRefCountPtr< T >::Ordinal lowerOffset,

typename ArrayRefCountPtr< T >::Ordinal size,

Dealloc_T dealloc,

bool owns_mem

) [related]

Wraps a preallocated array of data and uses a templated deallocation strategy object to define deletion .

template<class T>

ArrayRefCountPtr< T > arcp ( typename ArrayRefCountPtr< T >::Ordinal size ) [related]

Allocate a new array just given a dimension.
Warning! The memory is allocated using new T[size] and is *not* initialized (unless there is a default constructor for a user-defined type).

template<class T>

ArrayRefCountPtr< T > arcp ( const RefCountPtr< std::vector< T > > & v ) [related]

Wrap an std::vector<T> object as an ArrayRefCountPtr<T> object.

template<class T>

ArrayRefCountPtr< const T > arcp ( const RefCountPtr< const std::vector< T > > & v ) [related]

Wrap a const std::vector<T> object as an ArrayRefCountPtr<const T> object.

template<class T>

RefCountPtr< std::vector< T > > get_std_vector ( const ArrayRefCountPtr< T > & ptr ) [related]

Get an std::vector<T> object out of an ArrayRefCountPtr<T> object that was created using the arcp() above to wrap the vector in the first place..

template<class T>

RefCountPtr< const std::vector< T > > get_std_vector ( const ArrayRefCountPtr< const T > & ptr ) [related]

Get a const std::vector<T> object out of an ArrayRefCountPtr<const T> object that was created using the arcp() above to wrap the vector in the first place.

template<class T>

bool is_null ( const ArrayRefCountPtr< T > & p ) [related]

Returns true if p.get()==NULL.

template<class T>

bool operator== ( const ArrayRefCountPtr< T > & p,

ENull

) [related]

Returns true if p.get()==NULL.

template<class T>

bool operator!= ( const ArrayRefCountPtr< T > & p,

ENull

) [related]

Returns true if p.get()!=NULL.

template<class T>

bool operator== ( const ArrayRefCountPtr< T1 > & p1,

const ArrayRefCountPtr< T2 > & p2

) [related]

template<class T>

bool operator!= ( const ArrayRefCountPtr< T1 > & p1,

const ArrayRefCountPtr< T2 > & p2

) [related]

template<class T>

bool operator< ( const ArrayRefCountPtr< T1 > & p1,

const ArrayRefCountPtr< T2 > & p2

) [related]

template<class T>

bool operator<= ( const ArrayRefCountPtr< T1 > & p1,

const ArrayRefCountPtr< T2 > & p2

) [related]

template<class T>

bool operator> ( const ArrayRefCountPtr< T1 > & p1,

const ArrayRefCountPtr< T2 > & p2

) [related]

template<class T>

bool operator>= ( const ArrayRefCountPtr< T1 > & p1,

const ArrayRefCountPtr< T2 > & p2

) [related]

template<class T>

ArrayRefCountPtr< T2 > arcp_reinterpret_cast ( const ArrayRefCountPtr< T1 > & p1 ) [related]

Reinterpret cast of underlying ArrayRefCountPtr type from T1* to T2*.
The function will compile only if (reinterpret_cast<T2*>(p1.get());) compiles.
Warning! Do not use this function unless you absolutely know what you are doing. Doing a reinterpret cast is always a tricking thing and must only be done by developers who are 100% comfortable with what they are doing.

template<class T>

ArrayRefCountPtr< T2 > arcp_implicit_cast ( const ArrayRefCountPtr< T1 > & p1 ) [related]

Implicit case the underlying ArrayRefCountPtr type from T1* to T2*.
The function will compile only if (T2 *p = p1.get();) compiles.
Warning! Do not use this function unless you absolutely know what you are doing. While implicit casting of pointers to single objects is usually 100% safe, implicit casting pointers to arrays of objects can be very dangerous. One exception that is always safe is when you are implicit casting an array of pointers to non-const objects to an array of const pointers to const objects. For example, the following implicit conversion from a array pointer objects aptr1 of type ArrayRefCountPtr<T*> to

ArrayRefCountPtr<const T * const> aptr2 = arcp_implicit_cast<const T * const>(ptr1);
is always legal and safe to do.

template<class T>

void set_extra_data ( const T1 & extra_data,

const std::string & name,

ArrayRefCountPtr< T2 > * p,

EPrePostDestruction destroy_when = POST_DESTROY,

bool force_unique = true

) [related]

Set extra data associated with a ArrayRefCountPtr object.

Parameters:

extra_data [in] Data object that will be set (copied)

name [in] The name given to the extra data. The value of name together with the data type T1 of the extra data must be unique from any other such data or the other data will be overwritten.

p [out] On output, will be updated with the input extra_data

destroy_when [in] Determines when extra_data will be destroyed in relation to the underlying reference-counted object. If destroy_when==PRE_DESTROY then extra_data will be deleted before the underlying reference-counted object. If destroy_when==POST_DESTROY (the default) then extra_data will be deleted after the underlying reference-counted object.

force_unique [in] Determines if this type and name pair must be unique in which case if an object with this same type and name already exists, then an exception will be thrown. The default is true for safety.

If there is a call to this function with the same type of extra data T1 and same arguments p and name has already been made, then the current piece of extra data already set will be overwritten with extra_data. However, if the type of the extra data T1 is different, then the extra data can be added and not overwrite existing extra data. This means that extra data is keyed on both the type and name. This helps to minimize the chance that clients will unexpectedly overwrite data by accident.
When the last RefcountPtr object is removed and the reference-count node is deleted, then objects are deleted in the following order: (1) All of the extra data that where added with destroy_when==PRE_DESTROY are first, (2) then the underlying reference-counted object is deleted, and (3) the rest of the extra data that was added with destroy_when==PRE_DESTROY is then deleted. The order in which the objects are destroyed is not guaranteed. Therefore, clients should be careful not to add extra data that has deletion dependencies (instead consider using nested ArrayRefCountPtr objects as extra data which will guarantee the order of deletion).
Preconditions:

p->get() != NULL (throws std::logic_error)

If this function has already been called with the same template type T1 for extra_data and the same string name and force_unique==true, then an std::invalid_argument exception will be thrown.

Note, this function is made a non-member function to be consistent with the non-member get_extra_data() functions.

template<class T>

T1 & get_extra_data ( ArrayRefCountPtr< T2 > & p,

const std::string & name

) [related]

Get a non-const reference to extra data associated with a ArrayRefCountPtr object.

Parameters:

p [in] Smart pointer object that extra data is being extracted from.

name [in] Name of the extra data.

Returns:
Returns a non-const reference to the extra_data object.
Preconditions:

p.get() != NULL (throws std::logic_error)

name and T1 must have been used in a previous call to set_extra_data() (throws std::invalid_argument).

Note, this function must be a non-member function since the client must manually select the first template argument.

template<class T>

const T1 & get_extra_data ( const ArrayRefCountPtr< T2 > & p,

const std::string & name

) [related]

Get a const reference to extra data associated with a ArrayRefCountPtr object.

Parameters:

p [in] Smart pointer object that extra data is being extracted from.

name [in] Name of the extra data.

Returns:
Returns a const reference to the extra_data object.
Preconditions:

p.get() != NULL (throws std::logic_error)

name and T1 must have been used in a previous call to set_extra_data() (throws std::invalid_argument).

Note, this function must be a non-member function since the client must manually select the first template argument.
Also note that this const version is a false sense of security since a client can always copy a const ArrayRefCountPtr object into a non-const object and then use the non-const version to change the data. However, its presence will help to avoid some types of accidental changes to this extra data.

template<class T>

T1 * get_optional_extra_data ( ArrayRefCountPtr< T2 > & p,

const std::string & name

) [related]

Get a pointer to non-const extra data (if it exists) associated with a ArrayRefCountPtr object.

Parameters:

p [in] Smart pointer object that extra data is being extracted from.

name [in] Name of the extra data.

Returns:
Returns a non-const pointer to the extra_data object.
Preconditions:

p.get() != NULL (throws std::logic_error)

Postconditions:

If name and T1 have been used in a previous call to set_extra_data() then return !=NULL and otherwise return == NULL.

Note, this function must be a non-member function since the client must manually select the first template argument.

template<class T>

const T1 * get_optional_extra_data ( const ArrayRefCountPtr< T2 > & p,

const std::string & name

) [related]

Get a pointer to const extra data (if it exists) associated with a ArrayRefCountPtr object.

Parameters:

p [in] Smart pointer object that extra data is being extracted from.

name [in] Name of the extra data.

Returns:
Returns a const pointer to the extra_data object if it exists.
Preconditions:

p.get() != NULL (throws std::logic_error)

Postconditions:

If name and T1 have been used in a previous call to set_extra_data() then return !=NULL and otherwise return == NULL.

Note, this function must be a non-member function since the client must manually select the first template argument.
Also note that this const version is a false sense of security since a client can always copy a const ArrayRefCountPtr object into a non-const object and then use the non-const version to change the data. However, its presence will help to avoid some types of accidental changes to this extra data.

template<class T>

Dealloc_T & get_dealloc ( ArrayRefCountPtr< T > & p ) [related]

Return a non-const reference to the underlying deallocator object.
Preconditions:

p.get() != NULL (throws std::logic_error)

The deallocator object type used to construct p is same as Dealloc_T (throws std::logic_error)

template<class T>

const Dealloc_T & get_dealloc ( const ArrayRefCountPtr< T > & p ) [related]

Return a const reference to the underlying deallocator object.
Preconditions:

p.get() != NULL (throws std::logic_error)

The deallocator object type used to construct p is same as Dealloc_T (throws std::logic_error)

Note that the const version of this function provides only a very ineffective attempt to avoid accidental changes to the deallocation object. A client can always just create a new non-const ArrayRefCountPtr<T> object from any const ArrayRefCountPtr<T> object and then call the non-const version of this function.

template<class T>

Dealloc_T * get_optional_dealloc ( ArrayRefCountPtr< T > & p ) [related]

Return a pointer to the underlying non-const deallocator object if it exists.
Preconditions:

p.get() != NULL (throws std::logic_error)

Postconditions:

If the deallocator object type used to construct p is same as Dealloc_T then return!=NULL, otherwise return==NULL

template<class T>

const Dealloc_T * get_optional_dealloc ( const ArrayRefCountPtr< T > & p ) [related]

Return a pointer to the underlying const deallocator object if it exists.
Preconditions:

p.get() != NULL (throws std::logic_error)

Postconditions:

If the deallocator object type used to construct p is same as Dealloc_T then return!=NULL, otherwise return==NULL

Note that the const version of this function provides only a very ineffective attempt to avoid accidental changes to the deallocation object. A client can always just create a new non-const ArrayRefCountPtr<T> object from any const ArrayRefCountPtr<T> object and then call the non-const version of this function.

template<class T>

std::ostream & operator<< ( std::ostream & out,

const ArrayRefCountPtr< T > & p

) [related]

Output stream inserter.
The implementation of this function just print pointer addresses and therefore puts not restrictions on the data types involved.

The documentation for this class was generated from the following files:

Generated on Thu Sep 18 12:30:31 2008 for Teuchos - Trilinos Tools Package by

1.3.9.1


Public Types
Public types
typedef T	element_type

typedef Teuchos_Index	Ordinal

Public Member Functions
Constructors/Initializers
	ArrayRefCountPtr (ENull null_arg=null)
	Initialize `ArrayRefCountPtr<T>` to NULL.
	ArrayRefCountPtr (const ArrayRefCountPtr< T > &r_ptr)
	Initialize from another `ArrayRefCountPtr<T>` object.
	~ArrayRefCountPtr ()
	Removes a reference to a dynamically allocated array and possibly deletes the array if owned.
ArrayRefCountPtr< T > &	operator= (const ArrayRefCountPtr< T > &r_ptr)
	Copy the pointer to the referenced array and increment the reference count.
Object/Pointer Access Functions
T *	operator-> () const
	Pointer (`->`) access to members of underlying object for current position.
T &	operator * () const
	Dereference the underlying object for the current pointer position.
T *	get () const
	Get the raw C++ pointer to the underlying object.
T &	operator[] (Ordinal offset) const
	Random object access.
Pointer Arithmetic Functions
ArrayRefCountPtr< T > &	operator++ ()
	Prefix increment of pointer (i.e. ++ptr).
ArrayRefCountPtr< T >	operator++ (int)
	Postfix increment of pointer (i.e. ptr++).
ArrayRefCountPtr< T > &	operator-- ()
	Prefix deincrement of pointer (i.e. --ptr).
ArrayRefCountPtr< T >	operator-- (int)
	Postfix deincrement of pointer (i.e. ptr--).
ArrayRefCountPtr< T > &	operator+= (Ordinal offset)
	Pointer integer increment (i.e. ptr+=offset).
ArrayRefCountPtr< T > &	operator-= (Ordinal offset)
	Pointer integer increment (i.e. ptr-=offset).
ArrayRefCountPtr< T >	operator+ (Ordinal offset) const
	Pointer integer increment (i.e. ptr+offset).
ArrayRefCountPtr< T >	operator- (Ordinal offset) const
	Pointer integer deincrement (i.e. ptr-offset).
Views
ArrayRefCountPtr< const T >	getConst () const
	Return object for only const access to data.
ArrayRefCountPtr< T >	subview (Ordinal lowerOffset, Ordinal size) const
	Return a view of a contiguous range of elements.
General query functions
int	count () const
	Return the number of `ArrayRefCountPtr<>` objects that have a reference to the underlying pointer that is being shared.
template<class T2>
bool	shares_resource (const ArrayRefCountPtr< T2 > &r_ptr) const
	Returns true if the smart pointers share the same underlying reference-counted object.
Ordinal	lowerOffset () const
	Return the lower offset to valid data.
Ordinal	upperOffset () const
	Return the upper offset to valid data.
Ordinal	size () const
	The total number of items in the managed array (i.e. `upperOffset()-lowerOffset()+1`).
Standard Container-Like Functions
const_iterator	begin () const
	Return an iterator to beginning of the array of data.
const_iterator	end () const
	Return an iterator to past the end of the array of data.
Ownership
T *	release ()
	Release the ownership of the underlying array.
void	set_has_ownership ()
	Give `this` and other `ArrayRefCountPtr<>` objects ownership of the underlying referenced array to delete it.
bool	has_ownership () const
	Returns true if `this` has ownership of object pointed to by `this->get()` in order to delete it.
Assertion Functions.
const ArrayRefCountPtr< T > &	assert_not_null () const
	Throws `std::logic_error` if `this->get()==NULL`, otherwise returns reference to `*this`.
const ArrayRefCountPtr< T > &	assert_in_range (Ordinal lowerOffset, Ordinal size) const
	Throws `std::logic_error` if `this->get()==NULL` or`this->get()!=NULL && (lowerOffset < this->lowerOffset() \|\| this->upperOffset() < upperOffset`, otherwise returns reference to `*this`.
Related Functions
(Note that these are not member functions.)
ArrayRefCountPtr< T >	arcp (T *p, typename ArrayRefCountPtr< T >::Ordinal lowerOffset, typename ArrayRefCountPtr< T >::Ordinal size, bool owns_mem=true)
	Wraps a preallocated array of data with the assumption to call the array version of delete.
ArrayRefCountPtr< T >	arcp (T *p, typename ArrayRefCountPtr< T >::Ordinal lowerOffset, typename ArrayRefCountPtr< T >::Ordinal size, Dealloc_T dealloc, bool owns_mem)
	Wraps a preallocated array of data and uses a templated deallocation strategy object to define deletion .
ArrayRefCountPtr< T >	arcp (typename ArrayRefCountPtr< T >::Ordinal size)
	Allocate a new array just given a dimension.
ArrayRefCountPtr< T >	arcp (const RefCountPtr< std::vector< T > > &v)
	Wrap an `std::vector<T>` object as an `ArrayRefCountPtr<T>` object.
ArrayRefCountPtr< const T >	arcp (const RefCountPtr< const std::vector< T > > &v)
	Wrap a `const std::vector<T>` object as an `ArrayRefCountPtr<const T>` object.
RefCountPtr< std::vector< T > >	get_std_vector (const ArrayRefCountPtr< T > &ptr)
	Get an `std::vector<T>` object out of an `ArrayRefCountPtr<T>` object that was created using the `arcp()` above to wrap the vector in the first place..
RefCountPtr< const std::vector< T > >	get_std_vector (const ArrayRefCountPtr< const T > &ptr)
	Get a `const std::vector<T>` object out of an `ArrayRefCountPtr<const T>` object that was created using the `arcp()` above to wrap the vector in the first place.
bool	is_null (const ArrayRefCountPtr< T > &p)
	Returns true if `p.get()==NULL`.
bool	operator== (const ArrayRefCountPtr< T > &p, ENull)
	Returns true if `p.get()==NULL`.
bool	operator!= (const ArrayRefCountPtr< T > &p, ENull)
	Returns true if `p.get()!=NULL`.
bool	operator== (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool	operator!= (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool	operator< (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool	operator<= (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool	operator> (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

bool	operator>= (const ArrayRefCountPtr< T1 > &p1, const ArrayRefCountPtr< T2 > &p2)

ArrayRefCountPtr< T2 >	arcp_reinterpret_cast (const ArrayRefCountPtr< T1 > &p1)
	Reinterpret cast of underlying `ArrayRefCountPtr` type from `T1` to `T2`.
ArrayRefCountPtr< T2 >	arcp_implicit_cast (const ArrayRefCountPtr< T1 > &p1)
	Implicit case the underlying `ArrayRefCountPtr` type from `T1` to `T2`.
void	set_extra_data (const T1 &extra_data, const std::string &name, ArrayRefCountPtr< T2 > *p, EPrePostDestruction destroy_when=POST_DESTROY, bool force_unique=true)
	Set extra data associated with a `ArrayRefCountPtr` object.
T1 &	get_extra_data (ArrayRefCountPtr< T2 > &p, const std::string &name)
	Get a non-const reference to extra data associated with a `ArrayRefCountPtr` object.
const T1 &	get_extra_data (const ArrayRefCountPtr< T2 > &p, const std::string &name)
	Get a const reference to extra data associated with a `ArrayRefCountPtr` object.
T1 *	get_optional_extra_data (ArrayRefCountPtr< T2 > &p, const std::string &name)
	Get a pointer to non-const extra data (if it exists) associated with a `ArrayRefCountPtr` object.
const T1 *	get_optional_extra_data (const ArrayRefCountPtr< T2 > &p, const std::string &name)
	Get a pointer to const extra data (if it exists) associated with a `ArrayRefCountPtr` object.
Dealloc_T &	get_dealloc (ArrayRefCountPtr< T > &p)
	Return a non-`const` reference to the underlying deallocator object.
const Dealloc_T &	get_dealloc (const ArrayRefCountPtr< T > &p)
	Return a `const` reference to the underlying deallocator object.
Dealloc_T *	get_optional_dealloc (ArrayRefCountPtr< T > &p)
	Return a pointer to the underlying non-`const` deallocator object if it exists.
const Dealloc_T *	get_optional_dealloc (const ArrayRefCountPtr< T > &p)
	Return a pointer to the underlying `const` deallocator object if it exists.
std::ostream &	operator<< (std::ostream &out, const ArrayRefCountPtr< T > &p)
	Output stream inserter.

Teuchos::ArrayRefCountPtr< T > Class Template Reference [Teuchos Memory Management Utilities]

Public Types

Public Member Functions

Related Functions