MEX utilities. More...

#include "mex.h"
#include <vl/generic.h>
#include <vl/array.h>
#include <vl/stringop.h>
#include <ctype.h>
#include <string.h>
#include <stdio.h>
#include <stdarg.h>

Include dependency graph for mexutils.h:

Go to the source code of this file.

Classes
struct	_vlmxOption
	MEX option. More...
Defines
#define	IN(x) (in[IN_ ## x])
	Access MEX input argument.
#define	MEXUTILS_RAISE_HELPER MEXUTILS_RAISE_HELPER_A MEXUTILS_RAISE_HELPER_B
#define	MEXUTILS_RAISE_HELPER_A
#define	MEXUTILS_RAISE_HELPER_B
#define	OUT(x) (out[OUT_ ## x])
	Access MEX output argument.
#define	VL_USE_MATLAB_ENV
	Setup VLFeat to be used in a MEX file.
Typedefs
typedef vl_int32	mwIndex
typedef vl_uint32	mwSize
typedef struct _vlmxOption	vlmxOption
	MEX option type.
Functions
static int	vlmxCompareStringsI (const char s1, const char s2)
	Case insensitive string comparison.
static int	vlmxCompareToStringI (mxArray const array, char const string)
	Case insensitive string comparison with array.
static mxArray *	vlmxCreateArrayFromVlArray (VlArray const *x)
	Create a MATLAB array from a VlArray.
static mxArray *	vlmxCreatePlainScalar (double x)
	Create a MATLAB array which is a plain scalar.
static VlEnumerator *	vlmxDecodeEnumeration (mxArray const name_array, VlEnumerator const enumeration, vl_bool caseInsensitive)
	Get an emumeration member by name.
static VlArray *	vlmxEnvelopeArrayInVlArray (VlArray v, mxArray x)
	Envelope a MATLAB array in a VlArray instance.
static int	vlmxIsEqualToStringI (mxArray const array, char const string)
	Case insensitive string equality test with array.
static int	vlmxNextOption (mxArray const args[], int nargs, vlmxOption const options, int next, mxArray const *optarg)
	Parse the next option.
Check for array attributes
VL_INLINE vl_bool	vlmxIsOfClass (mxArray const *array, mxClassID classId)
	Check if a MATLAB array is of a prescribed class.
VL_INLINE vl_bool	vlmxIsReal (mxArray const *array)
	Check if a MATLAB array is real.
Check for scalar, vector and matrix arrays
VL_INLINE vl_bool	vlmxIsScalar (mxArray const *array)
	Check if a MATLAB array is scalar.
static vl_bool	vlmxIsVector (mxArray const *array, vl_index numElements)
	Check if a MATLAB array is a vector.
static vl_bool	vlmxIsMatrix (mxArray const *array, vl_index M, vl_index N)
	Check if a MATLAB array is a matrix.
static vl_bool	vlmxIsArray (mxArray const array, vl_index numDimensions, vl_index dimensions)
	Check if the MATLAB array has the specified dimensions.
Check for plain arrays
VL_INLINE vl_bool	vlmxIsPlain (mxArray const *array)
	Check if a MATLAB array is plain.
VL_INLINE vl_bool	vlmxIsPlainScalar (mxArray const *array)
	Check if a MATLAB array is plain scalar.
VL_INLINE vl_bool	vlmxIsPlainVector (mxArray const *array, vl_index numElements)
	Check if a MATLAB array is a plain vector.
VL_INLINE vl_bool	vlmxIsPlainMatrix (mxArray const *array, vl_index M, vl_index N)
	Check if a MATLAB array is a plain matrix.
static int	vlmxIsString (const mxArray *array, vl_index length)
	Check if the array is a string.
Error handling
enum	_VlmxErrorId { vlmxErrAlloc = 1, vlmxErrInvalidArgument, vlmxErrNotEnoughInputArguments, vlmxErrTooManyInputArguments, vlmxErrNotEnoughOutputArguments, vlmxErrTooManyOutputArguments, vlmxErrInvalidOption, vlmxErrInconsistentData }
	VLFeat MEX errors. More...
typedef enum _VlmxErrorId	VlmxErrorId
	VLFeat MEX errors.
