Encapsulating a MATLAB mxArray. More...

#include <value.hpp>

Inheritance diagram for ValueMex:

Collaboration diagram for ValueMex:

Public Types
enum	type_complexity_e { TC_EMPTY = 0, TC_SIMPLE, TC_SIMPLE_VECTOR, TC_SIMPLE_ARRAY, TC_COMPLEX, TC_UNSUPP = -1 }

enum	{ LOGICAL_CLASS = mxLOGICAL_CLASS, INT8_CLASS = mxINT8_CLASS, UINT8_CLASS = mxUINT8_CLASS, INT16_CLASS = mxINT16_CLASS, INT32_CLASS = mxINT32_CLASS, UINT16_CLASS = mxUINT16_CLASS, UINT32_CLASS = mxUINT32_CLASS, INT64_CLASS = mxINT64_CLASS, DOUBLE_CLASS = mxDOUBLE_CLASS, SINGLE_CLASS = mxSINGLE_CLASS, CHAR_CLASS = mxCHAR_CLASS }

Public Member Functions
	ValueMex ()
	Standard ctor.

	ValueMex (const ValueMex &other)
	Copy ctor for const objects.

	ValueMex (ValueMex &other)
	Move ctor for lvalues.

	ValueMex (ValueMex &&other)
	Move ctor for rvalues (temporary objects)

ValueMex &	operator= (const ValueMex &other)
	Assignment operator for const objects.

ValueMex &	operator= (ValueMex &other)
	Move assignment operator for lvalues.

ValueMex &	operator= (ValueMex &&other)
	Move assignment operator for rvalues (temporary objects)

	ValueMex (const mxArray *pcItem)
	Copy ctor for mxArrays. More...

	ValueMex (mwIndex m, mwIndex n, int clsid=mxDOUBLE_CLASS)
	Ctor allocating new MATLAB matrix object. More...

ValueMex &	Adopt (bool doAdopt=true)
	Take ownership (custody) of a MEX array. More...

void	Destroy ()
	Dtor. More...

const mxArray *	Item () const
	Returns hosted MATLAB array.

mxArray *	Item ()
	Returns hosted MATLAB array.

ValueMex	Duplicate () const
	Returns a duplictae of the hosted MATLAB array.

mxArray *	Detach ()
	Detach hosted MATLAB array.

size_t	GetM () const
	Returns row count (1st dimension)

size_t	GetN () const
	Returns col count (2nd dimension)

bool	IsEmpty () const
	Returns true if item is NULL or empty ([])

bool	IsCell () const
	Returns true if item is a cell array.

bool	IsComplex () const
	Returns true if item is not NULL and complex.

bool	IsScalar () const
	Returns true if item consists of exact 1 element.

bool	IsStruct () const
	Returns true if item is a struct array.

bool	IsVector () const
	Returns true if m_pcItem is of size 1xN or Mx1.

bool	IsDoubleClass () const
	Returns true if m_pcItem is of type mxDOUBLE_CLASS.

bool	IsFunctionHandle () const
	Returns true if m_pcItem is of type mxFUNCTION_CLASS.

size_t	NumElements () const
	Returns number of elements.

size_t	ByElement () const
	Returns size in bytes of one element.

int	NumDims () const
	Returns number of dimensions.

size_t	ByData () const
	Returns data size in bytes.

mxClassID	ClassID () const
	Returns item class ID or mxUNKNOWN_CLASS if item is NULL.

type_complexity_e	Complexity (bool bCanSerialize=false) const
	Get complexity information. Which storage level is necessary (scalar, vector, matrix, text, blob) More...

void *	Data () const
	Returns pointer to raw data.

char *	GetString (bool flagUTF=false, const char *format=NULL) const
	Convert a string to char, due flagUTF converted to utf8. More...

char *	GetEncString () const
	Returns allocated memory with items test, due to global flag converted to UTF. More...

int	GetInt (int errval=0) const
	Get integer value from item. More...

sqlite3_int64	GetInt64 (int errval=0) const
	Get 64 bit integer value from item. More...

double	GetScalar () const

const mxArray *	GetField (int n, const char *name) const
	Get field from a struct array. More...

void	SetCell (int i, const mxArray *cell)
	Sets a cell of a MATLAB cell array. More...

