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

Array reference-counted pointer class. More...

#include <Teuchos_ArrayRCPDecl.hpp>

List of all members.

Public Types

Public types

typedef std::random_access_iterator_tag iterator_category

typedef T * iterator_type

typedef T value_type

typedef T & reference

typedef T * pointer

typedef ptrdiff_t difference_type

typedef T element_type

typedef Teuchos_Index Ordinal

Public Member Functions

Constructors/Destructors/Initializers

ArrayRCP (ENull null_arg=null)

Initialize ArrayRCP<T> to NULL.

ArrayRCP (const ArrayRCP< T > &r_ptr)

Initialize from another ArrayRCP<T> object.

~ArrayRCP ()

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

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

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

Object/Pointer Access Functions

bool is_null () const

Returns true if the underlying pointer is null.

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 * getRawPtr () const

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

T & operator[] (Ordinal offset) const

Random object access.

Pointer Arithmetic Functions

ArrayRCP< T > & operator++ ()

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

ArrayRCP< T > operator++ (int)

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

ArrayRCP< T > & operator-- ()

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

ArrayRCP< T > operator-- (int)

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

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

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

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

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

ArrayRCP< T > operator+ (Ordinal offset) const

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

ArrayRCP< T > operator- (Ordinal offset) const

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

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.

ArrayRCP Views

ArrayRCP< const T > getConst () const

Return object for only const access to data.

ArrayRCP< T > persistingView (Ordinal lowerOffset, Ordinal size) const

Return a persisting view of a contiguous range of elements.

Size and extent query functions

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).

ArrayView views

ArrayView< T > view (Ordinal lowerOffset, Ordinal size) const

Return view of a contiguous range of elements.

ArrayView< T > operator() (Ordinal lowerOffset, Ordinal size) const

Return a view of a contiguous range of elements (calls view(offset,size)).

ArrayView< T > operator() () const

Return an ArrayView of *this.

operator ArrayView () const

Perform an implicit conversion to a ArrayView<T> (calls operator()()).

operator ArrayRCP () const

Convert from ArrayRCP<T> to ArrayRCP<const T>.

Reference counting

ERCPStrength strength () const

Strength of the pointer.

bool is_valid_ptr () const

Return if the underlying object pointer is still valid or not.

int strong_count () const

Return the number of active RCP<> objects that have a "strong" reference to the underlying reference-counted object.

int weak_count () const

Return the number of active RCP<> objects that have a "weak" reference to the underlying reference-counted object.

int total_count () const

Total count (strong_count() + weak_count()).

void set_has_ownership ()

Give this and other ArrayRCP<> 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.

T * release ()

Release the ownership of the underlying array.

ArrayRCP< T > create_weak () const

Create a new weak RCP object from another RCP object.

template<class T2>

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

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

Assertion Functions.

const ArrayRCP< T > & assert_not_null () const

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

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

