Workspace 6.21.5
Classes | Public Types | Public Member Functions | Protected Member Functions | List of all members
ArrayNd Class Referenceabstract

An interface to an n-dimensional array of a single workspace data type. More...

#include <DataAnalysis/DataStructures/arraynd.h>

Inheritance diagram for ArrayNd:
[legend]

Classes

class  const_iterator
 
class  const_iterator_range
 Represents a pair of iterators that bound a range of data (i.e. the begin and end corners of a multi-dimensional cube of data). More...
 

Public Types

typedef NamedDimensionRange::size_type size_type
 

Public Member Functions

 ArrayNd ()
 
 ~ArrayNd () override
 
virtual bool arrayAccessHint (const NamedDimensionRangeList &range)=0
 
const_iterator begin () const
 
ArrayNdclone () const override=0
 
const_iterator end () const
 
NamedDimensionRangeList getAllDimensions () const
 
virtual const DataCollectiongetAttributes () const =0
 
template<typename T >
bool getData (const NamedDimensionRangeList &range, T *data) const
 
virtual const DataExecution::DataFactorygetDataFactory () const =0
 
NamedDimensionRange getDimension (const QString &name) const
 
virtual int getDimensionIndex (const QString &name) const =0
 
virtual ArrayNdDimensionLabels getDimensionLabels (const QString &dimensionName) const =0
 
virtual QString getDimensionName (int index) const =0
 
virtual size_type getDimensionSize (const QString &name) const =0
 
virtual size_type getDimensionSize (int index) const =0
 
virtual double getFillValue () const =0
 
virtual QVariant getFillValueAsVariant () const =0
 
template<typename T >
ArrayNdTyped< T > * getTypedInterface ()
 
template<typename T >
const ArrayNdTyped< T > * getTypedInterface () const
 
virtual QVariant getValue (const DimensionIndexList &dimIndices) const =0
 
virtual QVariant getValue (size_type dim0, size_type dim1=0, size_type dim2=0, size_type dim3=0, size_type dim4=0) const =0
 
virtual bool hasFillValue () const =0
 
virtual bool isDimensionUnlimited (int index) const =0
 
virtual int numDimensions () const =0
 
virtual double operator() (const DimensionIndexList &dimIndices) const =0
 
virtual double operator() (size_type dim0, size_type dim1=0, size_type dim2=0, size_type dim3=0, size_type dim4=0) const =0
 
const_iterator_range range (const NamedDimensionRangeList &range) const
 
virtual bool setDimensions (const NamedDimensionRangeList &dimensions)=0
 
template<typename T >
bool setFillValue (const T &value)
 
virtual void setHasFillValue (bool b)=0
 
template<typename T >
bool writeData (const NamedDimensionRangeList &range, const T *data)
 
- Public Member Functions inherited from Clonable
virtual ~Clonable ()=default
 
virtual Clonableclone () const =0
 

Protected Member Functions

 ArrayNd (ArrayNd &&other)
 
 ArrayNd (const ArrayNd &other)
 
ArrayNdoperator= (const ArrayNd &other)=default
 

Detailed Description

The ArrayNd interface allows generic access to a dataset which contains multi-dimensional data of any Workspace data type, and of any number of dimensions. Concrete sub-classes are free to implement the underlying data storage in any way they wish.

Note
Implementations should extend the ArrayNdTyped interface, instead of extending this one directly. ArrayNdTyped provides several functions critical to reading / writing to / from type-specific datasets. There is no way to read or write data to / from this interface directly.

Member Typedef Documentation

◆ size_type

size_type is used to represent the indices and ranges of the dimensions in the ArrayNd. We have selected a 64bit integer, as we can expect considerably large datasets. It must be the same type as the NamedDimensionRange.

Constructor & Destructor Documentation

◆ ArrayNd() [1/3]

ArrayNd ( )
default

◆ ~ArrayNd()

~ArrayNd ( )
overridedefault

◆ ArrayNd() [2/3]

ArrayNd ( const ArrayNd other)
protecteddefault

◆ ArrayNd() [3/3]

ArrayNd ( ArrayNd &&  other)
protecteddefault

Member Function Documentation

◆ arrayAccessHint()

virtual bool arrayAccessHint ( const NamedDimensionRangeList range)
pure virtual
Parameters
rangeThe range we are expecting to read from when using the getValue or operator() functions.
Returns
true if the hint is valid, false if the dimensions or ranges were out of range.

