Teuchos Package Browser (Single Doxygen Collection) Version of the Day
Public Member Functions | Private Member Functions | Private Attributes | Related Functions
Teuchos::ArrayView< T > Class Template Reference

Nonowning array view. More...

#include <Teuchos_ArrayViewDecl.hpp>

Inheritance diagram for Teuchos::ArrayView< T >:
Inheritance graph
[legend]

List of all members.

Public Member Functions

T * access_private_ptr () const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT
std::string 
toString () const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT
std::string 
toString () const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT
std::string 
toString () const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT
std::string 
toString () const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT
std::string 
toString () const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT
std::string 
toString () const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT
std::string 
toString () const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT
std::string 
toString () const

Private Member Functions

void setUpIterators (const ERCPNodeLookup rcpNodeLookup=RCP_ENABLE_NODE_LOOKUP)
void debug_assert_not_null () const
void debug_assert_in_range (size_type offset, size_type size_in) const
void debug_assert_valid_ptr () const

Private Attributes

T * ptr_
int size_

Related Functions

(Note that these are not member functions.)

template<class T >
ArrayView< T > arrayView (T *p, typename ArrayView< T >::size_type size)
 Construct a const or non-const view to const or non-const data.
template<class T >
ArrayView< T > arrayViewFromVector (std::vector< T > &vec)
 Construct a non-const view of an std::vector.
template<class T >
ArrayView< const T > arrayViewFromVector (const std::vector< T > &vec)
 Construct a const view of an std::vector.
template<class T >
std::vector< T > createVector (const ArrayView< T > &av)
 Get a new std::vector<T> object out of an ArrayView<T> object.
template<class T >
std::vector< T > createVector (const ArrayView< const T > &av)
 Get a new std::vector<T> object out of an ArrayView<const T> object.
template<class T >
bool is_null (const ArrayView< T > &av)
 Returns true if av.is_null()==true.
template<class T >
bool nonnull (const ArrayView< T > &av)
 Returns true if av.get()!=NULL.
template<class T >
std::ostream & operator<< (std::ostream &out, const ArrayView< T > &av)
 Output stream inserter.
template<class T2 , class T1 >
ArrayView< T2 > av_const_cast (const ArrayView< T1 > &p1)
 Const cast of underlying ArrayView type from const T* to T*.
template<class T2 , class T1 >
ArrayView< T2 > av_reinterpret_cast (const ArrayView< T1 > &p1)
 Reinterpret cast of underlying ArrayView type from T1* to T2*.

Public typedefs

typedef Teuchos_Ordinal Ordinal
 Integer index type used throughout ArrayView.
typedef Ordinal size_type
 Type representing the number of elements in an ArrayRCP or view thereof.
typedef Ordinal difference_type
 Type representing the difference between two size_type values.
typedef T value_type
 Type of each array element.
typedef T * pointer
 Type of a pointer to an array element.
typedef const T * const_pointer
 Type of a const pointer to an array element.
typedef T & reference
 Type of a reference to an array element.
typedef const T & const_reference
 Type of a const reference to an array element.
typedef pointer iterator
 Type of a nonconst iterator.
typedef const_pointer const_iterator
 Type of a const iterator.

Constructors/Destructors

 ArrayView (ENull null_arg=null)
 Constructor that initializes to NULL (implicitly or explicitly).
 ArrayView (T *p, size_type size, const ERCPNodeLookup rcpNodeLookup=RCP_ENABLE_NODE_LOOKUP)
 Initialize view from raw memory.
 ArrayView (const ArrayView< T > &array)
 Initialize from another ArrayView<T> object.
 ArrayView (std::vector< typename ConstTypeTraits< T >::NonConstType > &vec)
 Create a nonconst view of an std::vector<T>.
 ArrayView (const std::vector< typename ConstTypeTraits< T >::NonConstType > &vec)
 Create a const view of an std::vector<T>.
