Tomographer  v1.0a
Tomographer C++ Framework Documentation
Classes | Public Member Functions | Static Public Member Functions | List of all members
Tomographer::MAT::Var Class Reference

A MATLAB variable in the MAT file. More...

#include <tomographer/tools/ezmatio.h>

Public Member Functions

 Var (File &matf, const std::string &varname, bool load_data=true)
 Read variable from MATLAB data file. More...
 
 Var (const Var &copy)
 Var objects are copyable. Beware though that the data is shared.
 
 Var (Var &&other)
 Var implements C++11 move semantics.
 
const std::string & varName () const
 The variable name. More...
 
int ndims () const
 Number of dimensions of this object. More...
 
DimList dims () const
 Specific dimensions of this numeric array or tensor. More...
 
int numel () const
 The total number of elements in this array or tensor. More...
 
bool isComplex () const
 Whether this variable is complex or real. More...
 
bool isSquareMatrix () const
 Whether this is a square matrix. More...
 
bool hasData () const
 Whether data for this Var object has been loaded. More...
 
template<typename T >
VarValueDecoder< T >::RetType value () const
 Read this variable data as native C++ object. More...
 
template<typename T , ENABLED_IF(tomo_internal::has_params_member< VarValueDecoder< T > >::value) >
VarValueDecoder< T >::RetType value (const typename VarValueDecoder< T >::Params &params)
 Read this variable data as native C++ object. More...
 
const matvar_t * getMatvarPtr () const
 Access the underlying C pointer to the MatIO structure. Use with care. More...
 
Var & operator= (Var &&other)
 Move assignment operator as this object implements C++11 move semantics. More...
 
Var & operator= (const Var &copy)
 Var objects are copyable. Beware though that the data is shared.
 

Static Public Member Functions

static Var takeOver (matvar_t *varinfo)
 Take in charge the given C matvar_t pointer. More...
 

Detailed Description

A MATLAB variable in the MAT file.

This object is a wrapper around MatIO's API for reading data of a variable in the data file.

