C++ MEX API

Примечание

API C++ MEX несовместим с API C MEX, описанным в приложении C MEX File Applications. Нельзя смешивать эти API в файле MEX.

C++ MEX API позволяет создавать приложения, использующие преимущества функций C++ 11, такие как семантика перемещения, обработка исключений и управление памятью .

`matlab::mex::Function`	Базовый класс для функций C++ MEX
`matlab::mex::ArgumentList`	Контейнер для входов и выходов функций C++ MEX
`matlab::engine::MATLABEngine`	Класс, определяющий API механизма

`matlab::mex::Function`

Все реализации файлов MEX являются классами, производными от matlab::mex::Function.

`std::shared_ptr<matlab::engine::MatlabEngine> getEngine()`	Получить указатель на `MATLABEngine` объект
`void mexLock()`	Предотвращение очистки MEX-файла от памяти
`void mexUnLock()`	Разрешить удаление файла MEX из памяти
`std::u16string getFunctionName()`	Получение имени текущей функции MEX

`matlab::mex::ArgumentList`

Аргументы функции MEX, переданные через operator() из MexFunction класс являются matlab::mex::ArgumentList контейнеры. ArgumentList является полным диапазоном для базовой коллекции массивов. ArgumentList объект поддерживает следующие функции.

`operator[]`	Позволяет `[]` индексирование в элементы `ArgumentList`.
`begin()`	Начать итератор.
`end()`	Конечный итератор.
`size()`	Возвращает число элементов в списке аргументов. Эта функция используется для проверки количества входов и выходов, указанных в месте вызова.
`empty()`	Возвращает логическое значение, указывающее, является ли список аргументов пустым (`size() == 0`).

API механизма C++

Доступ к функциям, переменным и объектам MATLAB ® с помощью matlab::engine::MATLABEngine API описан в следующих разделах. Для вызова matlab::engine::MATLABEngine функции, получить общий указатель, который возвращается matlab::mex::Function::getEngine функция. Например:

std::shared_ptr<matlab::engine::MATLABEngine> matlabPtr = getEngine();

Этот указатель используется для вызова функций механизма. Например:

matlabPtr->feval(...);

Функции обработчика вызовов только в том же потоке, что и MexFunction класс.

matlab:: двигатель:: MATLABEngine:: feval	Вызов функций MATLAB с аргументами
matlab:: двигатель:: MATLABEngine:: fevalAsync	Вызовите функцию MATLAB с аргументами и возвращенными значениями асинхронно.
matlab:: двигатель:: MATLABEngine:: eval	Оценка операторов MATLAB в базовой рабочей области
matlab:: двигатель:: MATLABEngine:: evalAsync	Асинхронная оценка инструкций MATLAB в базовой рабочей области
matlab:: engine:: MATLABEngine:: getVariable	Получение переменных из базы MATLAB или глобальной рабочей области
matlab:: engine:: MATLABEngine:: getVariiveAsync	Асинхронное получение переменных из базы MATLAB или глобальной рабочей области
matlab:: двигатель:: MATLABEngine:: setVariable	Поместить переменные в базовую или глобальную рабочую область MATLAB
matlab:: engine:: MATLABEngine:: setVariiveAsync	Помещать переменные в базовую или глобальную рабочую область MATLAB асинхронно
matlab:: engine:: MATLABEngine:: getProperty	Получить свойство объекта
matlab:: engine:: MATLABEngine:: getPropertyAsync	Асинхронное получение свойства объекта
matlab:: двигатель:: MATLABEngine:: setProperty	Задать свойство объекта
matlab:: engine:: MATLABEngine:: setPropertyAsync	Асинхронное задание свойства объекта

`matlab::engine::MATLABEngine::feval`

std::vector<matlab::data::Array> feval(const std::u16string &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())

matlab::data::Array feval(const std::u16string &function, 
   const std::vector<matlab::data::Array> &args, 
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())