Throws NullReferenceError if this->get()==NULL orthis->get()!=NULL, throws RangeError if (lowerOffset < this->lowerOffset() || this->upperOffset() < upperOffset, otherwise returns reference to *this.

const ArrayRCP< T > & assert_valid_ptr () const

If the object pointer is non-null, assert that it is still valid.

Deprecated

int count () const

Returns strong_count() [deprecated].

Related Functions

(Note that these are not member functions.)

ArrayRCP< T > arcp (const RCP< Array< T > > &v)

Wrap an Array<T> object as an ArrayRCP<T> object.

ArrayRCP< const T > arcp (const RCP< const Array< T > > &v)

Wrap a const Array<T> object as an ArrayRCP<const T> object.

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

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

ArrayRCP< T > arcp (T *p, typename ArrayRCP< T >::Ordinal lowerOffset, typename ArrayRCP< 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 .

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

Allocate a new array just given a dimension.

ArrayRCP< T > arcpClone (const ArrayView< const T > &v)

Allocate a new array by cloning data from an input array view.

ArrayRCP< T > arcpWithEmbeddedObjPreDestroy (T *p, typename ArrayRCP< T >::Ordinal lowerOffset, typename ArrayRCP< T >::Ordinal size, const Embedded &embedded, bool owns_mem=true)

Create an ArrayRCP with and also put in an embedded object.

ArrayRCP< T > arcpWithEmbeddedObjPostDestroy (T *p, typename ArrayRCP< T >::Ordinal lowerOffset, typename ArrayRCP< T >::Ordinal size, const Embedded &embedded, bool owns_mem=true)

Create an ArrayRCP with and also put in an embedded object.

ArrayRCP< T > arcpWithEmbeddedObj (T *p, typename ArrayRCP< T >::Ordinal lowerOffset, typename ArrayRCP< T >::Ordinal size, const Embedded &embedded, bool owns_mem=true)

Create an ArrayRCP with and also put in an embedded object.

ArrayRCP< T > arcp (const RCP< std::vector< T > > &v)

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

ArrayRCP< const T > arcp (const RCP< const std::vector< T > > &v)

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

RCP< std::vector< T > > get_std_vector (const ArrayRCP< T > &ptr)

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

RCP< const std::vector< T > > get_std_vector (const ArrayRCP< const T > &ptr)

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

bool is_null (const ArrayRCP< T > &p)

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

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

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

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

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

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

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

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

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

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

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

ArrayRCP< T >::difference_type operator- (const ArrayRCP< T > &p1, const ArrayRCP< T > &p2)

Returns difference of two ArrayRCP object.

ArrayRCP< T2 > arcp_const_cast (const ArrayRCP< T1 > &p1)

Const cast of underlying ArrayRCP type from const T* to T*.

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

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

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

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

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

Set extra data associated with a ArrayRCP object.

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

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

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

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

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

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

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

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

Dealloc_T & get_nonconst_dealloc (const ArrayRCP< T > &p)

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

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

Return a const reference to the underlying deallocator object.

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

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

Dealloc_T * get_optional_nonconst_dealloc (const ArrayRCP< T > &p)

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

const Embedded & getEmbeddedObj (const ArrayRCP< T > &p)

Get a const reference to an embedded object that was set by calling arcpWithEmbeddedObjPreDestroy(), arcpWithEmbeddedObjPostDestory(), or arcpWithEmbeddedObj().

Embedded & getNonconstEmbeddedObj (const ArrayRCP< T > &p)

Get a const reference to an embedded object that was set by calling arcpWithEmbeddedObjPreDestroy(), arcpWithEmbeddedObjPostDestory(), or arcpWithEmbeddedObj().

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

Output stream inserter.

Detailed Description

template<class T>
class Teuchos::ArrayRCP< T >

Array reference-counted pointer class.

This is a reference-counted class similar to RCP 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 ArrayRCP 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.

Type T requirements:

Must have a valid Teuchos::TypeNameTraits<T> specialization

ToDo: Finish documentation!

Member Typedef Documentation

template<class T>

typedef std::random_access_iterator_tag Teuchos::ArrayRCP< T >::iterator_category

template<class T>

typedef T* Teuchos::ArrayRCP< T >::iterator_type

template<class T>

typedef T Teuchos::ArrayRCP< T >::value_type

template<class T>

typedef T& Teuchos::ArrayRCP< T >::reference

template<class T>

typedef T* Teuchos::ArrayRCP< T >::pointer

template<class T>

typedef ptrdiff_t Teuchos::ArrayRCP< T >::difference_type

template<class T>

typedef T Teuchos::ArrayRCP< T >::element_type

template<class T>

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

Constructor & Destructor Documentation

template<class T>

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

Initialize ArrayRCP<T> to NULL.
This allows clients to write code like:
ArrayRCP<int> p = null;
or
ArrayRCP<int> p;
and construct to NULL

template<class T>

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

Initialize from another ArrayRCP<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

template<class T>

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

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 ArrayRCP<...> objects for this shared array is deincremented by one. If this->get() == NULL then nothing happens.

Member Function Documentation

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > & Teuchos::ArrayRCP< T >::operator= ( const ArrayRCP< 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

template<class T>

bool Teuchos::ArrayRCP< T >::is_null ( ) const [inline]

Returns true if the underlying pointer is null.

template<class T>

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

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

this->get() != NULL

this->lowerOffset() <= 0

this->upperOffset() >= 0

template<class T>

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

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

this->get() != NULL

this->lowerOffset() <= 0

this->upperOffset() >= 0

template<class T>

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

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

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

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

template<class T>

T * Teuchos::ArrayRCP< T >::getRawPtr ( ) const [inline]

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

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

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

template<class T>

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

Random object access.
Preconditions:

this->get() != NULL

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

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > & Teuchos::ArrayRCP< 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

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > Teuchos::ArrayRCP< 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

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > & Teuchos::ArrayRCP< 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

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > Teuchos::ArrayRCP< 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

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > & Teuchos::ArrayRCP< 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

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > & Teuchos::ArrayRCP< 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

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > Teuchos::ArrayRCP< 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 ArrayRCP<T> objects is not allowed that it does not help at all to make this function into a non-member function.

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > Teuchos::ArrayRCP< 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 ArrayRCP<T> objects is not allowed that it does not help at all to make this function into a non-member function.

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T >::const_iterator Teuchos::ArrayRCP< 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 ArrayRCP<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)

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T >::const_iterator Teuchos::ArrayRCP< 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 ArrayRCP<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)

template<class T>

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

Return object for only const access to data.
This function should only compile successfully if the type T is not already declared const!

template<class T>

REFCOUNTPTR_INLINE ArrayRCP< T > Teuchos::ArrayRCP< T >::persistingView ( Ordinal lowerOffset,

Ordinal size

) const

Return a persisting 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

template<class T>

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

Return the lower offset to valid data.

template<class T>

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

Return the upper offset to valid data.

template<class T>

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

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

template<class T>

ArrayView< T > Teuchos::ArrayRCP< T >::view ( Ordinal lowerOffset,

Ordinal size

) const [inline]

Return 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

template<class T>

ArrayView< T > Teuchos::ArrayRCP< T >::operator() ( Ordinal lowerOffset,

Ordinal size

) const [inline]

Return a view of a contiguous range of elements (calls view(offset,size)).

template<class T>

ArrayView< T > Teuchos::ArrayRCP< T >::operator() ( ) const [inline]

Return an ArrayView of *this.
NOTE: This will return a null ArrayView if this->size() == 0.

template<class T>

Teuchos::ArrayRCP< T >::operator ArrayView< T > ( ) const [inline]

Perform an implicit conversion to a ArrayView<T> (calls operator()()).

template<class T>

Teuchos::ArrayRCP< T >::operator ArrayRCP< const T > ( ) const [inline]

Convert from ArrayRCP<T> to ArrayRCP<const T>.

template<class T>

ERCPStrength Teuchos::ArrayRCP< T >::strength ( ) const [inline]

Strength of the pointer.
Return values:

RCP_STRONG: Underlying reference-counted object will be deleted when *this is destroyed if strong_count()==1.

RCP_WEAK: Underlying reference-counted object will not be deleted when *this is destroyed if strong_count() > 0.

RCP_STRENGTH_INVALID: *this is not strong or weak but is null.

template<class T>

bool Teuchos::ArrayRCP< T >::is_valid_ptr ( ) const [inline]

Return if the underlying object pointer is still valid or not.
The underlying object will not be valid if the strong count has gone to zero but the weak count thas not.
NOTE: Null is a valid object pointer. If you want to know if there is a non-null object and it is valid then !is_null() && is_valid_ptr() will be true.

template<class T>

int Teuchos::ArrayRCP< T >::strong_count ( ) const [inline]

Return the number of active RCP<> objects that have a "strong" reference to the underlying reference-counted object.

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

template<class T>

int Teuchos::ArrayRCP< T >::weak_count ( ) const [inline]

Return the number of active RCP<> objects that have a "weak" reference to the underlying reference-counted object.

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

template<class T>

int Teuchos::ArrayRCP< T >::total_count ( ) const [inline]

Total count (strong_count() + weak_count()).

template<class T>

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

Give this and other ArrayRCP<> objects ownership of the underlying referenced array to delete it.
See ~ArrayRCP() 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

template<class T>

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

Returns true if this has ownership of object pointed to by this->get() in order to delete it.
See ~ArrayRCP() 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).