static void	vlmxError (VlmxErrorId errorId, char const *errorMessage,...)
	Raise a MEX error with VLFeat format.
static void	vlmxWarning (VlmxErrorId errorId, char const *errorMessage,...)
	Raise a MEX warning with VLFeat format.

Detailed Description

MEX utilities.

Author:: Andrea Vedaldi

This header file provides helper functions for writing MATLAB MEX files.

VLFeat environment

When the VLFeat DLL is linked to a MATLAB MEX files, at run time the MEX file must configure VLFeat to use MATLAB memory allocation and logging functions. This can be obtained by calling the macro VL_USE_MATLAB_ENV as the first line of each MEX file which is linked to the VLFeat DLL.

Array tests

MATLAB supports a variety of array types. Most MEX file arguments are restricted to a few types and must be properly checked at run time. mexutils.h provides some helper functions to make it simpler to check such arguments. MATLAB basic array types are:

Numeric array: mxDOUBLE_CLASS, mxSINGLE_CLASS, mxINT8_CLASS, mxUINT8_CLASS, mxINT16_CLASS, mxUINT16_CLASS, mxINT32_CLASS, mxUINT32_CLASS. Moreover:
- all such types have a real component
- all such types may have a imaginary component
- mxDOUBLE_LCASS arrays with two dimensions can be sparse.
Logical array (mxLOGICAL_CLASS).
Character array (mxCHAR_CLASS).

The other MATLAB array types are:

Struct array (mxSTRUCT_CLASS).
Cell array (mxCELL_CLASS).
Custom class array (mxCLASS_CLASS).
Unkown type array (mxUNKNOWN_CLASS).

VLFeat defines a number of common classes of arrays and corresponding tests.

Scalar array is a non-sparse array with exactly one element. Note that the array may have an arbitrary number of dimensions, and be of any numeric or other type. All dimensions are singleton (which is implied by having exactly one element). Use vlmxIsScalar to test if an array is scalar.

Vector array is a non-sparse array which is either empty (empty vector) or has at most one non-singleton dimension. The array can be of any numeric or other type. The elements of such a MATLAB array are stored as a plain C array with a number of elements equal to the number of elements in the array (obtained with mxGetNumberOfElements). Use vlmxIsVector to test whether an array is a vector.

Matrix array is a non-sparse array for which all dimensions beyond the first two are singleton, or a non-sparse array which is empty and for which at least one of the first two dimensions is zero. The array can be of any numeric or other type. The non-singleton dimensions can be zero (empty matrix), one, or more. The element of such a MATLAB array are stored as a C array in column major order and its dimensions can be obtained by mxGetM and mxGetN. Use vlmxIsMatrix to test if an array is a matrix.

Real array is a numeric array (as for mxIsNumeric) without a complex component. Use vlmxIsReal to check if an array is real.

Use vlmxIsOfClass to check if an array is of a prescribed (storage) class, such as mxDOUBLE_CLASS.

Plain scalar, vector, and matrix are a scalar, vector, and matrix arrays which are real and of class mxDOUBLE_CLASS. Use vlmxIsPlainScalar, vlmxIsPlainVector and vlmxIsPlainMatrix to check this.

Parsing options

It is common to pass optional arguments to a MEX file as option type-value pairs. Here type is a string identifying the option and value is a MATLAB array specifing its value. The function vlmxNextOption can be used to simplify parsing a list of such arguments (similar to UNIX getopt). The functions vlmxError and vlmxWarning are shortcuts to specify VLFeat formatted errors.

Definition in file mexutils.h.

Define Documentation

#define IN ( x ) (in[IN_ ## x])

Access MEX input argument.

Definition at line 39 of file mexutils.h.

#define MEXUTILS_RAISE_HELPER MEXUTILS_RAISE_HELPER_A MEXUTILS_RAISE_HELPER_B

Definition at line 240 of file mexutils.h.

#define MEXUTILS_RAISE_HELPER_A

Value:

char const * errorString ; \
  char formattedErrorId [512] ; \
  char formattedErrorMessage [1024] ; \
  \
  switch (errorId) { \
    case vlmxErrAlloc : errorString = "outOfMemory" ; break ; \
    case vlmxErrInvalidArgument : errorString = "invalidArgument" ; break ; \
    case vlmxErrNotEnoughInputArguments : errorString = "notEnoughInputArguments" ; break ; \
    case vlmxErrTooManyInputArguments : errorString = "tooManyInputArguments" ; break ; \
    case vlmxErrNotEnoughOutputArguments : errorString = "notEnoughOutputArguments" ; break ; \
    case vlmxErrTooManyOutputArguments : errorString = "tooManyOutputArguments" ; break ; \
    case vlmxErrInvalidOption : errorString = "invalidOption" ; break ; \
    case vlmxErrInconsistentData : errorString = "inconsistentData" ; break ; \
    default : errorString = "undefinedError" ; break ; \
  } \
  \
  if (! errorMessage) { \
    switch (errorId) { \
      case vlmxErrAlloc: errorMessage = "Out of memory." ; break ; \
      case vlmxErrInvalidArgument: errorMessage = "Invalid argument." ; break ; \
      case vlmxErrNotEnoughInputArguments: errorMessage = "Not enough input arguments." ; break ; \
      case vlmxErrTooManyInputArguments: errorMessage = "Too many input arguments." ; break ; \
      case vlmxErrNotEnoughOutputArguments: errorMessage = "Not enough output arguments." ; break ; \
      case vlmxErrTooManyOutputArguments: errorMessage = "Too many output arguments." ; break ; \
      case vlmxErrInconsistentData: errorMessage = "Inconsistent data." ; break ; \
      case vlmxErrInvalidOption: errorMessage = "Invalid option." ; break ; \
      default: errorMessage = "Undefined error message." ; \
    } \
  }

Definition at line 183 of file mexutils.h.

#define MEXUTILS_RAISE_HELPER_B

Value:

{ \
  va_list args ; \
  va_start(args, errorMessage) ; \
  snprintf(formattedErrorId, \
           sizeof(formattedErrorId)/sizeof(char), \
           "vl:%s", errorString) ; \
  vsnprintf(formattedErrorMessage, \
            sizeof(formattedErrorMessage)/sizeof(char), \
            errorMessage, args) ; \
  va_end(args) ; \
}

Definition at line 226 of file mexutils.h.

#define OUT ( x ) (out[OUT_ ## x])

Access MEX output argument.

Definition at line 43 of file mexutils.h.

#define VL_USE_MATLAB_ENV

Value:

vl_set_alloc_func (mxMalloc, mxRealloc, mxCalloc, mxFree) ; \
  vl_set_printf_func ((printf_func_t)mexPrintf) ;

Setup VLFeat to be used in a MEX file.

This makes VLFeat use MATLAB version of the memory allocation and logging functions.

Definition at line 76 of file mexutils.h.

Typedef Documentation

typedef vl_int32 mwIndex

Definition at line 34 of file mexutils.h.

typedef vl_uint32 mwSize

Definition at line 33 of file mexutils.h.

typedef enum _VlmxErrorId VlmxErrorId

VLFeat MEX errors.

typedef struct _vlmxOption vlmxOption

MEX option type.

Definition at line 734 of file mexutils.h.

Enumeration Type Documentation

enum _VlmxErrorId

VLFeat MEX errors.

Enumerator:

vlmxErrAlloc
vlmxErrInvalidArgument
vlmxErrNotEnoughInputArguments
vlmxErrTooManyInputArguments
vlmxErrNotEnoughOutputArguments
vlmxErrTooManyOutputArguments
vlmxErrInvalidOption
vlmxErrInconsistentData

Definition at line 247 of file mexutils.h.

Function Documentation

static int vlmxCompareStringsI	(	const char *	s1,
		const char *	s2
	)		`[static]`

Case insensitive string comparison.

------------------------------------------------------------------

Parameters:

s1	first string.
s2	second string.

Returns:: comparison result.

The comparison result is equal to 0 if the strings are equal, >0 if the first string is greater than the second (in lexicographical order), and <0 otherwise.

Definition at line 660 of file mexutils.h.

static int vlmxCompareToStringI	(	mxArray const *	array,
		char const *	string
	)		`[static]`

Case insensitive string comparison with array.

------------------------------------------------------------------

