Thyra::DetachedVectorView< Scalar > Class Template Reference
[Development of linear Abstract Numerical Algorithms (ANAs)]

Create an explicit mutable (non-const) view of a VectorBase object. More...

#include <Thyra_DetachedVectorView.hpp>

List of all members.

Public Member Functions
	DetachedVectorView (const Teuchos::RCP< VectorBase< Scalar > > &v, const Range1D &rng=Range1D(), const bool forceUnitStride=false)
	Construct an explicit mutable (non-const) view of a subset of elements.
	DetachedVectorView (VectorBase< Scalar > &v, const Range1D &rng=Range1D(), const bool forceUnitStride=false)
	Construct an explicit mutable (non-const) view of a subset of elements.
	~DetachedVectorView ()
	Commits back the the explicit view on the VectorBase object v passed to DetachedVectorView().
const RTOpPack::SubVectorView< Scalar > &	sv () const
	Returns the explicit view as an RTOpPack::ConstSubVectorView<Scalar> object.
Teuchos_Index	globalOffset () const
	Returns the global offset for the explicit view.
Teuchos_Index	subDim () const
	Returns the dimension of the explicit view.
Scalar *	values () const
	Return a pointer to a Scalar array containing the explicit view.
ptrdiff_t	stride () const
	Return the stride between elements in the array returned from this->values().
Scalar &	operator[] (Teuchos_Index i) const
	Zero-based indexing: Preconditions: values()!=NULL && (0 <= i < subDim()-1).
Scalar &	operator() (Teuchos_Index i) const
	Zero-based indexing: Preconditions: values()!=NULL && (0 <= i < subDim()-1).

---

Detailed Description

template<class Scalar>
class Thyra::DetachedVectorView< Scalar >

Create an explicit mutable (non-const) view of a VectorBase object.

This utility class makes it easy to explicitly access a contiguous subset of elements in any VectorBase object and change the VectorBase object.

Warning! Creating an explicit view of an arbitrary VectorBase object may be a very expensive operation (such as with distributed-memory vectors) and should only be done in special cases (such as when the vector is an in-core vector). There several specialized use cases where creating these types of explicit views are necessary but in most cases this should not be done.

The following functions show four different ways to access a range of elements from in any VectorBase object and then add to them the values form a raw C++ array.

 //
 // Add-to using unit-strided pointer access
 //
 template<class Scalar>
 void addToArrayPointerUnit(
   const Thyra::Range1D            &rng
   ,const Scalar                   x[]   // Size == rng.size()
   ,Thyra::VectorBase<Scalar>      *v
   )
 {
    Thyra::DetachedVectorView<Scalar> v_ev(rng,*v,true);  // Force unit stride
    const Scalar *v_ptr = v_ev.values();                         // Get pointer to unit-stride data
    for( int k = 0; k < n; ++k )                                 // For each element in view:
      v_ptr[k] += x[k];                                          //   Add-to elements
    // When this function returns then v_ev will be destroyed and the view will be committed back and *v modified
 }

 //
 // Add-to using non-unit-strided pointer access
 //
 template<class Scalar>
 void addToArrayPointerNonunit(
   const Thyra::Range1D          &rng
   ,const Scalar                 x[]   // Size == rng.size()
   ,Thyra::VectorBase<Scalar>    *v
   )
 {
    Thyra::DetachedVectorView<Scalar> v_ev(rng,*v);   // Allow non-unit stride
    const Scalar          *v_ptr    = v_ev.values();         // Get pointer to non-unit-stride data
    const Thyra::Index  *v_stride = v_ev.stride();           // Get stride between vector data
    for( int k = 0; k < rng.size(); ++k, v_ptr += v_stride ) // For each element in view:
      *v_ptr + x[k];                                         //   Add-to elements
    // When this function returns then v_ev will be destroyed and the view will be committed back and *v modified
 }

 //
 // Add-to using possibly non-unit stride with zero-based overloaded function operator[]()
 //
 template<class Scalar>
 void addToArrayZeroBasedOperator(
   const Thyra::Range1D          &rng
   ,const Scalar                 x[]   // Size == rng.size()
   ,Thyra::VectorBase<Scalar>    *v
   )
 {
    Thyra::DetachedVectorView<Scalar> v_ev(rng,*v);   // Allow non-unit stride 
    for( int k = 0; k < rng.size(); ++k )                    // For each element in view:
      v_ev[k] += x[k];                                       //   Add-to elements using operator[]()
    // When this function returns then v_ev will be destroyed and the view will be committed back and *v modified
 }

 //
 // Add-to using possibly non-unit stride with zero-based overloaded function operator()()
 //
 template<class Scalar>
 void addToArrayOneBasedOperator(
   const Thyra::Range1D          &rng
   ,const Scalar                 x[]   // Size == rng.size()
   ,Thyra::VectorBase<Scalar>    *v
   )
 {
    Thyra::DetachedVectorView<Scalar> v_ev(rng,*v); // Allow non-unit stride 
    for( int k = 0; k < rng.size(); ++k )                  // For each element in view:
      v_ev(k) += x[k];                                     //   Add-to elements using operator()()
    // When this function returns then v_ev will be destroyed and the view will be committed back and *v modified
 }