matlab::data::Array feval(const std::u16string &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())

ResultType feval(const std::u16string &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs )

ResultType feval(const std::u16string &function,
   RhsArgs&&... rhsArgs)

Описание

Вызовите функции MATLAB из функций MEX. Использовать feval вызов функций MATLAB с аргументами, передаваемыми из функций MEX, и возврат результата из функции MATLAB в функцию MEX.

Входы и выходы - это типы, определенные API данных MATLAB. Также существует синтаксис для поддержки собственных типов C++.

Параметры

`const std::u16string &function`	Имя вычисляемой функции или сценария MATLAB. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.
`const size_t nlhs`	Количество возвращенных значений.
`const std::vector<matlab::data::Array> &args`	Несколько входных аргументов для передачи функции MATLAB в `std::vector`. Вектор преобразуется в массив столбцов в MATLAB.
`const matlab::data::Array &arg`	Одиночный входной аргумент для передачи функции MATLAB.
`const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()`	Буфер потока, используемый для хранения стандартных выходных данных функции MATLAB.
`const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()`	Буфер потока, используемый для хранения сообщения об ошибке из функции MATLAB.
`RhsArgs&&... rhsArgs`	Собственные типы данных C++, используемые для ввода функций. `feval` принимает скалярные входы этих типов данных C++: `bool`, `int8_t`, `int16_t`, `int32_t`, `int64_t`, `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`, `float`, `double`.

Возвращаемое значение

`std::vector<matlab::data::Array>`	Выходные данные, возвращенные функцией MATLAB.
`matlab::data::Array`	Один выход, возвращенный функцией MATLAB.
`ResultType`	Вывод, возвращенный функцией MATLAB в качестве пользовательского типа. Может быть `std::tuple` при возврате нескольких аргументов.

Исключения

`matlab::engine::MATLABException`	В функции имеется ошибка времени выполнения MATLAB.
`matlab::engine::TypeConversionException`	Результат функции MATLAB не может быть преобразован в указанный тип.
`matlab::engine::MATLABSyntaxException`	Синтаксическая ошибка в функции MATLAB.

Для получения дополнительной информации см. Вызов функций MATLAB из функций MEX

`matlab::engine::MATLABEngine::fevalAsync`

FutureResult<std::vector<matlab::data::Array>> fevalAsync(const std::u16string &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())

FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())

FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> & output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> & error = std::shared_ptr<matlab::engine::StreamBuffer>())

FutureResult<ResultType> fevalAsync(const std::u16string &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs)

FutureResult<ResultType> fevalAsync(const std::u16string &function,
   RhsArgs&&... rhsArgs)

Описание

Вызовите функцию MATLAB с аргументами и возвращенными значениями асинхронно. Дополнительные сведения Создание асинхронных запросов с помощью mexCallMATLAB.

Параметры

`const std::u16string &function`	Имя вычисляемой функции или сценария MATLAB. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.
`const size_t numReturned`	Количество возвращенных значений
`const std::vector<matlab::data::Array> &args`	Несколько входных аргументов для передачи функции MATLAB в `std::vector`. Вектор преобразуется в массив столбцов в MATLAB.
`const matlab::data::Array arg`	Одиночный входной аргумент для передачи функции MATLAB.
`const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()`	Буфер потока, используемый для хранения стандартных выходных данных функции MATLAB.
`const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()`	Буфер потока, используемый для хранения сообщения об ошибке из функции MATLAB.
`RhsArgs&&... rhsArgs`	Собственные типы данных C++, используемые для ввода функций. `feval` принимает скалярные входы этих типов данных C++: `bool`, `int8_t`, `int16_t`, `int32_t`, `int64_t`, `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`, `float`, `double`.

Возвращаемое значение

FutureResult

A FutureResult используется для получения результата вызова функции MATLAB.

Исключения

Ничего

`matlab::engine::MATLABEngine::eval`

