Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Private Member Functions | Private Attributes | Related Functions | List of all members
Teuchos::ArrayView< T > Class Template Reference

Nonowning array view. More...

#include <Teuchos_ArrayViewDecl.hpp>

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

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_
 
size_type 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. More...
 
template<class T >
ArrayView< T > arrayViewFromVector (std::vector< T > &vec)
 Construct a non-const view of an std::vector. More...
 
template<class T >
ArrayView< const T > arrayViewFromVector (const std::vector< T > &vec)
 Construct a const view of an std::vector. More...
 
template<class T >
std::vector< T > createVector (const ArrayView< T > &av)
 Get a new std::vector<T> object out of an ArrayView<T> object. More...
 
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. More...
 
template<class T >
bool is_null (const ArrayView< T > &av)
 Returns true if av.is_null()==true. More...
 
template<class T >
bool nonnull (const ArrayView< T > &av)
 Returns true if av.get()!=NULL. More...
 
template<class T >
std::ostream & operator<< (std::ostream &out, const ArrayView< T > &av)
 Output stream inserter. More...
 
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*. More...
 
template<class T2 , class T1 >
ArrayView< T2 > av_reinterpret_cast (const ArrayView< T1 > &p1)
 Reinterpret cast of underlying ArrayView type from T1* to T2*. More...
 

Public typedefs

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

Constructors/Destructors

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

General query functions

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

Element Access Functions

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

Views

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

Assignment

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

Standard Container-Like Functions

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

Assertion Functions.

const ArrayView< T > & assert_not_null () const
 Throws NullReferenceError if this->get()==NULL, otherwise returns reference to *this. More...
 
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 More...
 

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 122 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 128 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 131 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 134 of file Teuchos_ArrayViewDecl.hpp.

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

Type of each array element.

Definition at line 137 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 142 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 145 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 150 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 153 of file Teuchos_ArrayViewDecl.hpp.

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

Type of a nonconst iterator.

Definition at line 162 of file Teuchos_ArrayViewDecl.hpp.

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

Type of a const iterator.

Definition at line 164 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 123 of file Teuchos_ArrayView.hpp.

template<class T>
Teuchos::ArrayView< T >::ArrayView ( std::vector< typename std::remove_const_t< T >> &  vec)
inline

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

Definition at line 140 of file Teuchos_ArrayView.hpp.

template<class T>
Teuchos::ArrayView< T >::ArrayView ( const std::vector< typename std::remove_const_t< T >> &  vec)
inline

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

Definition at line 159 of file Teuchos_ArrayView.hpp.

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

Destructor.

Definition at line 201 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 178 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 214 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 228 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 243 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 312 of file Teuchos_ArrayView.hpp.

template<class T >
T * Teuchos::ArrayView< T >::data ( ) const
inline

Return a raw pointer to beginning of array.

Same semantics as getRawPtr (which see).

Definition at line 319 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 340 of file Teuchos_ArrayView.hpp.

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

Get the first element.

Definition at line 357 of file Teuchos_ArrayView.hpp.

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

Get the last element.

Definition at line 373 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 393 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 426 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 439 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 454 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 471 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 481 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 498 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 521 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 547 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 565 of file Teuchos_ArrayView.hpp.

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

Definition at line 637 of file Teuchos_ArrayView.hpp.

template<class T>
void Teuchos::ArrayView< T >::debug_assert_not_null ( ) const
inlineprivate

Definition at line 390 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
void Teuchos::ArrayView< T >::debug_assert_in_range ( size_type  offset,
size_type  size_in 
) const
inlineprivate

Definition at line 396 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
void Teuchos::ArrayView< T >::debug_assert_valid_ptr ( ) const
inlineprivate

Definition at line 403 of file Teuchos_ArrayViewDecl.hpp.

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

Definition at line 413 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 382 of file Teuchos_ArrayViewDecl.hpp.

template<class T>
size_type Teuchos::ArrayView< T >::size_
private

Definition at line 383 of file Teuchos_ArrayViewDecl.hpp.


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