If one wants to only read the elements in a VectorBase object then one should use the utility class ConstDetachedVectorView.

The default constructor, copy constructor and assignment operators are not allowed.

Definition at line 338 of file Thyra_DetachedVectorView.hpp.

---

Constructor & Destructor Documentation

template<class Scalar>

Thyra::DetachedVectorView< Scalar >::DetachedVectorView	(	const Teuchos::RCP< VectorBase< Scalar > > &	v,
		const Range1D &	rng = Range1D(),
		const bool	forceUnitStride = false
	)			[inline]

Construct an explicit mutable (non-const) view of a subset of elements.

Parameters:

	v	[in] The vector that a view will be taken. This object must be maintained until *this is destroyed. The elements in v are not guaranteed to be updated until *this is destroyed.
	rng	[in] the range of element indices that the explicit view will be taken.
	forceUnitStride	[in] If true then the view will have unit stride.

Preconditions:

• [rng.full_range()==false] rng.ubound() < v.space()->dim()

Postconditions:

• this->sv() returns the created view
• this->globalOffset()==rng.lbound()
• this->subDim()==rng.size()
• this->values() returns a pointer to a Scalar array
• this->stride() returns the stride between the elements pointed it in this->values()
• [forceUnitStride==true] this->stride()==1

Definition at line 362 of file Thyra_DetachedVectorView.hpp.

template<class Scalar>

Thyra::DetachedVectorView< Scalar >::DetachedVectorView	(	VectorBase< Scalar > &	v,
		const Range1D &	rng = Range1D(),
		const bool	forceUnitStride = false
	)			[inline]

Construct an explicit mutable (non-const) view of a subset of elements.

Parameters:

	v	[in] The vector that a view will be taken. This object must be maintained until *this is destroyed. The elements in v are not guaranteed to be updated until *this is destroyed.
	rng	[in] the range of element indices that the explicit view will be taken.
	forceUnitStride	[in] If true then the view will have unit stride.

Preconditions:

• [rng.full_range()==false] rng.ubound() < v.space()->dim()

Postconditions:

• this->sv() returns the created view
• this->globalOffset()==rng.lbound()
• this->subDim()==rng.size()
• this->values() returns a pointer to a Scalar array
• this->stride() returns the stride between the elements pointed it in this->values()
• [forceUnitStride==true] this->stride()==1

Definition at line 391 of file Thyra_DetachedVectorView.hpp.

template<class Scalar>

Thyra::DetachedVectorView< Scalar >::~DetachedVectorView

(

)

[inline]

Commits back the the explicit view on the VectorBase object v passed to DetachedVectorView().

Definition at line 396 of file Thyra_DetachedVectorView.hpp.

---

Member Function Documentation

template<class Scalar>

const RTOpPack::SubVectorView<Scalar>& Thyra::DetachedVectorView< Scalar >::sv

(

)

const [inline]

Returns the explicit view as an RTOpPack::ConstSubVectorView<Scalar> object.

Definition at line 413 of file Thyra_DetachedVectorView.hpp.

template<class Scalar>

Teuchos_Index Thyra::DetachedVectorView< Scalar >::globalOffset

(

)

const [inline]

Returns the global offset for the explicit view.

Definition at line 415 of file Thyra_DetachedVectorView.hpp.

template<class Scalar>

Teuchos_Index Thyra::DetachedVectorView< Scalar >::subDim

(

)

const [inline]

Returns the dimension of the explicit view.

Definition at line 417 of file Thyra_DetachedVectorView.hpp.

template<class Scalar>

Scalar* Thyra::DetachedVectorView< Scalar >::values

(

)

const [inline]

Return a pointer to a Scalar array containing the explicit view.

Definition at line 419 of file Thyra_DetachedVectorView.hpp.

template<class Scalar>

ptrdiff_t Thyra::DetachedVectorView< Scalar >::stride

(

)

const [inline]

Return the stride between elements in the array returned from this->values().

Definition at line 421 of file Thyra_DetachedVectorView.hpp.

template<class Scalar>

Scalar& Thyra::DetachedVectorView< Scalar >::operator[]

(

Teuchos_Index

i

)

const [inline]

Zero-based indexing: Preconditions: values()!=NULL && (0 <= i < subDim()-1).

Definition at line 423 of file Thyra_DetachedVectorView.hpp.

template<class Scalar>

Scalar& Thyra::DetachedVectorView< Scalar >::operator()

(

Teuchos_Index

i

)

const [inline]

Zero-based indexing: Preconditions: values()!=NULL && (0 <= i < subDim()-1).

Definition at line 425 of file Thyra_DetachedVectorView.hpp.

---

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

• Thyra_DetachedVectorView.hpp

---