void eval(const std::u16string &statement,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer> ())

Описание

Вычислите инструкцию MATLAB как текстовую строку в рабочей области вызывающей функции.

Параметры

`const std::u16string &statement`	Оператор MATLAB для оценки
`const std::shared_ptr<matlab::engine::StreamBuffer> &output`	Буфер потока, используемый для хранения стандартных выходных данных инструкции MATLAB
`const std::shared_ptr<matlab::engine::StreamBuffer> &error`	Буфер потока, используемый для хранения сообщения об ошибке из команды MATLAB

Исключения

`matlab::engine::MATLABExecutionException`	Ошибка времени выполнения в инструкции MATLAB.
`matlab::engine::MATLABSyntaxException`	Синтаксическая ошибка в инструкции MATLAB.

Для получения дополнительной информации см. Выполнение инструкций MATLAB из функции MEX

`matlab::engine::MATLABEngine::evalAsync`

FutureResult<void> evalAsync(const std::u16string &str,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer> ())

Описание

Вычислите оператор MATLAB как строку асинхронно. Дополнительные сведения Создание асинхронных запросов с помощью mexCallMATLAB.

Параметры

`const std::u16string &str`	Оператор MATLAB для оценки
`const std::shared_ptr<matlab::engine::StreamBuffer> & output`	Буфер потока, используемый для хранения стандартных выходных данных инструкции MATLAB.
`const std::shared_ptr<matlab::engine::StreamBuffer> & error`	Буфер потока, используемый для хранения сообщения об ошибке из команды MATLAB.

Возвращаемое значение

matlab::engine::FutureResult

A FutureResult объект, используемый для ожидания завершения инструкции MATLAB.

Исключения

Ничего

`matlab::engine::MATLABEngine::getVariable`

