dataview_interface< T > Class Template Reference
[Data blocks and data views]

The abstract base class for all data views. PARTIAL DOCUMENTATION! More...

#include <dataview.h>

Inherited by matrixview< T >, and vectorview< T >.

Inheritance diagram for dataview_interface< T >:

[legend]List of all members.

Public Member Functions
virtual bool	Valid () const =0
	Should return TRUE if and only if the view has been properly initialized. Doesn't check parameters for sanity!
virtual itype	Dimensionality () const =0
	Should return the number of indices required to define an element in this view.
virtual itype	Size () const =0
	Should return the total size of the view -- i.e., the product of the virtual ranges.
virtual itype	Range (itype i) const =0
	Should return the virtual range of index i.
virtual bool	Is1DCompatible () const =0
	Should return TRUE if and only if this view provides 1-D strided access.
virtual bool	Is2DCompatible () const =0
	Should return TRUE if and only if this view provides 2-D semi-contiguous strided access.
virtual T *	Get1DRep (itype &n_elements, itype &stride) const =0
virtual T *	Get2DRep (itype &n_series, itype &series_range, itype &series_extent) const =0
virtual T &	item (itype index) const =0
virtual T &	element (itype *iarr) const =0
virtual T &	element (itype i1,...) const =0
virtual void	PrettyPrint (std::ostream &os=std::cout) const =0
virtual void	DataPrint (std::ostream &os=std::cout) const =0
virtual void	OwnData (bool copy)=0
virtual void	FillFromStream (std::istream &is, bool clear=true)=0
virtual void	InitFromStream (std::istream &is)=0
Protected Member Functions
virtual datablock< T > *	GetDataBlock () const =0
	Each dataview is attached to a datablock; this should give access to it. Only usable from derived classes (i.e., views).

---

Detailed Description

template<class T>
class dataview_interface< T >

The abstract base class for all data views. PARTIAL DOCUMENTATION!

The dataview_interface class defines the interface that every dataview must provide. Basically, it has to act like a multidimensional array (of some possibly fixed dimension), attached to a datablock.

---

Member Function Documentation

template<class T> virtual bool dataview_interface< T >::Is1DCompatible (   )  const [pure virtual]

Should return TRUE if and only if this view provides 1-D strided access. In other words, the data elements must be evenly spaced -- spacing of 1 means contiguous. There must exist a T* ptr and an int K such that every element X of the view is accessible as X = ptr[ N * K ] for some N in {0...Size()-1}. Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual bool dataview_interface< T >::Is2DCompatible (   )  const [pure virtual]

Should return TRUE if and only if this view provides 2-D semi-contiguous strided access. In other words, the data must be arranged in evenly spaced blocks, e.g. as blocks of length L followed by gaps of length K-L. There must exist a T* ptr and int K such that every element X of the view is accessible as X = ptr[ M + N * K ] for some N,M. Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual T* dataview_interface< T >::Get1DRep (  itype &  n_elements, itype &  stride )  const [pure virtual]

If the view is 1D compatible, should provide its 1D representation in n_elements and stride, and the returned pointer. See Is1DCompatible(). Using the notation defined there, this function should: place Size() in n_elements, place K in stride, return ptr Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual T* dataview_interface< T >::Get2DRep (  itype &  n_series, itype &  series_range, itype &  series_extent )  const [pure virtual]

If the view is 2D compatible, should provide its 2D representation in n_series, series_range, series_extent, and the returned pointer. See Is2DCompatible(). Using the notation defined there, this function should: place Range(0) in n_series, place Range(1) in series_range, return K in series_extent Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual T& dataview_interface< T >::item (  itype  index  )  const [pure virtual]

Should return a unique element corresponding to index, as long as index is in [0...Size()-1]. If the view has a 1DRep or 2DRep, then the ordering of the elements must agree with the ordering in that representation. Otherwise, there are no ordering requirements. Every element in the view must be accessible through this function, for some index in [0...Size()-1]. Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual T& dataview_interface< T >::element (  itype *  iarr  )  const [pure virtual]

Should return a unique element corresponding to the set of indices iarr. iarr must contain Dimensionality() indices, and iarr[i] must be in [0...Range(i)-1]. if Dimensionality() = 1, this function must agree with item( iarr[0] ). If the view has a 2DRep, the ordering must agree with it. Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual T& dataview_interface< T >::element (  itype  i1,   ... )  const [pure virtual]

Should return a unique element corresponding to the first Dimensionality() parameters passed. This function must behave identically to element( itype* iarr ) when Dimensionality() parameters are given. Extra parameters must be ignored. Behavior is undefined when insufficient parameters given. Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual void dataview_interface< T >::PrettyPrint (  std::ostream &  os = std::cout  )  const [pure virtual]

Should print the elements of the view to os, formatted for human reading. The exact format of printing is flexible -- it should be maximally readable for users. Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual void dataview_interface< T >::DataPrint (  std::ostream &  os = std::cout  )  const [pure virtual]

Should print the elements of the view, arranged in columnar form, to os. Unlike PrettyPrint(), DataPrint should follow a fairly strict format. 1 dimensional views should be printed as "lines": sequences of numbers (of type T), separated by spaces. The numbers themselves should not contain spaces, or if they must, they should be enclosed in quotes. 2 dimensional views should be printed as "blocks": sequences of "lines" (see above), separated by newline characters. 3 dimensional views should be printed as a sequence of "blocks", separated by double newlines. For 4 and higher dimensions, proceed recursively, separating N-dimensional "hyperblocks" by N newlines. Thus, e.g., a 4D view should be printed as a sequence of 3D views, separated by triple newlines. Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual void dataview_interface< T >::OwnData (  bool  copy  )  [pure virtual]

Ensures that the view has sole access to its datablock, by creating a virgin copy if necessary. The purpose of OwnData() is to permit the view to ensure that it has sole control of the data that it references, possibly resizing it. Note that there is no way to tell who "owns" a block of data -- it is possible, although not explicitly supported through data_view, to identify how many views on a given datablock exist, but none of them have special "owner" rights. Thus, OwnData simply initializes new data and discards the old data. Note that the old data is copied only if copying is explicitly requested, since that can be slow. Also, it is permitted for a view to ignore this call IF-AND-ONLY-IF the reference count for its datablock is 1, meaning it already owns it. Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual void dataview_interface< T >::FillFromStream (  std::istream &  is, bool  clear = true )  [pure virtual]

Should read in elements from a tabular data stream, and fill this view with them. The FillFromStream() function is the input version of DataPrint(). It should read from a tabular data stream, where the format is simply T's separated by whitespace, with a newline for each end- of-series. Thus, a 2D dataset will have single newlines after each series, while a 3D dataset will have 2D blocks separated by double newlines. FillFromStream() maintains the current dimensions of the view, but replaces as much data as possible with that obtained from the stream. If clear = TRUE, then it will set all elements not specified by the stream to 0. See also InitFromStream(). Implemented in vectorview< T >, and matrixview< T >.

template<class T> virtual void dataview_interface< T >::InitFromStream (  std::istream &  is  )  [pure virtual]

Should reconstruct this view (changing size if necessary) to hold elements read in from a tabular data stream. InitFromStream should read from a tabular data stream, where the format is simply T's separated by whitespace, with a newline for each end- of-series. Thus, a 2D dataset will have single newlines after each series, while a 3D dataset will have 2D blocks separated by double newlines. It then resizes the view to be just large enough to hold all that data, and fills it with the data read in. Elements not specified in the input stream will be set to zero. See also FillFromStream(). Implemented in vectorview< T >, and matrixview< T >.

---

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

• dataview.h

---