template<class T>

REFCOUNTPTR_INLINE T * Teuchos::ArrayRCP< 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 ArrayRCP<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()

template<class T>

ArrayRCP< T > Teuchos::ArrayRCP< T >::create_weak ( ) const [inline]

Create a new weak RCP object from another RCP object.
ToDo: Explain this!
Preconditons:

returnVal.is_valid_ptr()==true

Postconditons:

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

returnVal.strong_count() == this->strong_count()

returnVal.weak_count() == this->weak_count()+1

returnVal.strength() == RCP_WEAK

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

template<class T>

template<class T2>

REFCOUNTPTR_INLINE bool Teuchos::ArrayRCP< T >::shares_resource ( const ArrayRCP< 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.

template<class T>

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

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

template<class T>

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

Ordinal size

) const [inline]

Throws NullReferenceError if this->get()==NULL orthis->get()!=NULL, throws RangeError if (lowerOffset < this->lowerOffset() || this->upperOffset() < upperOffset, otherwise returns reference to *this.

template<class T>

const ArrayRCP< T > & Teuchos::ArrayRCP< T >::assert_valid_ptr ( ) const [inline]

If the object pointer is non-null, assert that it is still valid.
If is_null()==false && strong_count()==0, this will throw DanglingReferenceErorr with a great error message.
If is_null()==true, then this will not throw any exception.
In this context, null is a valid object.

template<class T>

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

Returns strong_count() [deprecated].

Friends And Related Function Documentation

template<class T>

ArrayRCP< T > arcp ( const RCP< Array< T > > & v ) [related]

Wrap an Array<T> object as an ArrayRCP<T> object.

template<class T>

ArrayRCP< const T > arcp ( const RCP< const Array< T > > & v ) [related]

Wrap a const Array<T> object as an ArrayRCP<const T> object.

template<class T>

ArrayRCP< T > arcp ( T * p,

typename ArrayRCP< T >::Ordinal <


Public Types
Public types
typedef std::random_access_iterator_tag	iterator_category

typedef T *	iterator_type

typedef T	value_type

typedef T &	reference

typedef T *	pointer

typedef ptrdiff_t	difference_type

typedef T	element_type

typedef Teuchos_Index	Ordinal

Public Member Functions
Constructors/Destructors/Initializers
	ArrayRCP (ENull null_arg=null)
	Initialize `ArrayRCP<T>` to NULL.
	ArrayRCP (const ArrayRCP< T > &r_ptr)
	Initialize from another `ArrayRCP<T>` object.
	~ArrayRCP ()
	Removes a reference to a dynamically allocated array and possibly deletes the array if owned.
ArrayRCP< T > &	operator= (const ArrayRCP< T > &r_ptr)
	Copy the pointer to the referenced array and increment the reference count.
Object/Pointer Access Functions
bool	is_null () const
	Returns true if the underlying pointer is null.
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 *	getRawPtr () const
	Get the raw C++ pointer to the underlying object.
T &	operator[] (Ordinal offset) const
	Random object access.
Pointer Arithmetic Functions
ArrayRCP< T > &	operator++ ()
	Prefix increment of pointer (i.e. ++ptr).
ArrayRCP< T >	operator++ (int)
	Postfix increment of pointer (i.e. ptr++).
ArrayRCP< T > &	operator-- ()
	Prefix deincrement of pointer (i.e. --ptr).
ArrayRCP< T >	operator-- (int)
	Postfix deincrement of pointer (i.e. ptr--).
ArrayRCP< T > &	operator+= (Ordinal offset)
	Pointer integer increment (i.e. ptr+=offset).
ArrayRCP< T > &	operator-= (Ordinal offset)
	Pointer integer increment (i.e. ptr-=offset).
ArrayRCP< T >	operator+ (Ordinal offset) const
	Pointer integer increment (i.e. ptr+offset).
ArrayRCP< T >	operator- (Ordinal offset) const
	Pointer integer deincrement (i.e. ptr-offset).
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.
ArrayRCP Views
ArrayRCP< const T >	getConst () const
	Return object for only const access to data.
ArrayRCP< T >	persistingView (Ordinal lowerOffset, Ordinal size) const
	Return a persisting view of a contiguous range of elements.
Size and extent query functions
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`).
ArrayView views
ArrayView< T >	view (Ordinal lowerOffset, Ordinal size) const
	Return view of a contiguous range of elements.
ArrayView< T >	operator() (Ordinal lowerOffset, Ordinal size) const
	Return a view of a contiguous range of elements (calls view(offset,size)).
ArrayView< T >	operator() () const
	Return an ArrayView of *this.
	operator ArrayView () const
	Perform an implicit conversion to a ArrayView<T> (calls operator()()).
	operator ArrayRCP () const
	Convert from ArrayRCP<T> to ArrayRCP<const T>.
Reference counting
ERCPStrength	strength () const
	Strength of the pointer.
bool	is_valid_ptr () const
	Return if the underlying object pointer is still valid or not.
int	strong_count () const
	Return the number of active `RCP<>` objects that have a "strong" reference to the underlying reference-counted object.
int	weak_count () const
	Return the number of active `RCP<>` objects that have a "weak" reference to the underlying reference-counted object.
int	total_count () const
	Total count (strong_count() + weak_count()).
void	set_has_ownership ()
	Give `this` and other `ArrayRCP<>` 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.
T *	release ()
	Release the ownership of the underlying array.
ArrayRCP< T >	create_weak () const
	Create a new weak RCP object from another RCP object.
template<class T2>
bool	shares_resource (const ArrayRCP< T2 > &r_ptr) const
	Returns true if the smart pointers share the same underlying reference-counted object.
Assertion Functions.
const ArrayRCP< T > &	assert_not_null () const
	Throws `NullReferenceError` if `this->get()==NULL`, otherwise returns reference to `*this`.
const ArrayRCP< T > &	assert_in_range (Ordinal lowerOffset, Ordinal size) const
	Throws `NullReferenceError` if `this->get()==NULL` or`this->get()!=NULL`, throws `RangeError` if `(lowerOffset < this->lowerOffset() \|\| this->upperOffset() < upperOffset`, otherwise returns reference to `*this`.
const ArrayRCP< T > &	assert_valid_ptr () const
	If the object pointer is non-null, assert that it is still valid.
Deprecated
int	count () const
	Returns `strong_count()` [deprecated].
Related Functions
(Note that these are not member functions.)
ArrayRCP< T >	arcp (const RCP< Array< T > > &v)
	Wrap an `Array<T>` object as an `ArrayRCP<T>` object.
ArrayRCP< const T >	arcp (const RCP< const Array< T > > &v)
	Wrap a `const Array<T>` object as an `ArrayRCP<const T>` object.
ArrayRCP< T >	arcp (T *p, typename ArrayRCP< T >::Ordinal lowerOffset, typename ArrayRCP< T >::Ordinal size, bool owns_mem=true)
	Wraps a preallocated array of data with the assumption to call the array version of delete.
ArrayRCP< T >	arcp (T *p, typename ArrayRCP< T >::Ordinal lowerOffset, typename ArrayRCP< 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 .
ArrayRCP< T >	arcp (typename ArrayRCP< T >::Ordinal size)
	Allocate a new array just given a dimension.
ArrayRCP< T >	arcpClone (const ArrayView< const T > &v)
	Allocate a new array by cloning data from an input array view.
ArrayRCP< T >	arcpWithEmbeddedObjPreDestroy (T *p, typename ArrayRCP< T >::Ordinal lowerOffset, typename ArrayRCP< T >::Ordinal size, const Embedded &embedded, bool owns_mem=true)
	Create an ArrayRCP with and also put in an embedded object.
ArrayRCP< T >	arcpWithEmbeddedObjPostDestroy (T *p, typename ArrayRCP< T >::Ordinal lowerOffset, typename ArrayRCP< T >::Ordinal size, const Embedded &embedded, bool owns_mem=true)
	Create an ArrayRCP with and also put in an embedded object.
ArrayRCP< T >	arcpWithEmbeddedObj (T *p, typename ArrayRCP< T >::Ordinal lowerOffset, typename ArrayRCP< T >::Ordinal size, const Embedded &embedded, bool owns_mem=true)
	Create an ArrayRCP with and also put in an embedded object.
ArrayRCP< T >	arcp (const RCP< std::vector< T > > &v)
	Wrap an `std::vector<T>` object as an `ArrayRCP<T>` object.
ArrayRCP< const T >	arcp (const RCP< const std::vector< T > > &v)
	Wrap a `const std::vector<T>` object as an `ArrayRCP<const T>` object.
RCP< std::vector< T > >	get_std_vector (const ArrayRCP< T > &ptr)
	Get an `std::vector<T>` object out of an `ArrayRCP<T>` object that was created using the `arcp()` above to wrap the std::vector in the first place..
RCP< const std::vector< T > >	get_std_vector (const ArrayRCP< const T > &ptr)
	Get a `const std::vector<T>` object out of an `ArrayRCP<const T>` object that was created using the `arcp()` above to wrap the std::vector in the first place.
bool	is_null (const ArrayRCP< T > &p)
	Returns true if `p.get()==NULL`.
bool	operator== (const ArrayRCP< T > &p, ENull)
	Returns true if `p.get()==NULL`.
bool	operator!= (const ArrayRCP< T > &p, ENull)
	Returns true if `p.get()!=NULL`.
bool	operator== (const ArrayRCP< T1 > &p1, const ArrayRCP< T2 > &p2)

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

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

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

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

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

ArrayRCP< T >::difference_type	operator- (const ArrayRCP< T > &p1, const ArrayRCP< T > &p2)
	Returns difference of two ArrayRCP object.
ArrayRCP< T2 >	arcp_const_cast (const ArrayRCP< T1 > &p1)
	Const cast of underlying `ArrayRCP` type from `const T` to `T`.
ArrayRCP< T2 >	arcp_reinterpret_cast (const ArrayRCP< T1 > &p1)
	Reinterpret cast of underlying `ArrayRCP` type from `T1` to `T2`.
ArrayRCP< T2 >	arcp_implicit_cast (const ArrayRCP< T1 > &p1)
	Implicit case the underlying `ArrayRCP` type from `T1` to `T2`.
void	set_extra_data (const T1 &extra_data, const std::string &name, const Ptr< ArrayRCP< T2 > > &p, EPrePostDestruction destroy_when=POST_DESTROY, bool force_unique=true)
	Set extra data associated with a `ArrayRCP` object.
T1 &	get_extra_data (ArrayRCP< T2 > &p, const std::string &name)
	Get a non-const reference to extra data associated with a `ArrayRCP` object.
const T1 &	get_extra_data (const ArrayRCP< T2 > &p, const std::string &name)
	Get a const reference to extra data associated with a `ArrayRCP` object.
T1 *	get_optional_extra_data (ArrayRCP< T2 > &p, const std::string &name)
	Get a pointer to non-const extra data (if it exists) associated with a `ArrayRCP` object.
const T1 *	get_optional_extra_data (const ArrayRCP< T2 > &p, const std::string &name)
	Get a pointer to const extra data (if it exists) associated with a `ArrayRCP` object.
Dealloc_T &	get_nonconst_dealloc (const ArrayRCP< T > &p)
	Return a non-`const` reference to the underlying deallocator object.
const Dealloc_T &	get_dealloc (const ArrayRCP< T > &p)
	Return a `const` reference to the underlying deallocator object.
const Dealloc_T *	get_optional_dealloc (const ArrayRCP< T > &p)
	Return a pointer to the underlying non-`const` deallocator object if it exists.
Dealloc_T *	get_optional_nonconst_dealloc (const ArrayRCP< T > &p)
	Return a pointer to the underlying `const` deallocator object if it exists.
const Embedded &	getEmbeddedObj (const ArrayRCP< T > &p)
	Get a const reference to an embedded object that was set by calling `arcpWithEmbeddedObjPreDestroy()`, `arcpWithEmbeddedObjPostDestory()`, or `arcpWithEmbeddedObj()`.
Embedded &	getNonconstEmbeddedObj (const ArrayRCP< T > &p)
	Get a const reference to an embedded object that was set by calling `arcpWithEmbeddedObjPreDestroy()`, `arcpWithEmbeddedObjPostDestory()`, or `arcpWithEmbeddedObj()`.
std::ostream &	operator<< (std::ostream &out, const ArrayRCP< T > &p)
	Output stream inserter.

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

Public Types

Public Member Functions

Related Functions