Nonowning array view. More...

#include <Teuchos_ArrayViewDecl.hpp>

Inheritance diagram for Teuchos::ArrayView< T >:

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 ConstTypeTraits< T >::NonConstType > &vec)
	Create a nonconst view of an std::vector<T>. More...

	ArrayView (const std::vector< typename ConstTypeTraits< T >::NonConstType > &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` or`this->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

T	The 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:

T must be default constructible.
T must be copy constructible.
TypeNameTraits must have a specialization for T.

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 123 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 140 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 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:

this->get() != NULL
0 <= i && i < this->size()

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 391 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 397 of file Teuchos_ArrayViewDecl.hpp.

template<class T>

void Teuchos::ArrayView< T >::debug_assert_valid_ptr ( ) const

inlineprivate

Definition at line 404 of file Teuchos_ArrayViewDecl.hpp.

template<class T>

T* Teuchos::ArrayView< T >::access_private_ptr ( ) const

inline

Definition at line 414 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
	)

template<class T >

ArrayView< T > arrayViewFromVector ( std::vector< T > & vec )

template<class T >

ArrayView< const T > arrayViewFromVector ( const std::vector< T > & vec )

template<class T >

std::vector< T > createVector ( const ArrayView< T > & av )

Note that a copy of data is made!

template<class T >

std::vector< T > createVector ( const ArrayView< const T > & av )

Note that a copy of data is made!

template<class T >

bool is_null ( const ArrayView< T > & av )

template<class T >

bool nonnull ( const ArrayView< T > & av )

template<class T >

std::ostream & operator<<	(	std::ostream &	out,
		const ArrayView< T > &	av
	)

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 )

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 )

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 383 of file Teuchos_ArrayViewDecl.hpp.

template<class T>

size_type Teuchos::ArrayView< T >::size_

private

Definition at line 384 of file Teuchos_ArrayViewDecl.hpp.

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

Public Member Functions

Private Member Functions

Private Attributes

Related Functions

Public typedefs

Constructors/Destructors

General query functions

Element Access Functions

Views

Assignment

Standard Container-Like Functions

Assertion Functions.

Detailed Description

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

Optional bounds checking

Requirements on the type T

Design discussion

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

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