The range we are hinting that we're about to access repeatedly through individual indexed reads (i.e. using the operator() function).

See also
operator()

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, ArrayNdSliceTyped< T >, ArrayNdTyped< T >, and ArrayNdTyped< double >.

◆ begin()

ArrayNd::const_iterator begin ( ) const
Returns
An iterator pointing to the first item in the dataset.

◆ clone()

ArrayNd * clone ( ) const
overridepure virtual
Returns
Return a clone of the ArrayNd object. This may or may not require copying all of the underlying data, depending on how it is stored / referenced (for example, an implementation that is copy-on-write will not need to replicate data until it is modified.

Implements Clonable.

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, ArrayNdSliceTyped< T >, ArrayNdTyped< T >, and ArrayNdTyped< double >.

◆ end()

ArrayNd::const_iterator end ( ) const
Returns
An iterator pointing to one item beyond the last item in the dataset.

◆ getAllDimensions()

NamedDimensionRangeList getAllDimensions ( ) const
Returns
Retrieves a list of all the dimensions in the Array.

◆ getAttributes()

virtual const DataCollection & getAttributes ( ) const
pure virtual
Returns
Returns a data collection containing top-level attribute data attached to the ArrayNd. These attributes may include elements such as "units", "cell dimensions", "description" etc.

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, and ArrayNdSliceTyped< T >.

◆ getData()

bool getData ( const NamedDimensionRangeList range,
T *  data 
) const
Parameters
rangeThe bounded range from which we are reading data. These dimensions must be specified in terms of the sliced dimensions, not the dimensions of the underlying base dataset.
dataThe data store into which we will write the data that we are reading from the dataset.

Template convenience function for getting data from an ArrayNd set without it being of a concrete type. The function will check whether the factories match before it attempts to add the data.

The data will be copied into the data parameter in column-major order, corresponding to the order of the dimensions in the dataset (the order of the input range is irrelevant). This means that the dimension with the highest index will vary the fastest.

Returns
true if the data was successfully retrieved from the dataset, false otherwise.

◆ getDataFactory()

virtual const DataExecution::DataFactory * getDataFactory ( ) const
pure virtual

◆ getDimension()

NamedDimensionRange getDimension ( const QString &  name) const
Returns
Retrieves a NamedDimensionRange containing all the parameters of a single dimension of the ArrayNd.

◆ getDimensionIndex()

virtual int getDimensionIndex ( const QString &  name) const
pure virtual
Parameters
nameThe name of the dimension for which we wish to rerieve its index.
Returns
The index of the dimension in the dataset.

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, and ArrayNdSliceTyped< T >.

◆ getDimensionLabels()

virtual ArrayNdDimensionLabels getDimensionLabels ( const QString &  dimensionName) const
pure virtual
Parameters
dimensionNameThe name of the dimension for which we wish to retrieve its labels.
Returns
The list of labels associated with the specified dimension.

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, and ArrayNdSliceTyped< T >.

◆ getDimensionName()

virtual QString getDimensionName ( int  index) const
pure virtual
Parameters
indexThe index of the dimension for which we wish to retrieve its name.
Returns
The name of the specified dimension.

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, and ArrayNdSliceTyped< T >.

◆ getDimensionSize() [1/2]

virtual size_type getDimensionSize ( const QString &  name) const
pure virtual
Parameters
nameThe name of the dimension for which we wish to retrieve its size, i.e. the number of elements in the specified dimension.
Returns
The number of elements in the specified dimension.

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, and ArrayNdSliceTyped< T >.

◆ getDimensionSize() [2/2]

virtual size_type getDimensionSize ( int  index) const
pure virtual
Parameters
indexThe index of the dimension for which we wish to retrieve its size, i.e. the number of elements in the specified dimension.
Returns
The number of elements in the specified dimension.

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, and ArrayNdSliceTyped< T >.

◆ getFillValue()

virtual double getFillValue ( ) const
pure virtual
Returns
The fill value used by the dataset.

The Fill Value of the dataset is used to indicate an 'empty' cell. Cells that do not contain any valid data, or data outside the known / valid range, will contain the fill value.

See also
hasFillValue
setHasFillValue
getFillValueAsVariant

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, ArrayNdSliceTyped< T >, ArrayNdTyped< T >, and ArrayNdTyped< double >.

◆ getFillValueAsVariant()

virtual QVariant getFillValueAsVariant ( ) const
pure virtual
Returns
The fill value used by the dataset contained within a QVariant.

The Fill Value of the dataset is used to indicate an 'empty' cell. Cells that do not contain any valid data, or data outside the known / valid range, will contain the fill value.

See also
hasFillValue
setHasFillValue
getFillValueAsVariant

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, ArrayNdSliceTyped< T >, ArrayNdTyped< T >, and ArrayNdTyped< double >.

◆ getTypedInterface() [1/2]

ArrayNdTyped< T > * getTypedInterface
Returns
Pointer to this ArrayNd object, of ArrayNdTyped<T> type.

◆ getTypedInterface() [2/2]

const ArrayNdTyped< T > * getTypedInterface
Returns
Pointer to this ArrayNd object, of ArrayNdTyped<T> type.

◆ getValue() [1/2]

virtual QVariant getValue ( const DimensionIndexList dimIndices) const
pure virtual
Parameters
dimIndicesThe set of coordinates at which we wish to inspect the value. The coordinate indices are assumed to be in the same order as they are stored in the dataset.
Returns
The data value for the specified cell, wrapping in a QVariant

Retrieve a single value from the underlying dataset using array subscript notation. The number of parameters supplied must match the underlying dataset. It is up to the developer to ensure that this always occurs.

The dimensions must be provided in the same order as they are stored in the dataset. This can be queried using getDimensionIndex() This version of the function returns a QVariant which contains the specific underlying type that matches the dataset.

See also
getDimensionIndex()
arrayAccessHint()
getTypedInterface()

Implemented in ArrayNdTyped< T >, ArrayNdTyped< double >, and ArrayNdEmpty.

◆ getValue() [2/2]

virtual QVariant getValue ( size_type  dim0,
size_type  dim1 = 0,
size_type  dim2 = 0,
size_type  dim3 = 0,
size_type  dim4 = 0 
) const
pure virtual
Parameters
dim0The index in the first dimension
dim1The index in the second dimension
dim2The index in the third dimension
dim3The index in the fourth dimension
dim4The index in the fifth dimension
Returns
A QVariant containing the value at the target coordinates in the dataset.

Retrieve a single value from the underlying dataset using array subscript notation. The number of parameters supplied MUST match the underlying dataset. It is up to the developer to ensure that this always occurs.

The dimensions must be provided in the same order as they are stored in the dataset. This can be queried using getDimensionIndex().

Note
If there are more than 5 dimensions in the dataset, is is recommended that you use the other overload of this function. All unspecified dimensions (i.e. dimensions at index 5 and above will be assumed as index zero).
See also
getDimensionIndex()
arrayAccessHint
getTypedInterface()

Implemented in ArrayNdTyped< T >, ArrayNdTyped< double >, and ArrayNdEmpty.

◆ hasFillValue()

virtual bool hasFillValue ( ) const
pure virtual
Returns
True if the dataset has a fill value defined, false otherwise.

The Fill Value of the dataset is used to indicate an 'empty' cell. Cells that do not contain any valid data, or data outside the known / valid range, will contain the fill value. This function returns a value indicating whether or not a fill value is being used.

See also
setHasFillValue
getFillValue
getFillValueAsVariant.

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, ArrayNdSliceTyped< T >, ArrayNdTyped< T >, and ArrayNdTyped< double >.

◆ isDimensionUnlimited()

virtual bool isDimensionUnlimited ( int  index) const
pure virtual
Parameters
indexThe index of the dimension we are inspecting.
Returns
true if the dimension is unlimited, false otherwise. An unlimited dimension is one that can by dynamically expanded "on write". For example, a time dimension where we do not know (up front) how many times there are going to be in the dataset, so we can create an "unlimited" dimension, and then repeatedly add to it.
Note
Not all ArrayNd implementations support unlimited dimensions, so in the majority of cases, this function will return false.

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, and ArrayNdSliceTyped< T >.

◆ numDimensions()

virtual int numDimensions ( ) const
pure virtual

◆ operator()() [1/2]

virtual double operator() ( const DimensionIndexList dimIndices) const
pure virtual
Parameters
dimIndicesThe set of coordinates at which we wish to inspect the value. The coordinate indices are assumed to be in the same order as they are stored in the dataset.
Returns
The data value for the specified cell, wrapping in a QVariant

Retrieve a single value from the underlying dataset using array subscript notation. The number of parameters supplied must match the underlying dataset. It is up to the developer to ensure that this always occurs.

The dimensions must be provided in the same order as they are stored in the dataset. This can be queried using getDimensionIndex()

See also
getDimensionIndex()
arrayAccessHint()
getTypedInterface()

Implemented in ArrayNdTyped< T >, ArrayNdTyped< double >, and ArrayNdEmpty.

◆ operator()() [2/2]

virtual double operator() ( size_type  dim0,
size_type  dim1 = 0,
size_type  dim2 = 0,
size_type  dim3 = 0,
size_type  dim4 = 0 
) const
pure virtual
Parameters
dim0The index in the first dimension
dim1The index in the second dimension
dim2The index in the third dimension
dim3The index in the fourth dimension
dim4The index in the fifth dimension
Returns
A QVariant containing the value at the target coordinates in the dataset.

Retrieve a single value from the underlying dataset using array subscript notation. The number of parameters supplied MUST match the underlying dataset. It is up to the developer to ensure that this always occurs.

The dimensions must be provided in the same order as they are stored in the dataset. This can be queried using getDimensionIndex().

Note
If there are more than 5 dimensions in the dataset, is is recommended that you use the other overload of this function. All unspecified dimensions (i.e. dimensions at index 5 and above will be assumed as index zero).
See also
getDimensionIndex()
arrayAccessHint
getTypedInterface()

Implemented in ArrayNdTyped< T >, ArrayNdTyped< double >, and ArrayNdEmpty.

◆ operator=()

ArrayNd & operator= ( const ArrayNd other)
protecteddefault

◆ range()

Returns
A pair of iterators that bounds the specified dimension range.

◆ setDimensions()

virtual bool setDimensions ( const NamedDimensionRangeList dimensions)
pure virtual
Parameters
dimensionsThe complete list of dimensions we want the dataset to have.
Returns
True if the dimensions of the dataset were successfully set.

Sets the dimensions of the dataset. This will result in the allocation of the underlying data storage. If the dataset previously contained data, this will result in a resize of the dataset, which may require the copying of data, the cost of which will vary greatly depending upon the implementation. For newly created cells in the dataset, a fill-value will be used (by default, this will be a default constructed object).

To avoid expensive copying, it is recommended to only invoke this function on an empty (i.e. uninitialized) dataset.

Note
Not all implementations may support this operation at all times. For example, some implementations may allow users to read from read-only datasets on disk.
See also
writeData
getData
setFillValue

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, and ArrayNdSliceTyped< T >.

◆ setFillValue()

bool setFillValue ( const T &  value)
Parameters
valueThe fill value which we are setting. Will be used to populate all new cells when setDimensions() is invoked.

Template convenience function for setting the fill value on an ArrayNd set without it being of a concrete type. The function will check whether the factories match before it attempts to add the data.

Returns
true if the fill value is set, false if it is of the wrong type or was not able to be set.

◆ setHasFillValue()

virtual void setHasFillValue ( bool  b)
pure virtual
Parameters
bWhether or not to use a fill value for this dataset. By default, the fill value will be the default constructed type of the underlying stored data.

The Fill Value of the dataset is used to indicate an 'empty' cell. Cells that do not contain any valid data, or data outside the known / valid range, will contain the fill value. This function allows the caller to indicate that a fill value is in use in the dataset.

See also
hasFillValue
getFillValue
getFillValueAsVariant

Implemented in ArrayNdEmpty, ArrayNdData< T >, ArrayNdData< double >, ArrayNdDimensionFilterTyped< T >, ArrayNdInterface< T >, ArrayNdPermutationTyped< T >, ArrayNdSliceTyped< T >, ArrayNdTyped< T >, and ArrayNdTyped< double >.

◆ writeData()

bool writeData ( const NamedDimensionRangeList range,
const T *  data 
)
Parameters
rangeThe bounded range to which we are writing the data. These dimensions must be specified in terms of the sliced dimensions, not the dimensions of the underlying base dataset.
dataThe data which we are going to write into the dataset.

Template convenience function for adding data to an ArrayNd set without it being of a concrete type. The function will check whether the factories match before it attempts to add the data.

The data will be copied into the data parameter in column-major order, corresponding to the order of the dimensions in the dataset (the order of the input range is irrelevant). This means that the dimension with the highest index will vary the fastest.

Returns
true if the data was added to the dataset successfully, false otherwise.