ArrayView< T > & operator= (const ArrayView< T > &array)
 Shallow copy assignment operator.
 ~ArrayView ()
 Destructor.

General query functions

bool is_null () const
 Returns true if the underlying pointer is null.
size_type size () const
 The total number of items in the managed array.
std::string toString () const
 Convert an ArrayView<T> to an std::string

Element Access Functions

T * getRawPtr () const
 Return a raw pointer to beginning of array or NULL if unsized.
T & operator[] (size_type i) const
 Random object access.
T & front () const
 Get the first element.
T & back () const
 Get the last element.

Views

ArrayView< T > view (size_type offset, size_type size) const
 Return a view of a contiguous range of elements.
ArrayView< T > operator() (size_type offset, size_type size) const
 Return a view of a contiguous range of elements (calls view(offset, size)).
const ArrayView< T > & operator() () const
 Return *this (just for compatibility with Array and ArrayPtr).
ArrayView< const T > getConst () const
 Return a const view of a possibly nonconst view.
 operator ArrayView< const T > () const
 Implicitly convert an ArrayView<T> to an ArrayView<const T>.

Assignment

void assign (const ArrayView< const T > &array) const
 Copy the data from one array view object to this array view object.

Standard Container-Like Functions

iterator begin () const
 Return an iterator to beginning of the array of data.
iterator end () const
 Return an iterator to past the end of the array of data.

Assertion Functions.

const ArrayView< T > & assert_not_null () const
 Throws NullReferenceError if this->get()==NULL, otherwise returns reference to *this.
