Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 >:
Teuchos::Tuple< T, N >

Public Types

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

Public Member Functions

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

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

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.

Examples:
ArrayRCP_test.cpp.

Definition at line 90 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 96 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 99 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 102 of file Teuchos_ArrayViewDecl.hpp.

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

Type of each array element.

Definition at line 105 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 110 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 113 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 118 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 121 of file Teuchos_ArrayViewDecl.hpp.

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

Type of a nonconst iterator.

Definition at line 130 of file Teuchos_ArrayViewDecl.hpp.

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

Type of a const iterator.

Definition at line 132 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 26 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 42 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 91 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 108 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 127 of file Teuchos_ArrayView.hpp.

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

Destructor.

Definition at line 169 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 146 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 182 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 196 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 211 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 280 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 287 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 308 of file Teuchos_ArrayView.hpp.

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

Get the first element.

Definition at line 325 of file Teuchos_ArrayView.hpp.

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

Get the last element.

Definition at line 341 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 361 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 394 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 407 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 422 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 439 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 449 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 466 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 489 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 515 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 533 of file Teuchos_ArrayView.hpp.

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.


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