Tomographer::MAT::VarShape Struct Reference

Describe shape of variable and whether it is complex. More...

#include <tomographer/tools/ezmatio.h>

Collaboration diagram for Tomographer::MAT::VarShape:

Public Member Functions
template<typename DimListType >
	VarShape (bool is_complex_, DimListType &&dims_, bool is_square_)
	Construct a VarShape object from given characteristics. More...
	VarShape (const Var &var)
	Construct a VarShape object reflecting the actual shape of a variable in the data file. More...
void	checkShape (const VarShape &shape)
	Verify that our requirements match the given other shape. More...
void	checkShape (const Var &var)
	Shorthand for checkShape(const VarShape& other) for a shape given by a variable. More...

Public Attributes
const bool	is_complex
	Whether the variable is or should be complex. More...
const DimList	dims
	The dimensions of the variable, or requested dimensions. More...
const bool	is_square
	Whether the variable's two first dimensions are (or should be) the same. More...

Detailed Description

Describe shape of variable and whether it is complex.

Allows to check a matlab variable for correct shape, for example.

This struct stores attributes of a variable, or attributes which one would require a variable to have. You can create a VarShape which represents an actual MATLAB variable, or you can also create a VarShape describing the characteristics which you'd want a loaded MATLAB variable to have, and then test that shape agains the actual variable.

This simple struct stores:

• whether the variable is complex or not (is_complex);
• the dimensions of the variable, i.e. a list of integers (dims);
• whether the variable is or should be square, i.e. whether the two first dimensions are or have to be equal (is_square).

The dimensions dims may contain -1 entries, which indicate that the particular dimension is not fixed (i.e. doesn't have a particular requirement).

You may check whether a particular requirement given as a VarShape matches the actual shape of a variable using checkShape(const Var & var), or more generally whether it matches another VarShape using checkShape(const VarShape& varshape).

Example:

VarShape shape(true, DimList() << 4 << 4, false);
Var v = matfile.var("my_variable");
try {
  std::cout << "Decoding '" << v.varName() << "' into a " << shape << "\n";
  shape.checkShape(v);
  // The variable 'my_variable' in the data file is indeed a 4x4 square
  // real or complex matrix.
  std::cout << "OK\n";
} catch (const VarTypeError & err) {
  std::cout << "Error: " << err.what() << "\n";
}

You may also stream a VarShape into an std::ostream for formatting, as in the example.

Definition at line 1559 of file ezmatio.h.

Constructor & Destructor Documentation

VarShape() [1/2]

template<typename DimListType >

Tomographer::MAT::VarShape::VarShape ( bool  is_complex_, DimListType &&  dims_, bool  is_square_  )

inline

Construct a VarShape object from given characteristics.

This simply initializes the fields and checks consistency of the given fields.

Definition at line 1607 of file ezmatio.h.

VarShape() [2/2]

Tomographer::MAT::VarShape::VarShape ( const Var &  var )

inline

Construct a VarShape object reflecting the actual shape of a variable in the data file.

The fields are initialized from the values of the actual variable.

Definition at line 1618 of file ezmatio.h.

Member Function Documentation

checkShape() [1/2]

void Tomographer::MAT::VarShape::checkShape ( const VarShape &  shape )

inline

Verify that our requirements match the given other shape.

If the shape does not satisfy the requirements of this VarShape object, then throw a VarTypeError. The requirements are described in the class documentation and in the individual member documentations for is_complex, dims and is_square.

Definition at line 1687 of file ezmatio.h.

checkShape() [2/2]

void Tomographer::MAT::VarShape::checkShape ( const Var &  var )

inline

Shorthand for checkShape(const VarShape& other) for a shape given by a variable.

Note

If you have a variable to check against, it is advantageous to use this method instead of checkShape(const VarShape& shape) as any thrown exception will also contain the name of the variable and thus be more informative.

Definition at line 1650 of file ezmatio.h.

Member Data Documentation

dims

const DimList Tomographer::MAT::VarShape::dims

The dimensions of the variable, or requested dimensions.

If you are describing the requested dimensions of a variable, you can set some dimensions to -1 to signify that they can assume any value. For example, if you want a matrix with three rows but any number of columns, you may set

dims = DimList() << 3 << -1;

This property can be left empty to signify that there should be no constraint on the dimensions of the MATLAB variable.

See also DimList::matchesWanted()

Definition at line 1584 of file ezmatio.h.

is_complex

const bool Tomographer::MAT::VarShape::is_complex

Whether the variable is or should be complex.

When describing a requirement, it is OK if the requirement is to be complex but the variable is real, and the shapes will be reported to match. (This is natural as a real MATLAB variable is easily decoded into a complex C++ object.)

Definition at line 1568 of file ezmatio.h.

is_square

const bool Tomographer::MAT::VarShape::is_square

Whether the variable's two first dimensions are (or should be) the same.

This flag encodes a requirement that the two first dimensions of a matrix must be equal. For example, to ensure that an input variable is a list of three square matrices (of any but same size) encoded as Mat(:,:,i), then you may set

dims = DimList() << -1 << -1 << 3;
is_square = true;

If is_square is false, this does not indicate that the variable is requested to have a non-square shape. If is_square is false, the variable may have any shape.

Definition at line 1600 of file ezmatio.h.

---

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

• tomographer/tools/ezmatio.h (v5.3)