const ArrayView< T > & assert_in_range (size_type offset, size_type size) const
 Throws NullReferenceError if this->get()==NULL orthis->get()!=NULL, throws RangeError if (offset < 0 || this->size() < offset+size, otherwise returns reference to *this

Detailed Description

template<class T>
class Teuchos::ArrayView< T >

Nonowning array view.

Template Parameters:
TThe type of each element in the array.

This class provides a nonowning view of a one-dimensional array with zero or more entries. It holds a pointer to the data, and the number of entries in the view. "Nonowning" means that it does not manage the array's memory. This means two things. First, ArrayView's destructor does not deallocate the array. Second, if the array's memory is deallocated while the ArrayView is in scope, any further use of the ArrayView or its iterators will result in undefined behavior.

The ArrayView class has the same shallow copy semantics of the Ptr class. ArrayView is to ArrayRCP as Ptr is to RCP.

Optional bounds checking

You may enable bounds checking and other safety checks for this class by setting the Teuchos_ENABLE_DEBUG:BOOL=ON CMake option when configuring your Trilinos build. This option is off by default. It incurs a significant performance penalty and so is not recommended for production builds. Bounds checking requires that you always create ArrayView instances with the correct range. For example, if you use one of the constructors that accepts a raw pointer, you are responsible for supplying the correct number of elements in the array. Our bounds checking implementation does not attempt to replace memory debugging tools such as the Memcheck tool in Valgrind.

Requirements on the type T

ArrayView imposes the following requirements on the type T of elements in the array:

Design discussion

This class has a partial specialization for const T that omits the conversion operator operator ArrayView<const T>() const, and the assign() method (which performs a deep copy). The conversion operator does not make sense if T is already const T' for some type T', and the assign() method does not make sense if the right-hand side of the assignment is const.

Partial specialization results in duplicated code, so Teuchos developers should be careful to make modifications in both the fully generic implementation and in the partial specialization.

We considered avoiding most of the duplication by making ArrayView<T> and its partial specialization ArrayView<const T> inherit from a common base class, which contains all the common code. However, the circular dependency between ArrayRCP and ArrayView would have complicated this solution. We chose instead the simple "partial specialization without a common base class" solution, which does not interfere with the ArrayRCP / ArrayView circular dependency.

Definition at line 123 of file Teuchos_ArrayViewDecl.hpp.


Member Typedef Documentation

template<class T>
typedef Teuchos_Ordinal Teuchos::ArrayView< T >::Ordinal

Integer index type used throughout ArrayView.

Definition at line 129 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
typedef Ordinal Teuchos::ArrayView< T >::size_type

Type representing the number of elements in an ArrayRCP or view thereof.

Definition at line 132 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
typedef Ordinal Teuchos::ArrayView< T >::difference_type

Type representing the difference between two size_type values.

Definition at line 135 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
typedef T Teuchos::ArrayView< T >::value_type

Type of each array element.

Definition at line 138 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
typedef T* Teuchos::ArrayView< T >::pointer

Type of a pointer to an array element.

It may be const or nonconst, depending on T.

Definition at line 143 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
typedef const T* Teuchos::ArrayView< T >::const_pointer

Type of a const pointer to an array element.

Definition at line 146 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
typedef T& Teuchos::ArrayView< T >::reference

Type of a reference to an array element.

It may be const or nonconst, depending on T.

Definition at line 151 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
typedef const T& Teuchos::ArrayView< T >::const_reference

Type of a const reference to an array element.

Definition at line 154 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
typedef pointer Teuchos::ArrayView< T >::iterator

Type of a nonconst iterator.

Definition at line 163 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
typedef const_pointer Teuchos::ArrayView< T >::const_iterator

Type of a const iterator.

Definition at line 165 of file Teuchos_ArrayViewDecl.hpp.


Constructor & Destructor Documentation

template<class T >
Teuchos::ArrayView< T >::ArrayView ( ENull  null_arg = null) [inline]

Constructor that initializes to NULL (implicitly or explicitly).

Definition at line 58 of file Teuchos_ArrayView.hpp.

template<class T>
Teuchos::ArrayView< T >::ArrayView ( T *  p,
size_type  size,
const ERCPNodeLookup  rcpNodeLookup = RCP_ENABLE_NODE_LOOKUP 
) [inline]

Initialize view from raw memory.

Parameters:
p[in] Pointer to array of typed memory of size size. If p==0, then *this is a null view. Note that the memory pointed to by p can not go away until this view object is destoryed!
size[in] The size of the array that *this will represent pointer to by p. If p==0 then size must be 0!

Preconditions:

  • [p!=0] size > 0
  • [p==0] size == 0

Definition at line 74 of file Teuchos_ArrayView.hpp.

template<class T>
Teuchos::ArrayView< T >::ArrayView ( const ArrayView< T > &  array) [inline]

Initialize from another ArrayView<T> object.

After construction, this and array 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.

Definition at line 103 of file Teuchos_ArrayView.hpp.

template<class T>
Teuchos::ArrayView< T >::ArrayView ( std::vector< typename ConstTypeTraits< T >::NonConstType > &  vec) [inline]

Create a nonconst view of an std::vector<T>.

Definition at line 120 of file Teuchos_ArrayView.hpp.

template<class T>
Teuchos::ArrayView< T >::ArrayView ( const std::vector< typename ConstTypeTraits< T >::NonConstType > &  vec) [inline]

Create a const view of an std::vector<T>.

Definition at line 139 of file Teuchos_ArrayView.hpp.

template<class T >
Teuchos::ArrayView< T >::~ArrayView ( ) [inline]

Destructor.

Definition at line 181 of file Teuchos_ArrayView.hpp.


Member Function Documentation

template<class T>
ArrayView< T > & Teuchos::ArrayView< T >::operator= ( const ArrayView< T > &  array) [inline]

Shallow copy assignment operator.

Definition at line 158 of file Teuchos_ArrayView.hpp.

template<class T >
bool Teuchos::ArrayView< T >::is_null ( ) const [inline]

Returns true if the underlying pointer is null.

Definition at line 194 of file Teuchos_ArrayView.hpp.

template<class T >
ArrayView< T >::size_type Teuchos::ArrayView< T >::size ( ) const [inline]

The total number of items in the managed array.

Definition at line 208 of file Teuchos_ArrayView.hpp.

template<typename T >
std::string Teuchos::ArrayView< T >::toString ( ) const

Convert an ArrayView<T> to an std::string

Definition at line 223 of file Teuchos_ArrayView.hpp.

template<class T >
T * Teuchos::ArrayView< T >::getRawPtr ( ) const [inline]

Return a raw pointer to beginning of array or NULL if unsized.

Definition at line 292 of file Teuchos_ArrayView.hpp.

template<class T >
T & Teuchos::ArrayView< T >::operator[] ( size_type  i) const [inline]

Random object access.

Preconditions:

Definition at line 307 of file Teuchos_ArrayView.hpp.

template<class T >
T & Teuchos::ArrayView< T >::front ( ) const [inline]

Get the first element.

Definition at line 324 of file Teuchos_ArrayView.hpp.

template<class T >
T & Teuchos::ArrayView< T >::back ( ) const [inline]

Get the last element.

Definition at line 340 of file Teuchos_ArrayView.hpp.

template<class T >
ArrayView< T > Teuchos::ArrayView< T >::view ( size_type  offset,
size_type  size 
) const [inline]

Return a view of a contiguous range of elements.

Preconditions:

  • this->get() != NULL
  • 0 <= offset && offset + size <= this->size()

Postconditions:

  • returnVal.size() == size

NOTE: A size==0 view of even a null ArrayView is allowed and returns a null view.

Definition at line 360 of file Teuchos_ArrayView.hpp.

template<class T >
ArrayView< T > Teuchos::ArrayView< T >::operator() ( size_type  offset,
size_type  size 
) const [inline]

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

Definition at line 393 of file Teuchos_ArrayView.hpp.

template<class T >
const ArrayView< T > & Teuchos::ArrayView< T >::operator() ( ) const [inline]

Return *this (just for compatibility with Array and ArrayPtr).

Definition at line 406 of file Teuchos_ArrayView.hpp.

template<class T >
ArrayView< const T > Teuchos::ArrayView< T >::getConst ( ) const [inline]

Return a const view of a possibly nonconst view.

Definition at line 421 of file Teuchos_ArrayView.hpp.

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

Implicitly convert an ArrayView<T> to an ArrayView<const T>.

Note:
This conversion operator does not exist if T is already a const type (that is, if T is const T' for some type T'). In that case, the assignment operator and copy constructor achieve the same syntactic effect.

Definition at line 437 of file Teuchos_ArrayView.hpp.

template<class T>
void Teuchos::ArrayView< T >::assign ( const ArrayView< const T > &  array) const

Copy the data from one array view object to this array view object.

Preconditions:

  • this->size() == array.size()
Note:
This method does not exist if T is already a const type (that is, if T is const T' for some type T'). This is because assignment to a const right-hand side does not make sense.
This function does modify the right-hand side's data. However, it is declared const, because it does not change the right-hand side's pointer or the number of entries in the view. The pointer is const, even though the data (to which the pointer points) are not.

Definition at line 447 of file Teuchos_ArrayView.hpp.

template<class T >
ArrayView< T >::iterator Teuchos::ArrayView< 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)

