Матрицы могут реализовываться с помощью различных компонентов, поддерживающих интерфейс ImaMatrix. Для создания матриц служит интерфейс ImaMatrixFactory.
Функции интерфейса ImaMatrix


HRESULT Create ([in] maIndex sizes)
Функция создаёт матрицу заданной размерности и размеров. Если матрица уже содержит данные, то они уничтожаются. Тип значений матрицы определяется компонентом с этим интерфейсом.

Параметры:

sizes размерность и размеры матрицы

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

MA_NOERROR при отсутствии ошибок
MA_ERR_BAD_PARAM если sizes==NULL
MA_ERR_NOMEMORY если не удалось выделить память для хранения данных
MA_ERR_ACCESS если запрещена запись в матрицу

HRESULT CreateShared([in] maIndex sizes,
   [in,string] maString name,[in] int maxSize)
Функция позволяет создавать и использовать матрицы, размещенные в разделяемой памяти.
  1. Если maxSize≠0, то создается разделяемая область памяти размером maxSize с именем name и данные матрицы размещаются в ней. Созданная матрица имеет размеры sizes и доступна для чтения и записи.

  2. Если maxSize=0, то создается матрица с данными, уже хранящимися в разделяемой памяти с именем name. Параметр sizes в этом случае не используется, размер матрицы берется из разделяемой памяти. Созданная матрица доступна только для чтения.

Параметры:

sizes размерность и размеры матрицы
name Имя создаваемой матрицы. При создании новой матрицы оно должно быть уникальным в пределах ОС
maxSize размер памяти, резервируемой под данные. Надо брать с запасом, иначе возможны ошибки при выделении памяти в процессе работы.

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

MA_NOERROR при отсутствии ошибок
MA_ERR_BAD_PARAM если sizes==NULL
MA_ERR_NOMEMORY если не удалось выделить память для хранения данных
MA_ERR_REPNAME При создании новой матрицы, если матрица с именем name уже существует
MA_ERR_ACCESS если запрещена запись в матрицу
MA_ERR_BAD_CLSID если матрица с именем name имеет другой тип данных

HRESULT Resize([in] maIndex sizes);
Функция изменяет размер матрицы на заданные параметром sizes. Если матрица уже содержит данные, то они уничтожаются.

Параметры:

sizes новые размеры матрицы

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

MA_NOERROR при отсутствии ошибок
MA_ERR_BAD_PARAM если sizes==NULL
MA_ERR_ACCESS если запрещена запись в матрицу

HRESULT GetDim ([out,retval] int* dim)
Функция возвращает размерность матрицы.

Параметры:

dim Указатель на возвращаемое значение

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

MA_NOERROR всегда

HRESULT GetSize ([in] int dimno, [out,retval] int* size)
Функция возвращает размер матрицы по координате dimno. Координата может принимать значения от 0 до (dim-1), где dim — размерность матрицы, выдаваемая Dim.

Параметры:

dim Указатель на возвращаемое значение

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

MA_NOERROR всегда

HRESULT GetType([out,retval] maType* type)
Функция возвращает тип значений, хранящихся в матрице.

Параметры:

dim Указатель на возвращаемое значение

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

MA_NOERROR всегда

Вещественные и строковые матрицы могут содержать "пустые" значения, которые используются, например, для обозначения пропусков в данных. При инициализации матрицы все ее элементы устанавливаются "пустыми". При пустого считывании значения выдается константа, задаваемая функциями SetEmptyDoubleValue, SetEmptyStringValue и SetEmptyLongValue для считывания свойств AsDouble, AsString и AsLong соответственно. Целочисленные и булевские матрицы не поддерживают пустые значения и при создании инициализируются нулями или значением false.

HRESULT SetEmpty([in] maIndex index)
Функция записывает в матрицу пустое значение. Если матрица не поддерживает пустые значения, то вызов функции игнорируется.

Параметры:

index координата элемента матрицы

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

MA_NOERROR при отсутствии ошибок
MA_ERR_ACCESS если запись в матрицу запрещена

HRESULT IsEmpty([in] maIndex index)
Функция проверяет, будет ли значение ячейки матрицы пустым и возвращает MA_TRUE или MA_FALSE. Если матрица не поддерживает пустые значения, то функция возвращает MA_FALSE.

Параметры:

index координаты ячейки матрицы

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

MA_TRUE если ячейка матрицы пуста
MA_FALSE если ячейка матрицы непуста
MA_ERR_ACCESS если чтение из матрицы запрещено

HRESULT SetEmptyDoubleValue([in] double value)
HRESULT SetEmptyStringValue([in] maString value)
HRESULT SetEmptyLongValue([in] int value)
Функции устанавливают константы, которые играют роль "пустых" значений. Эти константы выдаются, если считываемое из матрицы значение пустое, и запись этих констант приводит к записи в матрицу пустого значения. Эти константы не являются глобальными и их можно изменять в процессе работы с матрицей, при этом пустые значения в матрице остаются пустыми.

Параметры:

value константа, которая возвращается вместо "пустых" значений

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

MA_NOERROR всегда

Замечание:

По умолчанию пустое числовое значение есть NaN, пустое строковое значение есть строка нулевой длины.
Если матрица не поддерживает пустые значения, то вызовы функции игнорируются.

HRESULT GetCell ([in] maIndex index, [out] ImaCell** pCell)
HRESULT SetCell ([in] maIndex index, [in] ImaCell* cell)
Функции чтения и записи ячейки матрицы. Если в матрице считываемый элемент пустой, то тип cell устанавливается в MA_EMPTY. При записи значения типа MA_EMPTY в матрицы записывается "пропуск".

Параметры:

index координаты ячейки матрицы
pCell указатель на возвращаемую ячейку
cell ячейка, из которой считывается значение

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