void	MakePersistent ()
	Make the MATLAB array persistent.

void	Throw ()
	Throws an exception if any occured.

void	Call (ValueMex lhs, ValueMex exception)
	Calling a MATLAB function (handle) with arguemnts. More...

Public Member Functions inherited from ValueBase
	~ValueBase ()
	Dtor.

Static Public Member Functions
static ValueMex	CreateCellMatrix (int m, int n)
	Create a cell array. More...

static ValueMex	CreateDoubleScalar (double value)
	Create a double scalar. More...

static ValueMex	CreateString (const char *str)
	Create a string. More...

Additional Inherited Members
Public Attributes inherited from ValueBase
bool	m_isConst
	if flagged as non-const, class may swap memory ownership (custody)

union {
double	m_float
	floating point representation

sqlite3_int64	m_integer
	integer representation

char *	m_text
	text representation or allocated memory ()

mxArray *	m_blob
	binary large object representation

mxArray *	m_pcItem
	MATLAB variable representation.

tagNativeArray *	m_array
	self allocated variable representation

long long	m_largest_field
	largest member used to copy entire union (dummy field)

};

Protected Member Functions inherited from ValueBase
	ValueBase ()
	Standard ctor.

	ValueBase (const ValueBase &other)
	Copy ctor for constant objects.

	ValueBase (ValueBase &other)
	Move ctor for lvalues.

	ValueBase (ValueBase &&other)
	Move ctor for rvalues (temporary objects)

ValueBase &	operator= (const ValueBase &other)
	Assignment operator.

ValueBase &	operator= (ValueBase &other)
	Move assignment operator for lvalues.

ValueBase &	operator= (ValueBase &&other)
	Move assignment operator for rvalues (temporary objects)

Detailed Description

Encapsulating a MATLAB mxArray.

Class ValueMex never takes custody of a MATLAB memory object!
Even though there is a function Destroy() which frees the MATLAB object, this class has no destructor which automatically does.

It's intended that this class allocates and tends memory space through other functions than mxCreate*() functions, since these are quite slow. (see tagNativeArray)

If a dtor is declared, we have to fulfil the "rule of three"

See also: Wikipedia

Definition at line 178 of file value.hpp.

Member Enumeration Documentation

◆ type_complexity_e

enum ValueMex::type_complexity_e

Complexity information about a MATLAB variable. For testing if a variable is able to be packed or not.

Enumerator
TC_EMPTY	Empty.
TC_SIMPLE	single non-complex value, char or simple string (SQLite simple types)
TC_SIMPLE_VECTOR	non-complex numeric vectors (SQLite BLOB)
TC_SIMPLE_ARRAY	multidimensional non-complex numeric or char arrays (SQLite typed BLOB)
TC_COMPLEX	structs, cells, complex data (SQLite typed ByteStream BLOB)
TC_UNSUPP	all other (unsuppored types)

Definition at line 185 of file value.hpp.

Constructor & Destructor Documentation

◆ ValueMex() [1/2]

ValueMex::ValueMex ( const mxArray * pcItem )

inlineexplicit

Copy ctor for mxArrays.

Parameters

[in] pcItem MATLAB array

Definition at line 256 of file value.hpp.

◆ ValueMex() [2/2]

ValueMex::ValueMex	(	mwIndex	m,
		mwIndex	n,
		int	clsid = `mxDOUBLE_CLASS`
	)

inline

Ctor allocating new MATLAB matrix object.

Parameters

[in]	m	Number of rows
[in]	n	Number of columns
[in]	clsid	Class ID of value type (refer MATLAB manual)

Definition at line 270 of file value.hpp.

Member Function Documentation

◆ Adopt()

ValueMex& ValueMex::Adopt ( bool doAdopt = true )

inline

Take ownership (custody) of a MEX array.

Parameters

doAdopt true to adopt, false to make it const

Definition at line 282 of file value.hpp.

Referenced by Call(), CreateCellMatrix(), CreateDoubleScalar(), CreateString(), and Duplicate().

Here is the caller graph for this function:

◆ Call()

void ValueMex::Call	(	ValueMex *	lhs,
		ValueMex *	exception
	)

inline

Calling a MATLAB function (handle) with arguemnts.

Parameters

lhs	Return value (only one)
exception	Exception container

Definition at line 812 of file value.hpp.