Definition at line 464 of file Teuchos_ArrayView.hpp.

template<class T >
ArrayView< T >::iterator Teuchos::ArrayView< 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 ArrayView<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 487 of file Teuchos_ArrayView.hpp.

template<class T >
const ArrayView< T > & Teuchos::ArrayView< T >::assert_not_null ( ) const

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

Definition at line 513 of file Teuchos_ArrayView.hpp.

template<class T >
const ArrayView< T > & Teuchos::ArrayView< T >::assert_in_range ( size_type  offset,
size_type  size 
) const

Throws NullReferenceError if this->get()==NULL orthis->get()!=NULL, throws RangeError if (offset < 0 || this->size() < offset+size, otherwise returns reference to *this

Definition at line 531 of file Teuchos_ArrayView.hpp.

template<class T >
void Teuchos::ArrayView< T >::setUpIterators ( const ERCPNodeLookup  rcpNodeLookup = RCP_ENABLE_NODE_LOOKUP) [private]

Definition at line 603 of file Teuchos_ArrayView.hpp.

template<class T>
void Teuchos::ArrayView< T >::debug_assert_not_null ( ) const [inline, private]

Definition at line 386 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
void Teuchos::ArrayView< T >::debug_assert_in_range ( size_type  offset,
size_type  size_in 
) const [inline, private]

Definition at line 392 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
void Teuchos::ArrayView< T >::debug_assert_valid_ptr ( ) const [inline, private]

Definition at line 399 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
T* Teuchos::ArrayView< T >::access_private_ptr ( ) const [inline]

Definition at line 409 of file Teuchos_ArrayViewDecl.hpp.

template<>
TEUCHOSCORE_LIB_DLL_EXPORT std::string Teuchos::ArrayView< float >::toString ( ) const

Definition at line 48 of file Teuchos_ArrayView.cpp.

template<>
TEUCHOSCORE_LIB_DLL_EXPORT std::string Teuchos::ArrayView< const float >::toString ( ) const

Definition at line 74 of file Teuchos_ArrayView.cpp.

template<>
TEUCHOSCORE_LIB_DLL_EXPORT std::string Teuchos::ArrayView< double >::toString ( ) const

Definition at line 100 of file Teuchos_ArrayView.cpp.

template<>
TEUCHOSCORE_LIB_DLL_EXPORT std::string Teuchos::ArrayView< const double >::toString ( ) const

Definition at line 126 of file Teuchos_ArrayView.cpp.

template<>
TEUCHOSCORE_LIB_DLL_EXPORT std::string Teuchos::ArrayView< float >::toString ( ) const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT std::string Teuchos::ArrayView< const float >::toString ( ) const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT std::string Teuchos::ArrayView< double >::toString ( ) const
template<>
TEUCHOSCORE_LIB_DLL_EXPORT std::string Teuchos::ArrayView< const double >::toString ( ) const

Friends And Related Function Documentation

template<class T >
ArrayView< T > arrayView ( T *  p,
typename ArrayView< T >::size_type  size 
) [related]

Construct a const or non-const view to const or non-const data.

template<class T >
ArrayView< T > arrayViewFromVector ( std::vector< T > &  vec) [related]

Construct a non-const view of an std::vector.

template<class T >
ArrayView< const T > arrayViewFromVector ( const std::vector< T > &  vec) [related]

Construct a const view of an std::vector.

template<class T >
std::vector< T > createVector ( const ArrayView< T > &  av) [related]

Get a new std::vector<T> object out of an ArrayView<T> object.

Note that a copy of data is made!

template<class T >
std::vector< T > createVector ( const ArrayView< const T > &  av) [related]

Get a new std::vector<T> object out of an ArrayView<const T> object.

Note that a copy of data is made!

template<class T >
bool is_null ( const ArrayView< T > &  av) [related]

Returns true if av.is_null()==true.

template<class T >
bool nonnull ( const ArrayView< T > &  av) [related]

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

template<class T >
std::ostream & operator<< ( std::ostream &  out,
const ArrayView< T > &  av 
) [related]

Output stream inserter.

The implementation of this function just prints pointer addresses and therefore puts no restrictions on the data types involved.

template<class T2 , class T1 >
ArrayView< T2 > av_const_cast ( const ArrayView< T1 > &  p1) [related]

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

The function will compile only if (const_cast<T2*>(p1.get());) compiles.

template<class T2 , class T1 >
ArrayView< T2 > av_reinterpret_cast ( const ArrayView< T1 > &  p1) [related]

Reinterpret cast of underlying ArrayView 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.


Member Data Documentation

template<class T>
T* Teuchos::ArrayView< T >::ptr_ [private]

Definition at line 378 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
int Teuchos::ArrayView< T >::size_ [private]

Definition at line 379 of file Teuchos_ArrayViewDecl.hpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines