Utilities for interfacing C++ with MATLAB using the MEX API. More...

Classes
class	Utils::mex_class_handle< base >
	A class template that manages a C++ object for use with MATLAB. More...

Functions
void	Utils::mex_error_message (string_view msg)
	Sends an error message to MATLAB.

bool	Utils::mex_is_scalar (mxArray const *arg, string_view msg)
	Checks if the input argument is a scalar.

double	Utils::mex_get_scalar_value (mxArray const *arg, string_view msg)
	Gets the scalar value from the input argument.

bool	Utils::mex_get_bool (mxArray const *arg, string_view msg)
	Gets a boolean value from the input argument.

int64_t	Utils::mex_get_int64 (mxArray const *arg, string_view msg)
	Gets a 64-bit integer value from the input argument.

double const *	Utils::mex_vector_pointer (mxArray const *arg, mwSize &sz, string_view msg)
	Gets a pointer to a vector from the input argument.

double const *	Utils::mex_matrix_pointer (mxArray const *arg, mwSize &nr, mwSize &nc, string_view msg)
	Gets a pointer to a matrix from the input argument.

void	Utils::mex_set_scalar_value (mxArray *&arg, double value)
	Sets a scalar value in the output argument.

void	Utils::mex_set_scalar_int32 (mxArray *&arg, int32_t value)
	Sets a scalar integer value in the output argument.

void	Utils::mex_set_scalar_int64 (mxArray *&arg, int64_t value)
	Sets a scalar 64-bit integer value in the output argument.

void	Utils::mex_set_scalar_bool (mxArray *&arg, bool value)
	Sets a boolean value in the output argument.

int32_t *	Utils::mex_create_matrix_int32 (mxArray *&arg, mwSize nrow, mwSize ncol)
	Creates a numeric matrix of type int32 and returns a pointer to its data.

int64_t *	Utils::mex_create_matrix_int64 (mxArray *&arg, mwSize nrow, mwSize ncol)
	Creates a numeric matrix of type int64 and returns a pointer to its data.

double *	Utils::mex_create_matrix_value (mxArray *&arg, mwSize nrow, mwSize ncol)
	Creates a numeric matrix of type double and returns a pointer to its data.

template<typename R, typename I>
int	Utils::mex_create_sparse_matrix (size_t nnz, size_t nrows, size_t ncols, I i_rows[], I j_cols[], R vals[], mxArray *arg_out[])
	Creates a sparse matrix in MATLAB format.

void	Utils::mex_create_string_cell_array (mxArray *&arg, vector< string > const &str_vec)
	Creates a MATLAB cell array and fills it with a vector of C++ strings.

template<typename base>
mxArray *	Utils::mex_convert_ptr_to_mx (base *ptr)
	Converts a pointer to a mex_class_handle into a MATLAB mxArray.

template<typename base>
mex_class_handle< base > *	Utils::mex_convert_mx_to_handle_ptr (mxArray const *in)
	Converts a MATLAB mxArray back to a mex_class_handle pointer.

template<typename base>
base *	Utils::mex_convert_mx_to_ptr (mxArray const *in)
	Converts a MATLAB mxArray to a pointer of the wrapped C++ object.

template<typename base>
void	Utils::mex_destroy_object (mxArray const *&in)
	Destroys the object wrapped by the mex_class_handle.

Detailed Description

Utilities for interfacing C++ with MATLAB using the MEX API.

This module provides functions and utilities for seamless integration between C++ code and MATLAB via the MEX (MATLAB Executable) API. It enables the creation, management, and conversion of MATLAB data types to and from C++ structures, allowing developers to leverage C++ performance within MATLAB environments.

Function Documentation

◆ mex_convert_mx_to_handle_ptr()

template<typename base>

mex_class_handle< base > * Utils::mex_convert_mx_to_handle_ptr ( mxArray const * in )

inline

Converts a MATLAB mxArray back to a mex_class_handle pointer.

This function retrieves the handle from a MATLAB mxArray, checking that it is a valid uint64 scalar.

Template Parameters

base	The type of the C++ class being wrapped.

Parameters

in	The mxArray containing the handle.

Returns: Pointer to the mex_class_handle.

Exceptions

std::runtime_error if the input is not a valid uint64 scalar.

◆ mex_convert_mx_to_ptr()

template<typename base>