MA_NOERROR при отсутствии ошибок
MA_ERR_ACCESS если чтение (для GetCell) или запись (для SetCell) в матрицу запрещена
HRESULT GetAsDouble (
  [in] maIndex index, [out,retval] double* value)
HRESULT GetAsString (
  [in] maIndex index, [out,retval] maString* value)
HRESULT GetAsLong (
  [in] maIndex index, [out,retval] int* value)
Функции чтения значений из матрицы. При необходимости выполняется необходимое преобразование данных.

Параметры:

index координаты ячейки матрицы
value указатель на возвращаемое значение

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

MA_NOERROR при отсутствии ошибок
MA_ERR_ACCESS если чтение из матрицы запрещено

HRESULT SetAsDouble (
  [in] maIndex index, [in] double value)
HRESULT SetAsString (
  [in] maIndex index, [in,string] maString value)
HRESULT SetAsLong (
  [in] maIndex index, [in] int value)
Функции записи значения в матрицу. При необходимости выполняется необходимое преобразование данных.

Параметры:

index координаты ячейки матрицы
value записываемое значение

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

MA_NOERROR при отсутствии ошибок
MA_ERR_ACCESS если запись в матрицу запрещена

HRESULT Clear ()
Функция очищает матрицу, заполняя ее пустыми значениями или значениями по умолчанию. Размеры матрицы не меняются.

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

MA_NOERROR при отсутствии ошибок
MA_ERR_ACCESS если запись в матрицу запрещена

HRESULT CacheMatrix([in] byte cacheMode,[in] ImaMatrix* source)
Функция позволяет использовать данную матрицу как буфер для матрицы source или отключить буферизацию, если source==NULL. При включении буферизации все данные в матрице уничтожаются и размер матрицы становится равным размеру source. Параметр cacheMode выбирает режим буферизации:
MA_CACHE_READ
Будет создан буфер для чтения и содержимое матрицы source будет прочитано в данную матрицу.


MA_CACHE_WRITE
Будет создан буфер для записи. При вызове функции Commit матрица source будет очищена и затем в нее будет записано содержимое данной матрицы.


MA_CACHE_WRITE_THROUGH
Будет создан буфер для записи. При каждой операции записи в данную матрицу значение сразу же будет скопровано и в матрицу source. Вызывать функцию Commit не нужно.


MA_CACHE_WRITE_APPEND
Будет создан буфер для записи. При вызове функции Commit все непустые элементы данной матрицы будут записаны в матрицу source.
Эта функция будет полезна при написании библиотек алгоритмов в методах, которые в процессе вычислений записывают данные во входные матрицы или считывают их из выходных матриц.

Параметры:

cacheMode режим буферизации
source буферизируемая матрица

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

MA_NOERROR при отсутствии ошибок
MA_ERR_NOMEMORY если при изменении размеров матрицы не удалось выделить память.

HRESULT Commit()
Функция передает данные в/из буферизуемой матрицы. Конкретное действие этой функции зависит от режима буферизации:
MA_CACHE_READ
Содержимое буферизуемой матрицы будет повторно прочитано в данную матрицу.


MA_CACHE_WRITE
Матрица source будет очищена и затем в нее будет записано содержимое данной матрицы.


MA_CACHE_WRITE_APPEND
Все непустые элементы данной матрицы будут записаны в матрицу source. Содержимое ячеек буферизуемой матрицы, соответствующх пустым элементам данной матрицы, не изменяется.

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

MA_NOERROR всегда
Следующая группа функций предназначена для перебора всех непустых элементов матрицы и полезна прежде всего при работе с разреженными матрицами. Элементы матрицы просматриваются а порядке
(0,..,0,0)...(0,...,0,K)(0,...,1,0)...(0,...,M,K)...(N,...,M,K)
Для этого используется итератор с функциями "начать просмотр сначала" и "перейти к следующему элементу"
HRESULT CreateIter([out,retval] int* iterno)
Функция создает новый итератор. Для одной матрицы можно создать несколько итераторов.

Параметры:

iterno идентификатор созданного итератора

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

MA_NOERROR при отсутствии ошибок
MA_ERR_ACCESS если чтение из матрицы запрещено

HRESULT DeleteIter([in] int iterno)
Функция удаляет созданный ранее итератор.

Параметры:

iterno идентификатор ранее созданного итератора

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

MA_NOERROR всегда

HRESULT FirstIter([in] int iterno,[in,out] maIndex* index)
Функция устанавливает итератор iterno на начало просмотра и возвращает индекс первого непустого элемента.

Параметры:

iterno идентификатор итератора
index указатель на индекс первого непустого элемента матрицы

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

MA_NOERROR при отсутствии ошибок
MA_ERR_NOTFOUND если матрица не содержит непустых значений. В этом случае содержимое index не определено

HRESULT NextIter ([in] int iterno,[in,out] maIndex* index)
Функция устанавливает итератор iterno на следующий непустой элемент и возвращает его индекс.

Параметры:

iterno идентификатор итератора
index указатель на индекс очередного непустого элемента матрицы

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

MA_NOERROR при отсутствии ошибок
MA_ERR_NOTFOUND если просмотр матрицы закончен. В этом случае содержимое index не определено

HRESULT GetIter  ([in] int iterno,[in,out] maIndex* index)
Функция возвращает индекс текущего элемента итератора iterno. Если последний вызов FirstIter или NextIter вернул MA_NOERROR, возвращается тот же индекс, который вернул последний вызов FirstIter или NextIter с данным iterno; иначе результат функции неопределен.

Параметры:

iterno идентификатор итератора
index указатель на индекс непустого элемента матрицы

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

MA_NOERROR всегда