This object can be moved around using C++11 move semantics. Also, this object is copyable. (But don't modify the object, as the data is shared.)

Var objects may, or may not, have the actual data loaded (hasData()). If no data is loaded, information about the variable (type, shape, etc.) may be accessed. There is currently no way to load the data subsequently for the same Var object, just re-construct a new Var object.

To read the data, you should use the template method value<T>(). The type you can request is any type for which a corresponding VarValueDecoder<T> has been defined.

Definition at line 851 of file ezmatio.h.

Constructor & Destructor Documentation

Tomographer::MAT::Var::Var ( File &  matf,
const std::string &  varname,
bool  load_data = true 
)
inline

Read variable from MATLAB data file.

This constructor initializes this variable from the given open MATLAB data file matf by looking up the variable named varname.

If load_data is true, then the data is also loaded. Otherwise, only the type and shape information is loaded. See hasData().

Calling this constructor directly is the same as calling File::var().

Definition at line 884 of file ezmatio.h.

Member Function Documentation

DimList Tomographer::MAT::Var::dims ( ) const
inline

Specific dimensions of this numeric array or tensor.

This returns a DimList, which is essentially a std::vector<int>.

Definition at line 960 of file ezmatio.h.

const matvar_t* Tomographer::MAT::Var::getMatvarPtr ( ) const
inline

Access the underlying C pointer to the MatIO structure. Use with care.

Please be careful as the data is shared between different copies of Var objects.

Definition at line 1073 of file ezmatio.h.

bool Tomographer::MAT::Var::hasData ( ) const
inline

Whether data for this Var object has been loaded.

If not, then to access data (e.g. value<T>()), then you need to re-obtain a fresh Var object with data loaded.

Definition at line 1003 of file ezmatio.h.

bool Tomographer::MAT::Var::isComplex ( ) const
inline

Whether this variable is complex or real.

Returns true if the data stored by this variable is complex.

If the data is complex, then the variable pointer's data is in fact a pointer to a mat_complex_split_t which stores the real and imaginary parts of the array separately. See MatIO's documentation for more info.

Definition at line 983 of file ezmatio.h.

bool Tomographer::MAT::Var::isSquareMatrix ( ) const
inline

Whether this is a square matrix.

Return true if this variable has 2 dimensions which are equal, or false otherwise.

Definition at line 992 of file ezmatio.h.

int Tomographer::MAT::Var::ndims ( ) const
inline

Number of dimensions of this object.

This is called the ‘rank’ of the tensor in MatIO terminology.

Definition at line 951 of file ezmatio.h.

int Tomographer::MAT::Var::numel ( ) const
inline

The total number of elements in this array or tensor.

Returns the product of all the dimensions of this array or tensor.

Definition at line 970 of file ezmatio.h.

Var& Tomographer::MAT::Var::operator= ( Var &&  other)
inline

Move assignment operator as this object implements C++11 move semantics.

Definition at line 1082 of file ezmatio.h.

static Var Tomographer::MAT::Var::takeOver ( matvar_t *  varinfo)
inlinestatic

Take in charge the given C matvar_t pointer.

This static method yields an instance of Var directly initialized with the given variable pointer. The object takes ownership of the pointer, and will call Mat_VarFree when the last Var copy sharing this data will be destructed.

Definition at line 932 of file ezmatio.h.

template<typename T >
VarValueDecoder<T>::RetType Tomographer::MAT::Var::value ( ) const
inline

Read this variable data as native C++ object.

This function returns the data stored by the variable in a C++ object of type T.

The type T may be any type for which a specialization of VarValueDecoder<T> has been defined.

Examples:

// Read a variable in the file named 'my_scalar_variable'
Var scalar_var = matfile.var("my_scalar_variable");
// get the scalar variable as a float. This will raise an exception if
// 'my_scalar_variable' is an array with several elements.
float scalar_f = scalar_var.value<float>();
// same: get the scalar variable as a double.
double scalar_f = scalar_var.value<double>();
// Read a variable in the file named 'my_matrix_variable'
Var matrix_var = matfile.var("my_matrix_variable");
// get the data as an Eigen::MatrixXd
Eigen::MatrixXd matrix = matrix_var.value<Eigen::MatrixXd>();
// get the data in an std::vector<double>, stored with row-major ordering
std::vector<double> vecdata = matrix_var.value<GetStdVector<double,true> >();
// read complex variables using std::complex<floating-point-type> :
Var cmatrix_var = matfile.var("my_complex_matrix_variable");
Eigen::MatrixXcd cmatrix = cmatrix_var.value<Eigen::MatrixXcd>();
std::vector<std::complex<double> > cvecdata
= cmatrix_var.value<GetStdVector<std::complex<double>,true> >();

You may also equivalently call Tomographer::MAT::value<T>:

Eigen::MatrixXd matrix = var.value<Eigen::MatrixXd>();
// is equivalent to:
Eigen::MatrixXd matrix = Tomographer::MAT::value<Eigen::MatrixXd>(var);

Definition at line 1048 of file ezmatio.h.

template<typename T , ENABLED_IF(tomo_internal::has_params_member< VarValueDecoder< T > >::value) >
VarValueDecoder<T>::RetType Tomographer::MAT::Var::value ( const typename VarValueDecoder< T >::Params &  params)
inline

Read this variable data as native C++ object.

See value<T>().

This overload accepts an additional params parameter, but only if the corresponding VarValueDecoder<T> accepts it. This is in case the behavior of the decoding should depend on additional parameters given at runtime. Currently, no built-in VarValueDecoder<T> specializations use this.

Definition at line 1063 of file ezmatio.h.

const std::string& Tomographer::MAT::Var::varName ( ) const
inline

The variable name.

Returns the name of the MATLAB variable this object is referring to.

Definition at line 941 of file ezmatio.h.

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