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(). The type you can request is any type for which a corresponding VarValueDecoder has been defined.

Definition at line 918 of file ezmatio.h.

Constructor & Destructor Documentation

§ Var()

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 951 of file ezmatio.h.

Member Function Documentation

§ dims()

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 1027 of file ezmatio.h.

§ getMatvarPtr()

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 1141 of file ezmatio.h.

§ hasData()

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 1070 of file ezmatio.h.

§ isComplex()

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 1050 of file ezmatio.h.

§ isSquareMatrix()

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 1059 of file ezmatio.h.

§ ndims()

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 1018 of file ezmatio.h.

§ numel()

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 1037 of file ezmatio.h.

§ operator=()

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

inline

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

Definition at line 1150 of file ezmatio.h.

§ takeOver()

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 999 of file ezmatio.h.

§ value() [1/2]

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 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 1116 of file ezmatio.h.

§ value() [2/2]

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 1131 of file ezmatio.h.

§ varName()

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 1008 of file ezmatio.h.

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

tomographer/tools/ezmatio.h (v5.4)

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

§ Var()

Member Function Documentation

§ dims()

§ getMatvarPtr()

§ hasData()

§ isComplex()

§ isSquareMatrix()

§ ndims()

§ numel()

§ operator=()

§ takeOver()

§ value() [1/2]

§ value() [2/2]

§ varName()