matlab::data::Array getVariable(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

Описание

Получение переменной из базовой или глобальной рабочей области MATLAB.

Параметры

`const std::u16string& varName`	Имя переменной в рабочей области MATLAB. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.
`matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE`	Для получения переменной из рабочей области MATLAB (BASE или GLOBAL). Дополнительные сведения см. в разделе `global` и `matlab::engine::WorkspaceType`.

Возвращаемое значение

matlab::data::Array

Переменная, полученная из базы MATLAB или глобальной рабочей области

Исключения

matlab::engine::MATLABExecutionException

Запрошенная переменная не существует в указанной базовой или глобальной рабочей области MATLAB.

Дополнительные сведения см. в разделе Установка и получение переменных MATLAB из MEX

`matlab::engine::MATLABEngine::getVariableAsync`

FutureResult<matlab::data::Array> getVariableAsync(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

Описание

Асинхронное получение переменной из базовой или глобальной рабочей области MATLAB.

Параметры

`const std::u16string& varName`	Имя переменной в рабочей области MATLAB. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.
`WorkspaceType workspaceType = WorkspaceType::BASE`	Для получения переменной из рабочей области MATLAB (BASE или GLOBAL). Дополнительные сведения см. в разделе `global`.

Возвращаемое значение

matlab::engine::FutureResult

A FutureResult объект, который можно использовать для получения переменной, полученной из рабочей области MATLAB, как matlab.data.Array.

Исключения

Ничего

`matlab::engine::MATLABEngine::setVariable`

void setVariable(const std::u16string &varName,
   const matlab::data::Array &var,
   WorkspaceType workspaceType = WorkspaceType::BASE)

Описание

Поместите переменную в базовую или глобальную рабочую область MATLAB. Если переменная с таким именем существует в рабочей области MATLAB, setVariable перезаписывает его.

Параметры

`const std::u16string& varName`	Имя переменной, создаваемой в рабочей области MATLAB. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.
`const matlab::data::Array var`	Значение переменной, создаваемой в рабочей области MATLAB.
`matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE`	MATLAB-рабочее пространство (BASE или GLOBAL) для вставки переменной в. Дополнительные сведения см. в разделе `global` и `matlab::engine::WorkspaceType`.

Дополнительные сведения см. в разделе Установка и получение переменных MATLAB из MEX

`matlab::engine::MATLABEngine::setVariableAsync`

FutureResult<void> setVariableAsync(const std::u16string &varName,
   const matlab::data::Array var,
   WorkspaceType workspaceType = WorkspaceType::BASE)

Описание

Помещайте переменную в базовую или глобальную рабочую область MATLAB асинхронно. Если переменная с таким именем существует в базовой рабочей области MATLAB, setVariableAsync перезаписывает его.

Параметры

`const std::u16string& varName`	Имя переменной, создаваемой в рабочей области MATLAB. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.
`const matlab::data::Array var`	Значение переменной, создаваемой в рабочей области MATLAB
`WorkspaceType workspaceType = WorkspaceType::BASE`	Поместите переменную в рабочую область MATLAB BASE или GLOBAL. Дополнительные сведения см. в разделе `global`.

Исключения

Ничего

`matlab::engine::MATLABEngine::getProperty`

matlab::data::Array getProperty(const matlab::data::Array &objectArray,
    size_t index,
    const std::u16string &propertyName)

matlab::data::Array getProperty(const matlab::data::Array &object,
    const std::u16string &propertyName)

Описание

Получение значения свойства объекта. Если входной аргумент объекта является массивом объектов, укажите индекс элемента массива, соответствующий объекту, значение свойства которого требуется получить.

Параметры

`const matlab::data::Array &objectArray`	Массив объектов MATLAB
`const matlab::data::Array &object`	Скалярный объект MATLAB
`size_t index`	Отсчитываемый от нуля индекс в массиве объектов, указывающий объект в массиве, значение свойства которого возвращается
`const std::u16string &propertyName`	Имя свойства. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.

Возвращаемое значение

matlab::data::Array

Значение именованного свойства

Исключения

matlab::engine::MATLABExecutionException

Свойство не существует.

Для получения дополнительной информации см. Объекты MATLAB в функциях MEX

`matlab::engine::MATLABEngine::getPropertyAsync`

matlab::engine::FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &objectArray,
    size_t index,
    const std::u16string &propertyName)

matlab::engine::FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &object,
   const std::u16string &propertyName)

Описание

Получение значения свойства объекта асинхронно. Если входной аргумент объекта является массивом объектов, укажите индекс элемента массива, соответствующий объекту, значение свойства которого требуется получить.

Параметры

`const matlab::data::Array &objectArray`	Массив объектов MATLAB
`const matlab::data::Array &object`	Скалярный объект MATLAB
`size_t index`	Отсчитываемый от нуля индекс в массиве объектов, указывающий объект в массиве, значение свойства которого возвращается
`const std::u16string &propertyName`	Имя свойства. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.

Возвращаемое значение

matlab::engine::FutureResult

matlab::engine::FutureResult объект, используемый для синхронизации операции.

Исключения

Ничего

`matlab::engine::MATLABEngine::setProperty`

void setProperty(matlab::data::Array &objectArray,   
    size_t index,
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)

void setProperty(matlab::data::Array &object, 
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)

Описание

Задайте значение свойства объекта. Если входной аргумент объекта является массивом объектов, укажите индекс элемента массива, соответствующий объекту, значение свойства которого требуется задать.

Параметры

`matlab::data::Array &objectArray`	Массив объектов MATLAB
`matlab::data::Array &object`	Скалярный объект MATLAB
`size_t index`	Отсчитываемый от нуля индекс в массиве объектов, указывающий объект в массиве, для которого задано значение свойства
`const std::u16string &propertyName`	Имя устанавливаемого свойства. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.
`const matlab::data::Array &propertyValue`	Значение, назначенное свойству

Исключения

matlab::engine::MATLABExecutionException

Свойство не существует.

Для получения дополнительной информации см. Объекты MATLAB в функциях MEX

`matlab::engine::MATLABEngine::setPropertyAsync`

FutureResult<void> setPropertyAsync(matlab::data::Array &objectArray,   
    size_t index,
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)

FutureResult<void> setPropertyAsync(matlab::data::Array &object,
 const std::u16string &propertyName,
 const matlab::data::Array &propertyValue)

Описание

Задайте значение свойства объекта асинхронно. Если входной аргумент объекта является массивом объектов, укажите индекс элемента массива, соответствующий объекту, значение свойства которого требуется задать.

Параметры

`matlab::data::Array &objectArray`	Массив объектов MATLAB
`matlab::data::Array &object`	Скалярный объект MATLAB
`size_t index`	Отсчитываемый от нуля индекс в массиве объектов, указывающий объект в массиве, для которого задано значение свойства
`const std::u16string &propertyName`	Имя устанавливаемого свойства. Укажите имя как `std::u16string`. Кроме того, можно указать этот параметр как `std::string`.
`const matlab::data::Array &propertyValue`	Значение, назначенное свойству.

Исключения

Ничего

Классы исключений

Исключение	Причина
`matlab::engine::EngineException`	Существует ошибка времени выполнения MATLAB в функции или не удается запустить MATLAB.
`matlab::engine::MATLABSyntaxException`	Синтаксическая ошибка в функции MATLAB.
`matlab::engine::MATLABExecutionException`	Ошибка времени выполнения MATLAB в функции или инструкции MATLAB.
`matlab::engine::TypeConversionException`	Результат функции MATLAB не может быть преобразован в указанный тип

Дополнительные сведения см. в разделе Исключения Catch в функции MEX

Связанные темы

Приложения C++ MEX

Документация

C++ MEX API

matlab::mex::Function

matlab::mex::ArgumentList

API механизма C++

matlab::engine::MATLABEngine::feval

Описание

Параметры

Возвращаемое значение

Исключения

matlab::engine::MATLABEngine::fevalAsync

Описание

Параметры

Возвращаемое значение

Исключения

matlab::engine::MATLABEngine::eval

Описание

Параметры

Исключения

matlab::engine::MATLABEngine::evalAsync

Описание

Параметры

Возвращаемое значение

Исключения

matlab::engine::MATLABEngine::getVariable

Описание

Параметры

Возвращаемое значение

Исключения

matlab::engine::MATLABEngine::getVariableAsync

Описание

Параметры

Возвращаемое значение

Исключения

matlab::engine::MATLABEngine::setVariable

Описание

Параметры

matlab::engine::MATLABEngine::setVariableAsync

Описание

Параметры

Исключения

matlab::engine::MATLABEngine::getProperty

Описание

Параметры

Возвращаемое значение

Исключения

matlab::engine::MATLABEngine::getPropertyAsync

Описание

Параметры

Возвращаемое значение

Исключения

matlab::engine::MATLABEngine::setProperty

Описание

Параметры

Исключения

matlab::engine::MATLABEngine::setPropertyAsync

Описание

Параметры

Исключения

Классы исключений

Связанные темы

Документация MATLAB

Поддержка

`matlab::mex::Function`

`matlab::mex::ArgumentList`

`matlab::engine::MATLABEngine::feval`

`matlab::engine::MATLABEngine::fevalAsync`

`matlab::engine::MATLABEngine::eval`

`matlab::engine::MATLABEngine::evalAsync`

`matlab::engine::MATLABEngine::getVariable`

`matlab::engine::MATLABEngine::getVariableAsync`

`matlab::engine::MATLABEngine::setVariable`

`matlab::engine::MATLABEngine::setVariableAsync`

`matlab::engine::MATLABEngine::getProperty`

`matlab::engine::MATLABEngine::getPropertyAsync`

`matlab::engine::MATLABEngine::setProperty`

`matlab::engine::MATLABEngine::setPropertyAsync`