Call Functions in C++ Compiled Library - MATLAB & Simulink (original) (raw)
The publisher of your MATLAB® interface to a C++ library provides you with instructions for installing the interface file and any dependent library files, if required. The publisher might give you dependent library files, ask you to install libraries from an external source, or provide a link to all relevant files. If the publisher created a toolbox using MATLABAdd-Ons, then this information might be found in the Getting Started Guide available through the Options menu for the toolbox in the Add-On Manager. If you need more information or cannot find a Getting Started Guide, then contact the publisher. For details about add-ons, see Manage Add-Ons.
The name of the interface file for library libname islibnameInterface._`ext`_, where_ext_ is platform-specific — .dll on Windows®, .so on Linux®, or .dylib on macOS.
Set Run-Time Path
MATLAB looks for the interface file on the MATLAB path and the dependent library files on the system path or run-time search path (rpath). If the publisher gives you dependent library files, you can put them in the same folder as the interface file. Alternatively, to add them to the system path, see Set Run-Time Library Path for C++ Interface. For information about locating dependent libraries, see Missing or Incorrectly Installed Run-Time Libraries.
Set MATLAB Path
Call addpath on the folder containing the interface file.
Display Help
The MATLABhelp and doc functions provide help for members of the library. For example, to display help for function funcname in library libname, type:
help clib.libname.funcname
Call Function
To call a function funcname in C++ library libname with input arguments arg1,arg2,... and output argumentretVal, use the MATLABclib namespace. MATLAB automatically loads the library when you type:
retVal = clib.libname.funcname(arg1,arg2,...)
After MATLAB loads the library, you can use tab completion to view the members of theclib namespace.
MATLAB Type to C++ Type Mapping
When you pass MATLAB data as arguments to C++ methods or functions, MATLAB converts the data into types that best represent the data to the C++ language.
Each row in this table shows a MATLAB type followed by the possible C++ argument matches, from left to right in order of closeness of the match. The MATLAB types (except cell arrays) can be scalar (1-by-1) arrays or matrices. The C++ types can be scalar values or arrays. The phrase cpparray refers to these C++ array types:
- box array (
[]) - array buffer (
*) std::vector
| MATLAB Argument (Scalar or Array) | C++ Parameter Type (Scalar or Array)Types Other Than ObjectClosest Type <———————————————————————> Least Close Type | ||||||
|---|---|---|---|---|---|---|---|
| logical | bool cpparray bool | int8_t cpparray int8_t uint8_t cpparray uint8_t | int16_t cpparray int16_t uint16_t cpparray uint16_t | int32_t cpparray int32_t uint32_t cpparray uint32_t | int64_t cpparray int64_t uint64_t cpparray uint64_t | float cpparray float | double cpparray double |
| double | double cpparray double | float cpparray float | int64_t cpparray int64_t uint64_t cpparray uint64_t | int32_t cpparray int32_t uint32_t cpparray uint32_t | int16_t cpparray int16_t uint16_t cpparray uint16_t | int8_t cpparray int8_t uint8_t cpparray uint8_t | std::complex cpparray std::complex std::complex cpparray std::complex std::complex<int64_t> cpparray std::complex<int64_t> std::complex<uint64_t> cpparray std::complex<uint64_t> std::complex<int32_t> cpparray std::complex<int32_t> std::complex<uint32_t> cpparray std::complex<uint32_t> std::complex<int16_t> cpparray std::complex<int16_t> std::complex<uint16_t> cpparray std::complex<uint16_t> std::complex<int8_t> cpparray std::complex<int8_t> std::complex<uint8_t> cpparray std::complex<uint8_t> |
| single | float cpparray float | double cpparray double | std::complex cpparray std::complex | std::complex cpparray std::complex | |||
| [u]int8 | [u]int8_t cpparray [u]int8_t | [u]int16_t cpparray [u]int16_t | [u]int32_t cpparray [u]int32_t | [u]int64_t cpparray [u]int64_t | float cpparray float | double cpparray double | std::complex<[u]int8_t> cpparray std::complex<[u]int8_t> std::complex<[u]int16_t> cpparray std::complex<[u]int16_t> std::complex<[u]int32_t> cpparray std::complex<[u]int32_t> std::complex<[u]int64_t> cpparray std::complex<[u]int64_t> std::complex cpparray std::complex std::complex cpparray std::complex |
| [u]int16 | [u]int16_t cpparray [u]int16_t | [u]int32_t cpparray [u]int32_t | [u]int64_t cpparray [u]int64_t | float cpparray float | double cpparray double | std::complex<[u]int16_t> cpparray std::complex<[u]int16_t> std::complex<[u]int32_t> cpparray std::complex<[u]int32_t> std::complex<[u]int64_t> cpparray std::complex<[u]int64_t> std::complex cpparray std::complex std::complex cpparray std::complex | |
| [u]int32 | [u]int32_t cpparray [u]int32_t | [u]int64_t cpparray [u]int64_t | float cpparray float | double cpparray double | std::complex<[u]int32_t> cpparray std::complex<[u]int32_t> std::complex<[u]int64_t> cpparray std::complex<[u]int64_t> std::complex cpparray std::complex std::complex cpparray std::complex | ||
| [u]int64 | [u]int64_t cpparray [u]int64_t | float cpparray float | double cpparray double | std::complex<[u]int64_t> cpparray std::complex<[u]int64_t> std::complex cpparray std::complex std::complex cpparray std::complex | |||
| complex double | std::complex cpparray std::complex | std::complex cpparray std::complex | std::complex<int64_t> cpparray std::complex<int64_t> std::complex<uint64_t> cpparray std::complex<uint64_t> | std::complex<int32_t> cpparray std::complex<int32_t> std::complex<uint32_t> cpparray std::complex<uint32_t> | std::complex<int16_t> cpparray std::complex<int16_t> std::complex<uint16_t> cpparray std::complex<uint16_t> | std::complex<int8_t> cpparray std::complex<int8_t> std::complex<uint8_t> cpparray std::complex<uint8_t> | |
| complex single | std::complex cpparray std::complex | std::complex cpparray std::complex | |||||
| complex [u]int8 | std::complex<[u]int8_t> cpparray std::complex<[u]int8_t> | std::complex<[u]int16_t> cpparray std::complex<[u]int16_t> | std::complex<[u]int32_t> cpparray std::complex<[u]int32_t> | std::complex<[u]int64_t> cpparray std::complex<[u]int64_t> | std::complex cpparray std::complex | std::complex cpparray std::complex | |
| complex [u]int16 | std::complex<[u]int16_t> cpparray std::complex<[u]int16_t> | std::complex<[u]int32_t> cpparray std::complex<[u]int32_t> | std::complex<[u]int64_t> cpparray std::complex<[u]int64_t> | std::complex cpparray std::complex | std::complex cpparray std::complex | ||
| complex [u]int32 | std::complex<[u]int32_t> cpparray std::complex<[u]int32_t> | std::complex<[u]int64_t> cpparray std::complex<[u]int64_t> | std::complex cpparray std::complex | std::complex cpparray std::complex | |||
| complex [u]int64 | std::complex<[u]int64_t> cpparray std::complex<[u]int64_t> | std::complex cpparray std::complex | |||||
| char | cpparray char char16_t cpparray char16_t char32_t_cpparray_ char32_t wchar_t cpparray wchar_t | std::string std::wstring std::u16string std::u32string | |||||
| string scalarSee Call Function with Enum Arguments. | enum | ||||||
| string arraycell array of character vectors | std::vectorstd::string std::vectorstd::wstring std::vectorstd::u16string std::vectorstd::u32string | char * [] | |||||
| MATLAB object of C++ type MyClass | C++ object of type MyClass | ||||||
| MATLAB object of MATLAB class | Unsupported |
Call Function with Default Arguments
If a C++ function is defined with default arguments, then you can call the function without providing one or more trailing arguments. The function help shows the default value. For example, if the type of arg is double and its default value is 100, then help displays:
clib.libname.funcname(arg) Input Arguments arg double = 100
These statements produce the same result:
clib.libname.funcname clib.libname.funcname(100)
This statement is also correct, although your result might be different:
clib.libname.funcname(99)
MATLAB supports default arguments for scalar integer and floating point types.
Call Function with Enum Arguments
You can pass a string to a C++ function or method in C++ library_libname_ that acceptsclib._`libname`_.enum as an input argument.
For example, suppose that you have a MATLAB interface to C++ library libname with a functiongetValue that takes clib.libname.Days as input:
help clib.libname.getValue
getValue - clib.libname.getValue Representation of C++ function getValue.
RetVal = clib.libname.getValue(D) Input Arguments D clib.libname.Days
Output Arguments
RetVal int32 To display the values for clib.libname.Days, type:
Enumeration Summary Fri Mon Sat Sun Thu Tue Wed
You can call getValue with eitherclib.libname.Days.Sun or the string "Sun".
clib.libname.getValue(clib.libname.Days.Sun) clib.libname.getValue("Sun")
Access Violation Errors
When you make calls to the library, make sure that your library was compiled in Release mode, not Debug mode. For help with other common problems, see Troubleshooting MATLAB Interface to C++ Library Issues.