base * Utils::mex_convert_mx_to_ptr ( mxArray const * in )

inline

Converts a MATLAB mxArray to a pointer of the wrapped C++ object.

This function first converts the mxArray to a mex_class_handle pointer and then retrieves the managed C++ object pointer.

Template Parameters

base	The type of the C++ class being wrapped.

Parameters

in	The mxArray containing the handle.

Returns: Pointer to the managed C++ object.

◆ mex_convert_ptr_to_mx()

template<typename base>

mxArray * Utils::mex_convert_ptr_to_mx ( base * ptr )

inline

Converts a pointer to a mex_class_handle into a MATLAB mxArray.

This function locks the MATLAB environment and creates a MATLAB numeric array that holds a pointer to a new mex_class_handle.

Template Parameters

base	The type of the C++ class being wrapped.

Parameters

ptr	Pointer to the C++ object to be wrapped.

Returns: A pointer to a MATLAB mxArray containing the handle.

◆ mex_create_matrix_int32()

int32_t * Utils::mex_create_matrix_int32	(	mxArray *&	arg,
		mwSize	nrow,
		mwSize	ncol )

inline

Creates a numeric matrix of type int32 and returns a pointer to its data.

This function allocates memory for a matrix of specified size (nrow x ncol) and initializes it as an int32 numeric matrix. The created matrix is assigned to the output argument arg, and a pointer to the data is returned.

Parameters

arg	Reference to the mxArray pointer that will hold the created matrix.
nrow	Number of rows in the matrix.
ncol	Number of columns in the matrix.

Returns: Pointer to the data of the created int32 matrix.

◆ mex_create_matrix_int64()

int64_t * Utils::mex_create_matrix_int64	(	mxArray *&	arg,
		mwSize	nrow,
		mwSize	ncol )

inline

Creates a numeric matrix of type int64 and returns a pointer to its data.

This function allocates memory for a matrix of specified size (nrow x ncol) and initializes it as an int64 numeric matrix. The created matrix is assigned to the output argument arg, and a pointer to the data is returned.

Parameters

arg	Reference to the mxArray pointer that will hold the created matrix.
nrow	Number of rows in the matrix.
ncol	Number of columns in the matrix.

Returns: Pointer to the data of the created int64 matrix.

◆ mex_create_matrix_value()

double * Utils::mex_create_matrix_value	(	mxArray *&	arg,
		mwSize	nrow,
		mwSize	ncol )

inline

Creates a numeric matrix of type double and returns a pointer to its data.

This function allocates memory for a matrix of specified size (nrow x ncol) and initializes it as a double numeric matrix. The created matrix is assigned to the output argument arg, and a pointer to the data is returned.

Parameters

arg	Reference to the mxArray pointer that will hold the created matrix.
nrow	Number of rows in the matrix.
ncol	Number of columns in the matrix.

Returns: Pointer to the data of the created double matrix.

◆ mex_create_sparse_matrix()

template<typename R, typename I>

int Utils::mex_create_sparse_matrix	(	size_t	nnz,
		size_t	nrows,
		size_t	ncols,
		I	i_rows[],
		I	j_cols[],
		R	vals[],
		mxArray *	arg_out[] )

inline

Creates a sparse matrix in MATLAB format.

This function creates a sparse matrix using MATLAB's internal data structures. The inputs are arrays representing the row indices, column indices, and values of the non-zero elements of the sparse matrix.

Template Parameters

R	Type of the values in the sparse matrix.
I	Type of the row and column indices.

Parameters

nnz	Number of non-zero elements in the sparse matrix.
nrows	Number of rows in the sparse matrix.
ncols	Number of columns in the sparse matrix.
i_rows	Array of row indices (0-based).
j_cols	Array of column indices (0-based).
vals	Array of non-zero values.

Returns: int Status code of the MATLAB function call.

◆ mex_create_string_cell_array()

void Utils::mex_create_string_cell_array	(	mxArray *&	arg,
		vector< string > const &	str_vec )

inline

Creates a MATLAB cell array and fills it with a vector of C++ strings.

Parameters

arg	Reference to the mxArray pointer that will hold the MATLAB cell array.
str_vec	Vector of C++ strings to be inserted into the cell array.

◆ mex_destroy_object()

template<typename base>

void Utils::mex_destroy_object ( mxArray const *& in )

inline

