MATLAB Function Reference: mxArray Manipulation Functions, Exams of English Language

Download MATLAB Function Reference: mxArray Manipulation Functions and more Exams English Language in PDF only on Docsity! External Interfaces Reference Version 7 MATLAB® The Language of Technical Computing How to Contact The MathWorks: www.mathworks.com Web comp.soft-sys.matlab Newsgroup support@mathworks.com Technical support suggest@mathworks.com Product enhancement suggestions bugs@mathworks.com Bug reports doc@mathworks.com Documentation error reports service@mathworks.com Order status, license renewals, passcodes info@mathworks.com Sales, pricing, and general information 508-647-7000 Phone 508-647-7001 Fax The MathWorks, Inc. Mail 3 Apple Hill Drive Natick, MA 01760-2098 For contact information about worldwide offices, see the MathWorks Web site. MATLAB External Interfaces Reference  COPYRIGHT 1984 - 2004 by The MathWorks, Inc. The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or repro- duced in any form without prior written consent from The MathWorks, Inc. FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through the federal government of the United States. By accepting delivery of the Program or Documentation, the government hereby agrees that this software or documentation qualifies as commercial computer software or commercial computer software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern the use, modification, reproduction, release, performance, display, and disclosure of the Program and Documentation by the federal government (or other entity acquiring for or through the federal government) and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the government's needs or is inconsistent in any respect with federal procurement law, the government agrees to return the Program and Documentation, unused, to The MathWorks, Inc. MATLAB, Simulink, Stateflow, Handle Graphics, and Real-Time Workshop are registered trademarks, and TargetBox is a trademark of The MathWorks, Inc. Other product or brand names are trademarks or registered trademarks of their respective holders. Printing History: December 1996 First printing May 1997 Online only Revised for 5.1 (Release 9) January 1998 Online only Revised for 5.2 (Release 10) January 1999 Online only Revised for 5.3 (Release 11) September 2000 Online only Revised for 6.0 (Release 12) June 2001 Online only Revised for 6.1 (Release 12.1) July 2002 Online only Revised for MATLAB 6.5 (Release 13) January 2003 Online only Revised for MATLAB 6.5.1 (Release 13 SP1) June 2004 Online only Revised for MATLAB 7.0 (Release 14) 1 Generic DLL Interface Functions calllib Call function in external library libfunctions Return information on functions in external library libfunctionsview Create window displaying information on functions in external library libisloaded Determine if external library is loaded libpointer Create pointer object for use with external libraries libstruct Construct a structure as defined in an external library loadlibrary Load an external library into MATLAB® unloadlibrary Unload an external library from memory calllib 1-2 1calllibPurpose Call function in external library Syntax [x1, ..., xN] = calllib('libname', 'funcname', arg1, ..., argN) Description [x1, ..., xN] = calllib('libname', 'funcname', arg1, ..., argN) calls the function funcname in library libname, passing input arguments arg1 through argN. calllib returns output values obtained from function funcname in x1 through XN. If you used an alias when initially loading the library, then you must use that alias for the libname argument. Examples This example calls functions from the libmx library to test the value stored in y: hfile = [matlabroot '\extern\include\matrix.h']; loadlibrary('libmx', hfile) y = rand(4, 7, 2); calllib('libmx', 'mxGetNumberOfElements', y) ans = 56 calllib('libmx', 'mxGetClassID', y) ans = mxDOUBLE_CLASS unloadlibrary libmx See Also loadlibrary, libfunctions, libfunctionsview, libpointer, libstruct, libisloaded, unloadlibrary libfunctions 1-3 1libfunctionsPurpose Return information on functions in external library Syntax m = libfunctions('libname') m = libfunctions('libname', '-full') libfunctions libname -full Description m = libfunctions('libname') returns the names of all functions defined in the external shared library, libname, that has been loaded into MATLAB with the loadlibrary function. The return value, m, is a cell array of strings. If you used an alias when initially loading the library, then you must use that alias for the libname argument. m = libfunctions('libname', '-full') returns a full description of the functions in the library, including function signatures. This includes duplicate function names with different signatures. The return value, m, is a cell array of strings. libfunctions libname -full is the command format for this function. Examples List the functions in the MATLAB libmx library: hfile = [matlabroot '\extern\include\matrix.h']; loadlibrary('libmx', hfile) libfunctions libmx Methods for class lib.libmx: mxAddField mxGetFieldNumber mxIsLogicalScalarTrue mxArrayToString mxGetImagData mxIsNaN mxCalcSingleSubscript mxGetInf mxIsNumeric mxCalloc mxGetIr mxIsObject mxClearScalarDoubleFlag mxGetJc mxIsOpaque mxCreateCellArray mxGetLogicals mxIsScalarDoubleFlagSet . . . . . . libfunctionsview 1-6 Examples The following command opens the window shown below for the libmx library: libfunctionsview libmx See Also loadlibrary, libfunctions, libpointer, libstruct, calllib, libisloaded, unloadlibrary libisloaded 1-7 1libisloadedPurpose Determine if external library is loaded Syntax libisloaded('libname') libisloaded libname Description libisloaded('libname') returns true if the shared library libname is loaded and false otherwise. libisloaded libname is the command format for this function. If you used an alias when initially loading the library, then you must use that alias for the libname argument. Examples Example 1 Load the shrlibsample library and check to see if the load was successful before calling one of its functions: addpath([matlabroot '\extern\examples\shrlib']) loadlibrary shrlibsample.dll shrlibsample.h if libisloaded('shrlibsample') x = calllib('shrlibsample', 'addDoubleRef', 1.78, 5.42, 13.3) end Since the library is successfully loaded, the call to addDoubleRef works as expected and returns x = 20.5000 unloadlibrary shrlibsample Example 2 Load the same library, this time giving it an alias. If you use libisloaded with the library name, shrlibsample, it now returns false. Since you loaded the library using an alias, all further references to the library must also use that alias: addpath([matlabroot '\extern\examples\shrlib']) loadlibrary shrlibsample.dll shrlibsample.h alias lib libisloaded 1-8 libisloaded shrlibsample ans = 0 libisloaded lib ans = 1 unloadlibrary lib See Also loadlibrary, libfunctions, libfunctionsview, libpointer, libstruct, calllib, unloadlibrary libstruct 1-11 1libstructPurpose Construct a structure as defined in an external library Syntax s = libstruct('structtype') s = libstruct('structtype', mlstruct) Description s = libstruct('type') returns a libstruct object s that is a MATLAB object designed to resemble a C structure of type structtype. The structure type, structtype, is defined in an external library that must be loaded into MATLAB using the loadlibrary function. All fields of s are set to zero. s = libstruct('structtype', mlstruct) returns a libstruct object s with its fields initialized from MATLAB structure, mlstruct. The libstruct function essentially creates a C-like structure that you can pass to functions in an external library. You can handle this structure in MATLAB as you would a true MATLAB structure. Examples This example performs a simple addition of the fields of a structure. The function addStructFields is defined in the MATLAB sample shared library, shrlibsample. Here is the C function: double addStructFields(struct c_struct st) { double t = st.p1 + st.p2 + st.p3; return t; } Start by loading the shrlibsample library and creating MATLAB structure, sm: addpath([matlabroot '\extern\examples\shrlib']) loadlibrary shrlibsample.dll shrlibsample.h sm.p1 = 476; sm.p2 = -299; sm.p3 = 1000; libstruct 1-12 Construct a libstruct object sc that uses the c_struct template: sc = libstruct('c_struct', sm); get(sc) p1: 476 p2: -299 p3: 1000 Now call the function, passing the libstruct object, sc: calllib('shrlibsample', 'addStructFields', sc) ans = 1177 unloadlibrary shrlibsample Note In most cases, you can pass a MATLAB structure and MATLAB will automatically convert the argument to a C structure. See “Structures”, in the MATLAB documentation for more information. See Also loadlibrary, libfunctions, libfunctionsview, libpointer, calllib, libisloaded, unloadlibrary loadlibrary 1-13 1loadlibraryPurpose Load an external library into MATLAB Syntax loadlibrary('shrlib', 'hfile') loadlibrary('shrlib', @protofile) loadlibrary('shrlib', ..., 'options') loadlibrary shrlib hfile options Description loadlibrary('shrlib', 'hfile') loads the functions defined in header file hfile and found in shared library shrlib into MATLAB. On Windows systems, shrlib refers to the name of a dynamic link library (.dll) file. On UNIX systems, it refers to the name of a shared object (.so) file. loadlibrary('shrlib', @protofile) uses the prototype M-file protofile in place of a header file in loading the library shrlib. The string @protofile specifies a function handle to the prototype M-file. (See the description of “Prototype M-Files” below). If you do not include a file extension with the shrlib argument, loadlibrary uses .dll or .so, depending on the platform you are using. If you do not include a file extension with the second argument, and this argument is not a function handle, loadlibrary uses .h for the extension. loadlibrary 1-16 Example 2 Load sample library shrlibsample, giving it an alias name of lib. Once you have set an alias, you need to use this name in all further interactions with the library for this session: addpath([matlabroot '\extern\examples\shrlib']) loadlibrary shrlibsample shrlibsample.h alias lib libfunctionsview lib str = 'This was a Mixed Case string'; calllib('lib', 'stringToUpper', str) ans = THIS WAS A MIXED CASE STRING unloadlibrary lib Example 3 Load the library, specifying an additional path in which to search for included header files: addpath([matlabroot '\extern\examples\shrlib']) loadlibrary('shrlibsample','shrlibsample.h','includepath', ... fullfile(matlabroot , 'extern', 'include')); Example 4 Load the libmx library and generate a prototype M-file containing the prototypes defined in header file matrix.h: hfile = [matlabroot '\extern\include\matrix.h']; loadlibrary('libmx.dll', hfile, 'mfilename', 'mxproto') dir mxproto.m mxproto.m Edit the generated file mxproto.m and locate the function 'mxGetNumberOfDimensions'. Give it an alias of 'mxGetDims' by adding this line to the file: fcns.alias{40}='mxGetDims'; loadlibrary 1-17 Unload the library and then reload it using the prototype M-file. unloadlibrary libmx loadlibrary('libmx.dll', @mxproto) Now call mxGetNumberOfDimensions using the alias function name: y = rand(4, 7, 2); calllib('libmx', 'mxGetDims', y) ans = 3 unloadlibrary libmx See Also libisloaded, unloadlibrary, libfunctions, libfunctionsview, libpointer, libstruct, calllib unloadlibrary 1-18 1unloadlibraryPurpose Unload an external library from memory Syntax unloadlibrary('libname') unloadlibrary libname Description unloadlibrary('libname') unloads the functions defined in shared library shrlib from memory. If you need to use these functions again, you must first load them back into memory using loadlibrary. unloadlibrary libname is the command format for this function. If you used an alias when initially loading the library, then you must use that alias for the libname argument. Examples Load the MATLAB sample shared library, shrlibsample. Call one of its functions, and then unload the library: addpath([matlabroot '\extern\examples\shrlib']) loadlibrary shrlibsample shrlibsample.h s.p1 = 476; s.p2 = -299; s.p3 = 1000; calllib('shrlibsample', 'addStructFields', s) ans = 1177 unloadlibrary shrlibsample See Also loadlibrary, libisloaded, libfunctions, libfunctionsview, libpointer, libstruct, calllib matClose 2-3 2matClosePurpose Closes a MAT-file C Syntax #include "mat.h" int matClose(MATFile *mfp); Arguments mfp Pointer to MAT-file information. Description matClose closes the MAT-file associated with mfp. It returns EOF for a write error, and zero if successful. Examples See matcreat.c and matdgns.c in the eng_mat subdirectory of the examples directory for sample programs that illustrate how to use the MATLAB MAT-file routines in a C program. matDeleteArray (Obsolete) 2-4 2matDeleteArray (Obsolete)V5 Compatible This API function is obsolete and should not be used in a program that interfaces with MATLAB 6.5 or later. This function may not be available in a future version of MATLAB. If you need to use this function in existing code, use the -V5 option of the mex script. Use matDeleteVariable(mfp, name) instead of matDeleteArray(mfp, name) See Also matDeleteVariable matDeleteMatrix (Obsolete) 2-5 2matDeleteMatrix (Obsolete) This API function is obsolete and should not be used in a program that interfaces with MATLAB 5 or later. Use matDeleteVariable(mfp, name) instead of matDeleteMatrix(mfp, name) See Also matDeleteVariable matGetArrayHeader (Obsolete) 2-8 2matGetArrayHeader (Obsolete)V5 Compatible This API function is obsolete and should not be used in a program that interfaces with MATLAB 6.5 or later. This function may not be available in a future version of MATLAB. If you need to use this function in existing code, use the -V5 option of the mex script. Use mp = matGetVariableInfo(mfp, name); instead of mp = matGetArrayHeader(mfp, name); See Also matGetVariableInfo matGetDir 2-9 2matGetDirPurpose Get directory of mxArrays in a MAT-file C Syntax #include "mat.h" char **matGetDir(MATFile *mfp, int *num); Arguments mfp Pointer to MAT-file information. num Address of the variable to contain the number of mxArrays in the MAT-file. Description This routine allows you to get a list of the names of the mxArrays contained within a MAT-file. matGetDir returns a pointer to an internal array containing pointers to the NULL-terminated names of the mxArrays in the MAT-file pointed to by mfp. The length of the internal array (number of mxArrays in the MAT-file) is placed into num. The internal array is allocated using a single mxCalloc and must be freed using mxFree when you are finished with it. matGetDir returns NULL and sets num to a negative number if it fails. If num is zero, mfp contains no arrays. MATLAB variable names can be up to length mxMAXNAM, where mxMAXNAM is defined in the file matrix.h. Examples See matcreat.c and matdgns.c in the eng_mat subdirectory of the examples directory for sample programs that illustrate how to use the MATLAB MAT-file routines in a C program. matGetFp 2-10 2matGetFpPurpose Get file pointer to a MAT-file C Syntax #include "mat.h" FILE *matGetFp(MATFile *mfp); Arguments mfp Pointer to MAT-file information. Description matGetFp returns the C file handle to the MAT-file with handle mfp. This can be useful for using standard C library routines like ferror() and feof() to investigate error situations. Examples See matcreat.c and matdgns.c in the eng_mat subdirectory of the examples directory for sample programs that illustrate how to use the MATLAB MAT-file routines in a C program. matGetMatrix (Obsolete) 2-13 2matGetMatrix (Obsolete) This API function is obsolete and should not be used in a program that interfaces with MATLAB 5 or later. Use mp = matGetVariable(mfp, name) instead of mp = matGetMatrix(mfp, name); See Also matGetVariable matGetNextArray (Obsolete) 2-14 2matGetNextArray (Obsolete)V5 Compatible This API function is obsolete and should not be used in a program that interfaces with MATLAB 6.5 or later. This function may not be available in a future version of MATLAB. If you need to use this function in existing code, use the -V5 option of the mex script. Use mp = matGetNextVariable(mfp, name); instead of mp = matGetNextArray(mfp); See Also matGetNextVariable matGetNextArrayHeader (Obsolete) 2-15 2matGetNextArrayHeader (Obsolete)V5 Compatible This API function is obsolete and should not be used in a program that interfaces with MATLAB 6.5 or later. This function may not be available in a future version of MATLAB. If you need to use this function in existing code, use the -V5 option of the mex script. Use matGetNextVariableInfo instead of matGetNextArrayHeader See Also matGetNextVariableInfo matGetNextVariableInfo 2-18 2matGetNextVariableInfoPurpose Load array header information only C Syntax #include "mat.h" mxArray *matGetNextVariableInfo(MATFile *mfp, const char *name); Arguments mfp Pointer to MAT-file information. name Address of the variable to contain the mxArray name. Description matGetNextVariableInfo loads only the array header information, including everything except pr, pi, ir, and jc, from the file’s current file offset. MATLAB returns the name of the mxArray in name. If pr, pi, ir, and jc are set to nonzero values when loaded with matGetVariable, matGetNextVariableInfo sets them to -1 instead. These headers are for informational use only and should never be passed back to MATLAB or saved to MAT-files. Examples See matcreat.c and matdgns.c in the eng_mat subdirectory of the examples directory for sample programs that illustrate how to use the MATLAB MAT-file routines in a C program. See Also matGetNextVariable, matGetVariableInfo matGetString (Obsolete) 2-19 2matGetString (Obsolete) This API function is obsolete and should not be used in a program that interfaces with MATLAB 5 or later. Use #include "mat.h" #include "matrix.h" mxArray *matGetVariable(MATFile *mfp, const char *name); int mxGetString(const mxArray *array_ptr, char *buf, int buflen) instead of matGetString See Also matGetVariable, mxGetString matGetVariable 2-20 2matGetVariablePurpose Read mxArrays from MAT-files C Syntax #include "mat.h" mxArray *matGetVariable(MATFile *mfp, const char *name); Arguments mfp Pointer to MAT-file information. name Name of mxArray to get from MAT-file. Description This routine allows you to copy an mxArray out of a MAT-file. matGetVariable reads the named mxArray from the MAT-file pointed to by mfp and returns a pointer to a newly allocated mxArray structure, or NULL if the attempt fails. Be careful in your code to free the mxArray created by this routine when you are finished with it. Examples See matcreat.c and matdgns.c in the eng_mat subdirectory of the examples directory for sample programs that illustrate how to use the MATLAB MAT-file routines in a C program. matOpen 2-23 Examples See matcreat.c and matdgns.c in the eng_mat subdirectory of the examples directory for sample programs that illustrate how to use the MATLAB MAT-file routines in a C program. matPutArray (Obsolete) 2-24 2matPutArray (Obsolete)V5 Compatible This API function is obsolete and should not be used in a program that interfaces with MATLAB 6.5 or later. This function may not be available in a future version of MATLAB. If you need to use this function in existing code, use the -V5 option of the mex script. Use matPutVariable(mfp, name, mp); instead of mxSetName(mp, name); matPutArray(mfp, mp); See Also matPutVariable matPutArrayAsGlobal (Obsolete) 2-25 2matPutArrayAsGlobal (Obsolete)V5 Compatible This API function is obsolete and should not be used in a program that interfaces with MATLAB 6.5 or later. This function may not be available in a future version of MATLAB. If you need to use this function in existing code, use the -V5 option of the mex script. Use matPutVariableAsGlobal instead of matPutArrayAsGlobal See Also matPutVariableAsGlobal matPutMatrix (Obsolete) 2-28 2matPutMatrix (Obsolete) This API function is obsolete and should not be used in a program that interfaces with MATLAB 5 or later. Use matPutVariable instead of matPutMatrix See Also matPutVariable matPutString (Obsolete) 2-29 2matPutString (Obsolete) This API function is obsolete and should not be used in a program that interfaces with MATLAB 5 or later. Use #include "matrix.h" #include "mat.h" mp = mxCreateString(str); matPutVariable(mfp, name, mp); mxDestroyArray(mp); instead of matPutString(mfp, name, str); See Also matPutVariable matPutVariable 2-30 2matPutVariablePurpose Write mxArrays into MAT-files C Syntax #include "mat.h" int matPutVariable(MATFile *mfp, const char *name, const mxArray *mp); Arguments mfp Pointer to MAT-file information. name Name of mxArray to put into MAT-file. mp mxArray pointer. Description This routine allows you to put an mxArray into a MAT-file. matPutVariable writes mxArray mp to the MAT-file mfp. If the mxArray does not exist in the MAT-file, it is appended to the end. If an mxArray with the same name already exists in the file, the existing mxArray is replaced with the new mxArray by rewriting the file. The size of the new mxArray can be different than the existing mxArray. matPutVariable returns 0 if successful and nonzero if an error occurs. Use feof and ferror from the Standard C Library along with matGetFp to determine status. Examples See matcreat.c and matdgns.c in the eng_mat subdirectory of the examples directory for sample programs that illustrate how to use the MATLAB MAT-file routines in a C program. 3 C MX-Functions mxAddField Add field to structure array mxArrayToString Convert arrays to strings mxAssert Check assertion value mxAssertS Check assertion value; doesn’t print assertion’s text mxCalcSingleSubscript Return offset from first element to desired element mxCalloc Allocate dynamic memory mxChar String mxArrays data type mxClassID Integer value that identifies mxArray's class mxClearLogical (Obsolete) Clear logical flag mxComplexity Specifies if mxArray has imaginary components mxCreateCellArray Create unpopulated N-dimensional cell mxArray mxCreateCellMatrix Create unpopulated two-dimensional cell mxArray mxCreateCharArray Create unpopulated N-dimensional string mxArray mxCreateCharMatrixFromStrings Create populated two-dimensional string mxArray mxCreateDoubleMatrix Create unpopulated two-dimensional, double-precision, floating-point mxArray mxCreateDoubleScalar Create scalar, double-precision array initialized to the specified value mxCreateLogicalArray Create N-dimensional, logical mxArray initialized to false mxCreateLogicalMatrix Create two-dimensional, logical mxArray initialized to false mxCreateLogicalScalar Create scalar, logical mxArray initialized to false mxCreateFull (Obsolete) Use mxCreateDoubleMatrix mxCreateNumericArray Create unpopulated N-dimensional numeric mxArray mxCreateNumericMatrix Create numeric matrix and initialize data elements to 0 mxCreateScalarDouble Create scalar, double-precision array initialized to specified value 3-2 mxCreateSparse Create two-dimensional unpopulated sparse mxArray mxCreateSparseLogicalMatrix Create unpopulated, two-dimensional, sparse, logical mxArray mxCreateString Create 1-by-n string mxArray initialized to specified string mxCreateStructArray Create unpopulated N-dimensional structure mxArray mxCreateStructMatrix Create unpopulated two-dimensional structure mxArray mxDestroyArray Free dynamic memory allocated by an mxCreate routine mxDuplicateArray Make deep copy of array mxFree Free dynamic memory allocated by mxCalloc mxFreeMatrix (Obsolete) Use mxDestroyArray mxGetCell Get cell’s contents mxGetChars Get pointer to character array data mxGetClassID Get mxArray's class mxGetClassName Get mxArray's class mxGetData Get pointer to data mxGetDimensions Get pointer to dimensions array mxGetElementSize Get number of bytes required to store each data element mxGetEps Get value of eps mxGetField Get field value, given field name and index in structure array mxGetFieldByNumber Get field value, given field number and index in structure array mxGetFieldNameByNumber Get field name, given field number in structure array mxGetFieldNumber Get field number, given field name in structure array mxGetImagData Get pointer to imaginary data of mxArray mxGetInf Get value of infinity mxGetIr Get ir array of sparse matrix mxGetJc Get jc array of sparse matrix mxGetLogicals Get pointer to logical array data 3-3 mxGetM Get number of rows mxGetN Get number of columns or number of elements mxGetName (Obsolete) Get name of specified mxArray mxGetNaN Get the value of NaN mxGetNumberOfDimensions Get number of dimensions mxGetNumberOfElements Get number of elements in array mxGetNumberOfFields Get number of fields in structure mxArray mxGetNzmax Get number of elements in ir, pr, and pi arrays mxGetPi Get mxArray’s imaginary data elements mxGetPr Get mxArray’s real data elements mxGetScalar Get real component of mxArray's first data element mxGetString Copy string mxArray's data into C-style string mxIsCell True if cell mxArray mxIsChar True if string mxArray mxIsClass True if mxArray is member of specified class mxIsComplex True if data is complex mxIsDouble True if mxArray represents its data as double-precision, floating-point numbers mxIsEmpty True if mxArray is empty mxIsFinite True if value is finite mxIsFromGlobalWS True if mxArray was copied from the MATLAB global workspace mxIsFull (Obsolete) Use mxIsSparse mxIsInf True if value is infinite mxIsInt8 True if mxArray represents its data as signed 8-bit integers mxIsInt16 True if mxArray represents its data as signed 16-bit integers mxIsInt32 True if mxArray represents its data as signed 32-bit integers mxAddField 3-6 3mxAddFieldPurpose Add a field to a structure array C Syntax #include "matrix.h" extern int mxAddField(mxArray array_ptr, const char *field_name); Arguments array_ptr Pointer to a structure mxArray. field_name The name of the field you want to add. Returns Field number on success or -1 if inputs are invalid or an out of memory condition occurs. Description Call mxAddField to add a field to a structure array. You must then create the values with the mxCreate* functions and use mxSetFieldByNumber to set the individual values for the field. See Also mxRemoveField, mxSetFieldByNumber mxArrayToString 3-7 3mxArrayToStringPurpose Convert arrays to strings C Syntax #include "matrix.h" char *mxArrayToString(const mxArray *array_ptr); Arguments array_ptr Pointer to a string mxArray; that is, a pointer to an mxArray having the mxCHAR_CLASS class. Returns A C-style string. Returns NULL on out of memory. Description Call mxArrayToString to copy the character data of a string mxArray into a C-style string. The C-style string is always terminated with a NULL character. If the string array contains several rows, they are copied, one column at a time, into one long string array. This function is similar to mxGetString, except that: • It does not require the length of the string as an input. • It supports multibyte character sets. mxArrayToString does not free the dynamic memory that the char pointer points to. Consequently, you should typically free the string (using mxFree) immediately after you have finished using it. Examples See mexatexit.c in the mex subdirectory of the examples directory. For additional examples, see mxcreatecharmatrixfromstr.c and mxislogical.c in the mx subdirectory of the examples directory. See Also mxCreateCharArray, mxCreateCharMatrixFromStrings, mxCreateString, mxGetString mxAssert 3-8 3mxAssertPurpose Check assertion value for debugging purposes C Syntax #include "matrix.h" void mxAssert(int expr, char *error_message); Arguments expr Value of assertion. error_message Description of why assertion failed. Description Similar to the ANSI C assert() macro, mxAssert checks the value of an assertion, and continues execution only if the assertion holds. If expr evaluates to true, mxAssert does nothing. If expr is false, mxAssert prints an error to the MATLAB command window consisting of the failed assertion’s expression, the filename and line number where the failed assertion occurred, and the error_message string. The error_message string allows you to specify a better description of why the assertion failed. Use an empty string if you don’t want a description to follow the failed assertion message. After a failed assertion, control returns to the MATLAB command line. Note that the MEX script turns off these assertions when building optimized MEX-functions, so you should use this for debugging purposes only. Build the mex file using the syntax, mex -g filename, in order to use mxAssert. Assertions are a way of maintaining internal consistency of logic. Use them to keep yourself from misusing your own code and to prevent logical errors from propagating before they are caught; do not use assertions to prevent users of your code from misusing it. Assertions can be taken out of your code by the C preprocessor. You can use these checks during development and then remove them when the code works properly, letting you use them for troubleshooting during development without slowing down the final product. mxCalcSingleSubscript 3-11 MATLAB uses a column-major numbering scheme to represent data elements internally. That means that MATLAB internally stores data elements from the first column first, then data elements from the second column second, and so on through the last column. For example, suppose you create a 4-by-2 variable. It is helpful to visualize the data as shown below. Although in fact, MATLAB internally represents the data as the following: If an mxArray is N-dimensional, then MATLAB represents the data in N-major order. For example, consider a three-dimensional array having dimensions 4-by-2-by-3. Although you can visualize the data as A E B F C G D H A B C D E F G H Index 0 Index 1 Index 2 Index 3 Index 4 Index 5 Index 6 Index 7 mxCalcSingleSubscript 3-12 MATLAB internally represents the data for this three-dimensional array in the order shown below: Avoid using mxCalcSingleSubscript to traverse the elements of an array. It is more efficient to do this by finding the array’s starting address and then using pointer auto-incrementing to access successive elements. For example, to find the starting address of a numerical array, call mxGetPr or mxGetPi. Examples See mxcalcsinglesubscript.c in the mx subdirectory of the examples directory. A B C D E F G H I J K L M N O P Q R S T U V W X 0 1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 1 8 1 9 2 0 2 1 2 2 2 3 A B C D E F G H I J K L M N O P Q R S T U V W X Page 1 Page 2 Page 3 mxCalloc 3-13 3mxCallocPurpose Allocate dynamic memory using the MATLAB memory manager C Syntax #include "matrix.h" #include <stdlib.h> void *mxCalloc(size_t n, size_t size); Arguments n Number of elements to allocate. This must be a nonnegative number. size Number of bytes per element. (The C sizeof operator calculates the number of bytes per element.) Returns A pointer to the start of the allocated dynamic memory, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCalloc returns NULL. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. mxCalloc is unsuccessful when there is insufficient free heap space. Description MATLAB applications should always call mxCalloc rather than calloc to allocate memory. Note that mxCalloc works differently in MEX-files than in stand-alone MATLAB applications. In MEX-files, mxCalloc automatically • Allocates enough contiguous heap space to hold n elements. • Initializes all n elements to 0. • Registers the returned heap space with the MATLAB memory management facility. The MATLAB memory management facility maintains a list of all memory allocated by mxCalloc. The MATLAB memory management facility automatically frees (deallocates) all of a MEX-file’s parcels when control returns to the MATLAB prompt. In stand-alone MATLAB applications, mxCalloc defaults to calling the ANSI C calloc function. If this default behavior is unacceptable, you can write your own memory allocation routine, and then register this routine with mxClassID 3-16 3mxClassIDPurpose Integer value that identifies an mxArray's class (category) C Syntax typedef enum { mxUNKNOWN_CLASS = 0, mxCELL_CLASS, mxSTRUCT_CLASS, mxLOGICAL_CLASS, mxCHAR_CLASS, <unused>, mxDOUBLE_CLASS, mxSINGLE_CLASS, mxINT8_CLASS, mxUINT8_CLASS, mxINT16_CLASS, mxUINT16_CLASS, mxINT32_CLASS, mxUINT32_CLASS, mxINT64_CLASS, mxUINT64_CLASS, mxFUNCTION_CLASS } mxClassID; Constants mxUNKNOWN_CLASS The class cannot be determined. You cannot specify this category for an mxArray; however, mxGetClassID can return this value if it cannot identify the class. mxCELL_CLASS Identifies a cell mxArray. mxSTRUCT_CLASS Identifies a structure mxArray. mxLOGICAL_CLASS Identifies a logical mxArray; that is, an mxArray that stores Boolean elements, true and false. mxCHAR_CLASS Identifies a string mxArray; that is an mxArray whose data is represented as mxCHAR’s. mxClassID 3-17 mxDOUBLE_CLASS Identifies a numeric mxArray whose data is stored as double-precision, floating-point numbers. mxSINGLE_CLASS Identifies a numeric mxArray whose data is stored as single-precision, floating-point numbers. mxINT8_CLASS Identifies a numeric mxArray whose data is stored as signed 8-bit integers. mxUINT8_CLASS Identifies a numeric mxArray whose data is stored as unsigned 8-bit integers. mxINT16_CLASS Identifies a numeric mxArray whose data is stored as signed 16-bit integers. mxUINT16_CLASS Identifies a numeric mxArray whose data is stored as unsigned 16-bit integers. mxINT32_CLASS Identifies a numeric mxArray whose data is stored as signed 32-bit integers. mxUINT32_CLASS Identifies a numeric mxArray whose data is stored as unsigned 32-bit integers. mxINT64_CLASS Identifies a numeric mxArray whose data is stored as signed 64-bit integers. mxUINT64_CLASS Identifies a numeric mxArray whose data is stored as unsigned 64-bit integers. mxFUNCTION_CLASS Identifies a function handle mxArray. Description Various mx calls require or return an mxClassID argument. mxClassID identifies the way in which the mxArray represents its data elements. Examples See explore.c in the mex subdirectory of the examples directory. See Also mxCreateNumericArray mxClearLogical (Obsolete) 3-18 3mxClearLogical (Obsolete)Purpose Clear the logical flag Note As of MATLAB version 6.5, mxClearLogical is obsolete. Support for mxClearLogical may be removed in a future version. C Syntax #include "matrix.h" void mxClearLogical(mxArray *array_ptr); Arguments array_ptr Pointer to an mxArray having a numeric class. Description Use mxClearLogical to turn off the mxArray’s logical flag. This flag, when cleared, tells MATLAB to treat the mxArray’s data as numeric data rather than as Boolean data. If the logical flag is on, then MATLAB treats a 0 value as meaning false and a nonzero value as meaning true. Call mxCreateLogicalScalar, mxCreateLogicalMatrix, mxCreateNumericArray, or mxCreateSparseLogicalMatrix to turn on the mxArray’s logical flag. For additional information on the use of logical variables in MATLAB, type help logical at the MATLAB prompt. Examples See mxislogical.c in the mx subdirectory of the examples directory. See Also mxIsLogical mxCreateCellMatrix 3-21 3mxCreateCellMatrixPurpose Create unpopulated two-dimensional cell mxArray C Syntax #include "matrix.h" mxArray *mxCreateCellMatrix(int m, int n); Arguments m The desired number of rows. n The desired number of columns. Returns A pointer to the created cell mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateCellMatrix returns NULL. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. Insufficient free heap space is the only reason for mxCreateCellMatrix to be unsuccessful. Description Use mxCreateCellMatrix to create an m-by-n two-dimensional cell mxArray. The created cell mxArray is unpopulated; that is, mxCreateCellMatrix initializes each cell to NULL. To put data into cells, call mxSetCell. mxCreateCellMatrix is identical to mxCreateCellArray except that mxCreateCellMatrix can create two-dimensional mxArrays only, but mxCreateCellArray can create mxArrays having any number of dimensions greater than 1. Examples See mxcreatecellmatrix.c in the mx subdirectory of the examples directory. See Also mxCreateCellArray mxCreateCharArray 3-22 3mxCreateCharArrayPurpose Create unpopulated N-dimensional string mxArray C Syntax #include "matrix.h" mxArray *mxCreateCharArray(int ndim, const int *dims); Arguments ndim The desired number of dimensions in the string mxArray. You must specify a positive number. If you specify 0, 1, or 2, mxCreateCharArray creates a two-dimensional mxArray. dims The dimensions array. Each element in the dimensions array contains the size of the array in that dimension. For example, setting dims[0] to 5 and dims[1] to 7 establishes a 5-by-7 mxArray. The dims array must have at least ndim elements. Returns A pointer to the created string mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateCharArray returns NULL. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. Insufficient free heap space is the only reason for mxCreateCharArray to be unsuccessful. Description Call mxCreateCharArray to create an unpopulated N-dimensional string mxArray. Examples See mxcreatecharmatrixfromstr.c in the mx subdirectory of the examples directory. See Also mxCreateCharMatrixFromStrings, mxCreateString mxCreateCharMatrixFromStrings 3-23 3mxCreateCharMatrixFromStringsPurpose Create populated two-dimensional string mxArray C Syntax #include "matrix.h" mxArray *mxCreateCharMatrixFromStrings(int m, const char **str); Arguments m The desired number of rows in the created string mxArray. The value you specify for m should equal the number of strings in str. str A pointer to a list of strings. The str array must contain at least m strings. Returns A pointer to the created string mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateCharMatrixFromStrings returns NULL. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. Insufficient free heap space is the primary reason for mxCreateCharArray to be unsuccessful. Another possible reason for failure is that str contains fewer than m strings. Description Use mxCreateCharMatrixFromStrings to create a two-dimensional string mxArray, where each row is initialized to a string from str. The created mxArray has dimensions m-by-max, where max is the length of the longest string in str. Note that string mxArrays represent their data elements as mxChar rather than as char. Examples See mxcreatecharmatrixfromstr.c in the mx subdirectory of the examples directory. See Also mxCreateCharArray, mxCreateString, mxGetString mxCreateFull (Obsolete) 3-26 3mxCreateFull (Obsolete) This API function is obsolete and is not supported in MATLAB 5 or later. Use mxCreateDoubleMatrix instead of mxCreateFull See Also mxCreateDoubleMatrix mxCreateLogicalArray 3-27 3mxCreateLogicalArrayPurpose Create N-dimensional logical mxArray initialized to false C Syntax #include "matrix.h" mxArray *mxCreateLogicalArray(int ndim, const int *dims); Arguments ndim Number of dimensions. If you specify a value for ndim that is less than 2, mxCreateLogicalArray automatically sets the number of dimensions to 2. dims The dimensions array. Each element in the dimensions array contains the size of the array in that dimension. For example, setting dims[0] to 5 and dims[1] to 7 establishes a 5-by-7 mxArray. There should be ndim elements in the dims array. Returns A pointer to the created mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateLogicalArray returns NULL. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. mxCreateLogicalArray is unsuccessful when there is not enough free heap space to create the mxArray. Description Call mxCreateLogicalArray to create an N-dimensional mxArray of logical (true and false) elements. After creating the mxArray, mxCreateLogicalArray initializes all its elements to false. mxCreateLogicalArray differs from mxCreateLogicalMatrix in that the latter can create two-dimensional arrays only. mxCreateLogicalArray allocates dynamic memory to store the created mxArray. When you finish with the created mxArray, call mxDestroyArray to deallocate its memory. See Also mxCreateLogicalMatrix, mxCreateSparseLogicalMatrix, mxCreateLogicalScalar mxCreateLogicalMatrix 3-28 3mxCreateLogicalMatrixPurpose Create two-dimensional, logical mxArray initialized to false C Syntax #include "matrix.h" mxArray *mxCreateLogicalMatrix(int m, int n); Arguments m The desired number of rows. n The desired number of columns. Returns A pointer to the created mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateLogicalMatrix returns NULL. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. mxCreateLogicalMatrix is unsuccessful when there is not enough free heap space to create the mxArray. Description Use mxCreateLogicalMatrix to create an m-by-n mxArray of logical (true and false) elements. mxCreateLogicalMatrix initializes each element in the array to false. Call mxDestroyArray when you finish using the mxArray. mxDestroyArray deallocates the mxArray. See Also mxCreateLogicalArray, mxCreateSparseLogicalMatrix, mxCreateLogicalScalar mxCreateNumericArray 3-31 • All data elements in mxCreateDoubleMatrix are double-precision, floating-point numbers. The data elements in mxCreateNumericArray could be any numerical type, including different integer precisions. • mxCreateDoubleMatrix can create two-dimensional arrays only; mxCreateNumericArray can create arrays of two or more dimensions. mxCreateNumericArray allocates dynamic memory to store the created mxArray. When you finish with the created mxArray, call mxDestroyArray to deallocate its memory. Examples See phonebook.c and doubleelement.c in the refbook subdirectory of the examples directory. For an additional example, see mxisfinite.c in the mx subdirectory of the examples directory. See Also mxClassID, mxCreateDoubleMatrix, mxCreateSparse, mxCreateString, mxComplexity mxCreateNumericMatrix 3-32 3mxCreateNumericMatrixPurpose Create numeric matrix and initialize all its data elements to 0 C Syntax #include "matrix.h" mxArray *mxCreateNumericMatrix(int m, int n, mxClassID class, mxComplexity ComplexFlag); Arguments m The desired number of rows. n The desired number of columns. class The way in which the numerical data is to be represented in memory. For example, specifying mxINT16_CLASS causes each piece of numerical data in the mxArray to be represented as a 16-bit signed integer. You can specify any numeric class including mxDOUBLE_CLASS, mxSINGLE_CLASS, mxINT8_CLASS, mxUINT8_CLASS, mxINT16_CLASS, mxUINT16_CLASS, mxINT32_CLASS, mxUINT32_CLASS, mxINT64_CLASS, and mxUINT64_CLASS. ComplexFlag Specify either mxREAL or mxCOMPLEX. If the data you plan to put into the mxArray has no imaginary components, specify mxREAL. If the data has some imaginary components, specify mxCOMPLEX. Returns A pointer to the created mxArray, if successful. mxCreateNumericMatrix is unsuccessful if there is not enough free heap space to create the mxArray. If mxCreateNumericMatrix is unsuccessful in a MEX-file, the MEX-file prints an “Out of Memory” message, terminates, and control returns to the MATLAB prompt. If mxCreateNumericMatrix is unsuccessful in a stand-alone (nonMEX-file) application, mxCreateNumericMatrix returns NULL. Description Call mxCreateNumericMatrix to create an 2-dimensional mxArray in which all data elements have the numeric data type specified by class. After creating the mxArray, mxCreateNumericMatrix initializes all its real data elements to 0. If ComplexFlag equals mxCOMPLEX, mxCreateNumericMatrix also initializes all its imaginary data elements to 0. mxCreateNumericMatrix allocates dynamic memory to store the created mxArray. When you finish using the mxArray, call mxDestroyArray to destroy it. mxCreateNumericMatrix 3-33 See Also mxCreateNumericArray mxCreateSparse 3-36 When you finish using the sparse mxArray, call mxDestroyArray to reclaim all its heap space. Examples See fulltosparse.c in the refbook subdirectory of the examples directory. See Also mxDestroyArray, mxSetNzmax, mxSetPr, mxSetPi, mxSetIr, mxSetJc, mxComplexity mxCreateSparseLogicalMatrix 3-37 3mxCreateSparseLogicalMatrixPurpose Create unpopulated two-dimensional, sparse, logical mxArray C Syntax #include "matrix.h" mxArray *mxCreateSparseLogicalMatrix(int m, int n, int nzmax); Arguments m The desired number of rows. n The desired number of columns. nzmax The number of elements that mxCreateSparseLogicalMatrix should allocate to hold the data. Set the value of nzmax to be greater than or equal to the number of nonzero elements you plan to put into the mxArray, but make sure that nzmax is less than or equal to m*n. Returns A pointer to the created mxArray, if successful. If unsuccessful in a stand-alone (nonMEX-file) application, mxCreateSparseLogicalMatrix returns NULL. If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt. mxCreateSparseLogicalMatrix is unsuccessful when there is not enough free heap space to create the mxArray. Description Use mxCreateSparseLogicalMatrix to create an m-by-n mxArray of logical (true and false) elements. mxCreateSparseLogicalMatrix initializes each element in the array to false. Call mxDestroyArray when you finish using the mxArray. mxDestroyArray deallocates the mxArray and its elements. See Also mxCreateLogicalMatrix, mxCreateLogicalArray, mxCreateLogicalScalar, mxCreateSparse, mxIsLogical mxCreateString 3-38 3mxCreateStringPurpose Create 1-by-n string mxArray initialized to the specified string C Syntax #include "matrix.h" mxArray *mxCreateString(const char *str); Arguments str The C string that is to serve as the mxArray's initial data. Returns A pointer to the created string mxArray if successful, and NULL otherwise. The most likely cause of failure is insufficient free heap space. Description Use mxCreateString to create a string mxArray initialized to str. Many MATLAB functions (for example, strcmp and upper) require string array inputs. Free the string mxArray when you are finished using it. To free a string mxArray, call mxDestroyArray. Examples See revord.c in the refbook subdirectory of the examples directory. For additional examples, see mxcreatestructarray.c, mxisclass.c, and mxsetallocfcns.c in the mx subdirectory of the examples directory. See Also mxCreateCharMatrixFromStrings, mxCreateCharArray mxCreateStructMatrix 3-41 3mxCreateStructMatrixPurpose Create unpopulated two-dimensional structure mxArray C Syntax #include "matrix.h" mxArray *mxCreateStructMatrix(int m, int n, int nfields, const char **field_names); Arguments m The desired number of rows. This must be a positive integer. n The desired number of columns. This must be a positive integer. nfields The desired number of fields in each element. field_names The desired list of field names. Returns A pointer to the created structure mxArray if successful, and NULL otherwise. The most likely cause of failure is insufficient heap space to hold the returned mxArray. Description mxCreateStructMatrix and mxCreateStructArray are almost identical. The only difference is that mxCreateStructMatrix can only create two-dimensional mxArrays, while mxCreateStructArray can create mxArrays having two or more dimensions. Examples See phonebook.c in the refbook subdirectory of the examples directory. See Also mxCreateStructArray, mxGetFieldByNumber, mxGetFieldNameByNumber, mxGetFieldNumber, mxIsStruct mxDestroyArray 3-42 3mxDestroyArrayPurpose Free dynamic memory allocated by an mxCreate routine C Syntax #include "matrix.h" void mxDestroyArray(mxArray *array_ptr); Arguments array_ptr Pointer to the mxArray that you want to free. Description mxDestroyArray deallocates the memory occupied by the specified mxArray. mxDestroyArray not only deallocates the memory occupied by the mxArray's characteristics fields (such as m and n), but also deallocates all the mxArray's associated data arrays (such as pr, pi, ir, and/or jc). You should not call mxDestroyArray on an mxArray you are returning on the left-hand side. Examples See sincall.c in the refbook subdirectory of the examples directory. For additional examples, see mexcallmatlab.c and mexgetarray.c in the mex subdirectory of the examples directory; see mxisclass.c and mxsetallocfcns.c in the mx subdirectory of the examples directory. See Also mxCalloc, mxFree, mexMakeArrayPersistent, mexMakeMemoryPersistent mxDuplicateArray 3-43 3mxDuplicateArrayPurpose Make a deep copy of an array C Syntax #include "matrix.h" mxArray *mxDuplicateArray(const mxArray *in); Arguments in Pointer to the mxArray that you want to copy. Returns Pointer to a copy of the array. Description mxDuplicateArray makes a deep copy of an array, and returns a pointer to the copy. A deep copy refers to a copy in which all levels of data are copied. For example, a deep copy of a cell array copies each cell, and the contents of the each cell (if any), and so on. Examples See mexget.c in the mex subdirectory of the examples directory and phonebook.c in the refbook subdirectory of the examples directory. For additional examples, see mxcreatecellmatrix.c, mxgetinf.c, and mxsetnzmax.c in the mx subdirectory of the examples directory.