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

###### Функции интерфейса ImaMatrix

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

- Create ([in] maIndex sizes)
- CreateShared([in] maIndex sizes,[in,string] maString name,[in] int maxSize)
- Resize([in] maIndex sizes);
- GetDim ([out,retval] int* dim)
- GetSize ([in] int dimno, [out,retval] int* size)
- GetType([out,retval] maType* type)

Работа с пустыми значениями

- SetEmpty([in] maIndex index)
- IsEmpty([in] maIndex index)
- SetEmptyDoubleValue([in] double value)
- SetEmptyStringValue([in] maString value)
- SetEmptyLongValue([in] int value)

Чтение и запись

- GetCell ([in] maIndex index, [out] ImaCell** pCell)
- SetCell ([in] maIndex index, [in] ImaCell* cell)
- GetAsDouble ( [in] maIndex index, [out,retval] double* value)
- GetAsString ( [in] maIndex index, [out,retval] maString* value)
- GetAsLong ( [in] maIndex index, [out,retval] int* value)
- SetAsDouble ( [in] maIndex index, [in] double value)
- SetAsString ( [in] maIndex index, [in,string] maString value)
- SetAsLong ( [in] maIndex index, [in] int value)
- Clear ()

Буферизация

- CacheMatrix([in] byte cacheMode,[in] ImaMatrix* source)
- Commit()

Итераторы

- CreateIter([out,retval] int* iterno)
- DeleteIter([in] int iterno)
- FirstIter([in] int iterno,[in,out] maIndex* index)
- NextIter ([in] int iterno,[in,out] maIndex* index)
- GetIter ([in] int iterno,[in,out] maIndex* index)

    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 всегда