Parameters:

array	first string (as a MATLAB array).
string	second string.

Returns:: comparison result.

The comparison result is equal to 0 if the strings are equal, >0 if the first string is greater than the second (in lexicographical order), and <0 otherwise.

Definition at line 687 of file mexutils.h.

static mxArray* vlmxCreateArrayFromVlArray ( VlArray const * x ) [static]

Create a MATLAB array from a VlArray.

------------------------------------------------------------------

Parameters:

x	VlArray instance.

Returns:: the new array.

Definition at line 567 of file mexutils.h.

static mxArray* vlmxCreatePlainScalar ( double x ) [static]

Create a MATLAB array which is a plain scalar.

------------------------------------------------------------------

Parameters:

x	scalar value.

Returns:: the new array.

Definition at line 553 of file mexutils.h.

static VlEnumerator* vlmxDecodeEnumeration	(	mxArray const *	name_array,
		VlEnumerator const *	enumeration,
		vl_bool	caseInsensitive
	)		`[static]`

Get an emumeration member by name.

Parameters:

enumeration	the enumeration to decode.
name_array	member name as a MATLAB string array.
caseInsensitive	if `true` match the string case-insensitive.

Returns:: the corresponding enumeration member, or NULL if any.

Definition at line 832 of file mexutils.h.

static VlArray* vlmxEnvelopeArrayInVlArray	(	VlArray *	v,
		mxArray *	x
	)		`[static]`

Envelope a MATLAB array in a VlArray instance.

------------------------------------------------------------------

Parameters:

v	VlArray instance (out)
x	MATALB array.

Returns:: v.

Definition at line 617 of file mexutils.h.

static void vlmxError	(	VlmxErrorId	errorId,
		char const *	errorMessage,
			...
	)		`[static]`

Raise a MEX error with VLFeat format.

Parameters:

errorId	error ID string.
errorMessage	error message C-style format string.
...	format string arguments.

The function internally calls mxErrMsgTxtAndId, which causes the MEX file to abort.

Definition at line 273 of file mexutils.h.

static vl_bool vlmxIsArray	(	mxArray const *	array,
		vl_index	numDimensions,
		vl_index *	dimensions
	)		`[static]`

Check if the MATLAB array has the specified dimensions.

------------------------------------------------------------------

Parameters:

array	array to check.
numDimensions	number of dimensions.
dimensions	dimensions.

Returns:: true the test succeeds.

The test is true if numDimensions < 0. If not, it is false if the array has not numDimensions. Otherwise it is true is dimensions is NULL or if each entry of dimensions is either negative or equal to the corresponding array dimension.

Definition at line 434 of file mexutils.h.

static int vlmxIsEqualToStringI	(	mxArray const *	array,
		char const *	string
	)		`[static]`

Case insensitive string equality test with array.

------------------------------------------------------------------

Parameters:

array	first string (as a MATLAB array).
string	second string.

Returns:: true if the strings are equal.

Definition at line 714 of file mexutils.h.

static vl_bool vlmxIsMatrix	(	mxArray const *	array,
		vl_index	M,
		vl_index	N
	)		`[static]`

Check if a MATLAB array is a matrix.

------------------------------------------------------------------

Parameters:

array	MATLAB array.
M	number of rows (negative for any).
N	number of columns (negative for any).

Returns:: VL_TRUE if the array is a matrix of the prescribed size.

See also:: Array tests

Definition at line 390 of file mexutils.h.

VL_INLINE vl_bool vlmxIsOfClass	(	mxArray const *	array,
		mxClassID	classId
	)

Check if a MATLAB array is of a prescribed class.

------------------------------------------------------------------

Parameters:

array	MATLAB array.
classId	prescribed class of the array.

Returns:: VL_TRUE if the class is of the array is of the prescribed class.

See also:: Array tests

Definition at line 308 of file mexutils.h.

VL_INLINE vl_bool vlmxIsPlain ( mxArray const * array )

Check if a MATLAB array is plain.

------------------------------------------------------------------

Parameters:

array MATLAB array.

Returns:: VL_TRUE if the array is plain.

See also:: Array tests

Definition at line 467 of file mexutils.h.