References Adopt().

◆ Complexity()

type_complexity_e ValueMex::Complexity ( bool bCanSerialize = false ) const

inline

Get complexity information. Which storage level is necessary (scalar, vector, matrix, text, blob)

Parameters

[in] bCanSerialize true if serialization of item is enabled

Returns: The item complexity (for storage issues)

Definition at line 531 of file value.hpp.

Referenced by blob_pack(), and createValueSQLFromItem().

Here is the caller graph for this function:

◆ CreateCellMatrix()

static ValueMex ValueMex::CreateCellMatrix	(	int	m,
		int	n
	)

inlinestatic

Create a cell array.

Parameters

m	Number of rows
n	Number of cols

Returns: Cell array

Definition at line 298 of file value.hpp.

References Adopt().

Referenced by MexFunctors::initGroupData(), and SQLiface::mexFcnWrapper().

Here is the caller graph for this function:

◆ CreateDoubleScalar()

static ValueMex ValueMex::CreateDoubleScalar ( double value )

inlinestatic

Create a double scalar.

Parameters

value Scalar value

Returns: Scalar value matrix

Definition at line 311 of file value.hpp.

References Adopt().

◆ CreateString()

static ValueMex ValueMex::CreateString ( const char * str )

inlinestatic

Create a string.

Parameters

str	String value

Returns: String as char array

Definition at line 324 of file value.hpp.

References Adopt().

◆ Destroy()

void ValueMex::Destroy ( )

inline

Dtor.

If this class has its custody, memory is freed.

Definition at line 335 of file value.hpp.

Referenced by MexFunctors::initGroupData(), and MexFunctors::~MexFunctors().

Here is the caller graph for this function:

◆ GetEncString()

char* ValueMex::GetEncString ( ) const

inline

Returns allocated memory with items test, due to global flag converted to UTF.

Returns: created string (allocator MEM_ALLOC)

Definition at line 665 of file value.hpp.

References g_convertUTF8.

◆ GetField()

const mxArray* ValueMex::GetField	(	int	n,
		const char *	name
	)		const

inline

Get field from a struct array.

Parameters

n	Index of the array
name	Name of the requested field

Returns: Handle to mxArray

Definition at line 738 of file value.hpp.

◆ GetInt()

int ValueMex::GetInt ( int errval = 0 ) const

inline

Get integer value from item.

Parameters

errval Value to return in case of non-convertible variable data type

Returns: Item value converted to integer type.

Definition at line 677 of file value.hpp.

Referenced by have_serialize().

Here is the caller graph for this function:

◆ GetInt64()

sqlite3_int64 ValueMex::GetInt64 ( int errval = 0 ) const

inline

Get 64 bit integer value from item.

Parameters

errval Value to return in case of non-convertible variable data type

Returns: Item value converted to integer type.

Definition at line 708 of file value.hpp.

◆ GetScalar()

double ValueMex::GetScalar ( ) const

inline

Returns: Scalar item value (double), or NaN if it's not a scalar

Definition at line 726 of file value.hpp.

◆ GetString()

char* ValueMex::GetString	(	bool	flagUTF = `false`,
		const char *	format = `NULL`
	)		const

inline

Convert a string to char, due flagUTF converted to utf8.

Parameters

[in]	flagUTF	if true, string will be converted to UTF8
[out]	format	optional format string (see fprintf())

Returns: created string (allocator MEM_ALLOC)

Definition at line 584 of file value.hpp.

References getLocaleMsg(), MEM_ALLOC, and utils_destroy_array().

◆ SetCell()

void ValueMex::SetCell	(	int	i,
		const mxArray *	cell
	)

inline

Sets a cell of a MATLAB cell array.

Parameters

i	Index
cell	Cell content

Definition at line 770 of file value.hpp.

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

value.hpp

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ type_complexity_e

Constructor & Destructor Documentation

◆ ValueMex() [1/2]

◆ ValueMex() [2/2]

Member Function Documentation

◆ Adopt()

◆ Call()

◆ Complexity()

◆ CreateCellMatrix()

◆ CreateDoubleScalar()

◆ CreateString()

◆ Destroy()

◆ GetEncString()

◆ GetField()

◆ GetInt()

◆ GetInt64()

◆ GetScalar()

◆ GetString()

◆ SetCell()