Destroys the object wrapped by the mex_class_handle.

This function deletes the handle and its managed object and sets the mxArray reference to nullptr.

Template Parameters

base	The type of the C++ class being wrapped.

Parameters

in	Reference to the mxArray containing the handle.

◆ mex_error_message()

void Utils::mex_error_message ( string_view msg )

inline

Sends an error message to MATLAB.

Parameters

msg	The error message to display.

◆ mex_get_bool()

bool Utils::mex_get_bool	(	mxArray const *	arg,
		string_view	msg )

inline

Gets a boolean value from the input argument.

Parameters

arg	The mxArray input argument.
msg	The error message to display if not a logical scalar.

Returns: The boolean value.

◆ mex_get_int64()

int64_t Utils::mex_get_int64	(	mxArray const *	arg,
		string_view	msg )

inline

Gets a 64-bit integer value from the input argument.

Parameters

arg	The mxArray input argument.
msg	The error message to display if not a valid scalar.

Returns: The 64-bit integer value.

◆ mex_get_scalar_value()

double Utils::mex_get_scalar_value	(	mxArray const *	arg,
		string_view	msg )

inline

Gets the scalar value from the input argument.

Parameters

arg	The mxArray input argument.
msg	The error message to display if not scalar.

Returns: The scalar value.

◆ mex_is_scalar()

bool Utils::mex_is_scalar	(	mxArray const *	arg,
		string_view	msg )

inline

Checks if the input argument is a scalar.

Parameters

arg	The mxArray input argument.
msg	The error message to display if not scalar.

Returns: True if arg is a scalar, false otherwise.

◆ mex_matrix_pointer()

double const * Utils::mex_matrix_pointer	(	mxArray const *	arg,
		mwSize &	nr,
		mwSize &	nc,
		string_view	msg )

inline

Gets a pointer to a matrix from the input argument.

Parameters

arg	The mxArray input argument.
nr	The number of rows (output).
nc	The number of columns (output).
msg	The error message to display if not a valid matrix.

Returns: Pointer to the matrix data.

◆ mex_set_scalar_bool()

void Utils::mex_set_scalar_bool	(	mxArray *&	arg,
		bool	value )

inline

Sets a boolean value in the output argument.

Parameters

arg	Reference to the mxArray output argument.
value	The boolean value to set.

◆ mex_set_scalar_int32()

void Utils::mex_set_scalar_int32	(	mxArray *&	arg,
		int32_t	value )

inline

Sets a scalar integer value in the output argument.

Parameters

arg	Reference to the mxArray output argument.
value	The integer value to set.

◆ mex_set_scalar_int64()

void Utils::mex_set_scalar_int64	(	mxArray *&	arg,
		int64_t	value )

inline

Sets a scalar 64-bit integer value in the output argument.

Parameters

arg	Reference to the mxArray output argument.
value	The 64-bit integer value to set.

◆ mex_set_scalar_value()

void Utils::mex_set_scalar_value	(	mxArray *&	arg,
		double	value )

inline

Sets a scalar value in the output argument.

Parameters

arg	Reference to the mxArray output argument.
value	The scalar value to set.

◆ mex_vector_pointer()

double const * Utils::mex_vector_pointer	(	mxArray const *	arg,
		mwSize &	sz,
		string_view	msg )

inline

Gets a pointer to a vector from the input argument.

Parameters

arg	The mxArray input argument.
sz	The size of the vector (output).
msg	The error message to display if not a valid vector.

Returns: Pointer to the vector data.

Classes

Functions

Detailed Description

Function Documentation

◆ mex_convert_mx_to_handle_ptr()

◆ mex_convert_mx_to_ptr()

◆ mex_convert_ptr_to_mx()

◆ mex_create_matrix_int32()

◆ mex_create_matrix_int64()

◆ mex_create_matrix_value()

◆ mex_create_sparse_matrix()

◆ mex_create_string_cell_array()

◆ mex_destroy_object()

◆ mex_error_message()

◆ mex_get_bool()

◆ mex_get_int64()

◆ mex_get_scalar_value()

◆ mex_is_scalar()

◆ mex_matrix_pointer()

◆ mex_set_scalar_bool()

◆ mex_set_scalar_int32()

◆ mex_set_scalar_int64()

◆ mex_set_scalar_value()

◆ mex_vector_pointer()