VL_INLINE vl_bool vlmxIsPlainMatrix	(	mxArray const *	array,
		vl_index	M,
		vl_index	N
	)

Check if a MATLAB array is a plain matrix.

------------------------------------------------------------------

Parameters:

array	MATLAB array.
M	number of rows (negative for any).
N	number of columns (negative for any).

Returns:: VL_TRUE if the array is a plain matrix of the prescribed size.

See also:: Array tests

Definition at line 513 of file mexutils.h.

VL_INLINE vl_bool vlmxIsPlainScalar ( mxArray const * array )

Check if a MATLAB array is plain scalar.

------------------------------------------------------------------

Parameters:

array MATLAB array.

Returns:: VL_TRUE if the array is plain scalar.

See also:: Array tests

Definition at line 483 of file mexutils.h.

VL_INLINE vl_bool vlmxIsPlainVector	(	mxArray const *	array,
		vl_index	numElements
	)

Check if a MATLAB array is a plain vector.

------------------------------------------------------------------

Parameters:

array	MATLAB array.
numElements	number of elements (negative for any).

Returns:: VL_TRUE if the array is a plain vecotr of the prescribed size.

See also:: Array tests

Definition at line 497 of file mexutils.h.

VL_INLINE vl_bool vlmxIsReal ( mxArray const * array )

Check if a MATLAB array is real.

------------------------------------------------------------------

Parameters:

array MATLAB array.

Returns:: VL_TRUE if the array is real.

See also:: Array tests

Definition at line 321 of file mexutils.h.

VL_INLINE vl_bool vlmxIsScalar ( mxArray const * array )

Check if a MATLAB array is scalar.

------------------------------------------------------------------

Parameters:

array MATLAB array.

Returns:: VL_TRUE if the array is scalar.

See also:: Array tests

Definition at line 339 of file mexutils.h.

static int vlmxIsString	(	const mxArray *	array,
		vl_index	length
	)		`[static]`

Check if the array is a string.

------------------------------------------------------------------

Parameters:

array	array to test.
length	string length.

Returns:: true if the array is a string of the specified length

The array array satisfies the test if:

its storage class is CHAR;
it has two dimensions but only one row;
length < 0 or the array has length columns.

Definition at line 531 of file mexutils.h.

static vl_bool vlmxIsVector	(	mxArray const *	array,
		vl_index	numElements
	)		`[static]`

Check if a MATLAB array is a vector.

------------------------------------------------------------------

Parameters:

array	MATLAB array.
numElements	number of elements (negative for any).

Returns:: VL_TRUE if the array is a vecotr of the prescribed size.

See also:: Array tests

Definition at line 353 of file mexutils.h.

static int vlmxNextOption	(	mxArray const *	args[],
		int	nargs,
		vlmxOption const *	options,
		int *	next,
		mxArray const **	optarg
	)		`[static]`

Parse the next option.

------------------------------------------------------------------

Parameters:

args	MEX argument array.
nargs	MEX argument array length.
options	List of option definitions.
next	Pointer to the next option (input and output).
optarg	Pointer to the option optional argument (output).

Returns:: the code of the next option, or -1 if there are no more options.

The function parses the array args for options. args is expected to be a sequence alternating option names and option values, in the form of nargs instances of mxArray. The function then scans the option starting at position next in the array. The option name is matched (case insensitive) to the table of options options, a pointer to the option value is stored in optarg, next is advanced to the next option, and the option code is returned.

The function is typically used in a loop to parse all the available options. next is initialized to zero, and then the function is called until the special code -1 is returned.

If the option name cannot be matched to the available options, either because the option name is not a string array or because the name is unknown, the function exits the MEX file with an error.

Definition at line 765 of file mexutils.h.

static void vlmxWarning	(	VlmxErrorId	errorId,
		char const *	errorMessage,
			...
	)		`[static]`

Raise a MEX warning with VLFeat format.

Parameters:

errorId	error ID string.
errorMessage	error message C-style format string.
...	format string arguments.

The function internally calls mxWarnMsgTxtAndId.

Definition at line 288 of file mexutils.h.

Classes

Defines

Typedefs

Functions

Error handling

Detailed Description

VLFeat environment

Array tests

Parsing options

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation