External Interfaces

Primitive Types

All standard scalar C data types are supported by the shared library interface. These are shown in the two tables below along with their equivalent MATLAB types. MATLAB uses the type from the right column for arguments having the C type shown in the left column.

(The second table shows extended MATLAB types in the right column. These are instances of the MATLAB lib.pointer class rather than standard MATLAB data types. See Creating References for information on the lib.pointer class.)

C Type (on a 32-bit computer)	Equivalent MATLAB Type
char, byte	int8
unsigned char, byte	uint8
short	int16
unsigned short	uint16
int, long	int32
unsigned int, unsigned long	uint32
float	single
double	double
char *	string (1xn char array)

C Type (on a 32-bit computer)	Extended MATLAB Type
integer pointer types (int *)	(u)int(size)Ptr
float *	singlePtr
double *	doublePtr
mxArray *	MATLAB array
void *	voidPtr
type **	Same as typePtr with an added Ptr (e.g., double ** is doublePtrPtr)

Converting to Other Primitive Types

For primitive types, MATLAB automatically converts any argument to the data type expected by the external function. This means that you can pass a double to a function that expects to receive a byte (8-bit integer) and MATLAB does the conversion for you.

For example, the C function shown here takes arguments that are of types short, int, and double:

• double addMixedTypes(short x, int y, double z)
  {
     return (x + y + z);
  }
  

You can simply pass all of the arguments as type double from MATLAB. MATLAB determines what type of data is expected for each argument and performs the appropriate conversions:

• calllib('shrlibsample', 'addMixedTypes', 127, 33000, pi)
  ans =
    3.3130e+004
  

Converting to a Reference

MATLAB also automatically converts an argument passed by value into an argument passed by reference when the external function prototype defines the argument as a reference. So a MATLAB double argument passed to a function that expects double * is converted to a double reference by MATLAB.

addDoubleRef is a C function that takes an argument of type double *:

• double addDoubleRef(double x, double *y, double z)
  {
      return (x + *y + z);
  }
  

Call the function with three arguments of type double, and MATLAB handles the conversion:

• calllib('shrlibsample', 'addDoubleRef', 1.78, 5.42, 13.3)
  ans =
     20.5000
  

Strings

For arguments that require char *, you can pass a MATLAB string (i.e., character array).

This C function takes a char * input argument:

• char* stringToUpper(char *input) {
     char *p = input;
  
     if (p != NULL)
        while (*p!=0)
           *p++ = toupper(*p);
     return input;
  }
  

libfunctions shows that you can use a MATLAB string for this input.

• libfunctions shrlibsample -full
     [string, string] stringToUpper(string)
  

Create a MATLAB character array, str, and pass it as the input argument:

• str = 'This was a Mixed Case string';
  calllib('shrlibsample', 'stringToUpper', str)
  ans =
     THIS WAS A MIXED CASE STRING
  

Note    Although the input argument that MATLAB passes to stringToUpper resembles a reference to type char, it is not a true reference data type. That is, it does not contain the address of the MATLAB character array, str. So, when the function executes, it returns the correct result but does not modify the value in str. If you now examine str, you find that its original value is unchanged: str str = This was a Mixed Case string

Data Conversion

Enumerated Types

© 1994-2005 The MathWorks, Inc.