struct::matrix

ИМЯ

struct::matrix — создание объектов матриц и работа с ними

Содержание

• Содержание

• Краткое описание

• Описание

• Примеры

• Ошибки, идеи, отзывы

• Категория

• Авторские права

КРАТКОЕ ОПИСАНИЕ

package require Tcl 8.5 9
package require struct::matrix ?2.2?

::struct::matrix ?matrixName? ?=|:=|as|deserialize source?
matrixName option ?arg arg ...?
matrixName = sourcematrix
matrixName --> destmatrix
matrixName add column ?values?
matrixName add row ?values?
matrixName add columns n
matrixName add rows n
matrixName cells
matrixName cellsize column row
matrixName columns
matrixName columnwidth column
matrixName delete column column
matrixName delete columns n
matrixName delete row row
matrixName delete rows n
matrixName deserialize serialization
matrixName destroy
matrixName format 2string ?report?
matrixName format 2chan ??report? channel?
matrixName get cell column row
matrixName get column column
matrixName get rect column_tl row_tl column_br row_br
matrixName get row row
matrixName insert column column ?values?
matrixName insert row row ?values?
matrixName link ?-transpose? arrayvar
matrixName links
matrixName rowheight row
matrixName rows
matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pattern
matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl row_tl column_br row_br pattern
matrixName serialize ?column_tl row_tl column_br row_br?
matrixName set cell column row value
matrixName set column column values
matrixName set rect column row values
matrixName set row row values
matrixName sort columns ?-increasing|-decreasing? row
matrixName sort rows ?-increasing|-decreasing? column
matrixName swap columns column_a column_b
matrixName swap rows row_a row_b
matrixName transpose
matrixName unlink arrayvar

ОПИСАНИЕ

Матрица — это прямоугольный набор ячеек, то есть ячейки упорядочены по строкам и столбцам. Каждая ячейка содержит ровно одно значение произвольного вида. Ячейки матрицы адресуются парами целых чисел: первое число в паре (слева) задаёт столбец, а второе (справа) — строку, в которой находится ячейка. Индексы отсчитываются от 0. Специальный нечисловой индекс end обозначает последнюю строку или столбец матрицы в зависимости от контекста. Индексы вида end-number отсчитываются от конца строки или столбца, как и в стандартных списках Tcl. Попытка обратиться к несуществующей ячейке приводит к ошибке.

Создаваемые здесь матрицы изначально пусты, то есть не содержат ни строк, ни столбцов. Пользователь должен добавить строки и столбцы, необходимые его приложению. Особенность этой структуры — возможность экспортировать представление её содержимого в виде массива. Например, его можно использовать в tkTable для связи матрицы с отображением.

Основная команда пакета:

• ::struct::matrix ?matrixName? ?=|:=|as|deserialize source?

  Эта команда создаёт новый объект матрицы и связанную с ним глобальную команду Tcl с именем matrixName. Эту команду можно использовать для вызова различных операций над матрицей. Она имеет следующий общий вид:

  • matrixName option ?arg arg ...?

    Option и arg определяют точное поведение команды.

  Если matrixName не задано, пакет сгенерирует уникальное имя. Если задан source, новая матрица будет инициализирована его содержимым. Для операторов =, := и as аргумент source интерпретируется как имя другого объекта матрицы, после чего выполняется оператор присваивания =. Для deserialize аргумент source представляет собой сериализованный объект матрицы, и будет выполнена команда deserialize.

  Иными словами

  ::struct::matrix mymatrix = b
  

  эквивалентно

  ::struct::matrix mymatrix
  mymatrix = b
  

  а

  ::struct::matrix mymatrix deserialize $b
  

  эквивалентно

  ::struct::matrix mymatrix
  mymatrix deserialize $b
  

Для объектов матриц доступны следующие команды:

• matrixName = sourcematrix

  Это оператор присваивания для объектов матриц. Он копирует матрицу, содержащуюся в объекте sourcematrix, в данные матрицы matrixName. При выполнении этой операции прежнее содержимое matrixName удаляется.

  По сути, эта операция эквивалентна

  matrixName deserialize [sourcematrix serialize]

• matrixName --> destmatrix

  Это обратный оператор присваивания для объектов матриц. Он копирует матрицу, содержащуюся в объекте matrixName, в данные матрицы объекта destmatrix. При выполнении этой операции прежнее содержимое destmatrix удаляется.

  По сути, эта операция эквивалентна

  destmatrix deserialize [matrixName serialize]

• matrixName add column ?values?

  Добавляет к матрице один столбец и, если указаны values, применяет к новому столбцу команду set column (см. ниже). Если values не указаны, новые ячейки заполняются пустыми строками. Новый столбец добавляется сразу после последнего существующего столбца.

• matrixName add row ?values?

  Добавляет к матрице одну строку и, если указаны values, применяет к новой строке команду set row (см. ниже). Если values не указаны, новые ячейки заполняются пустыми строками. Новая строка добавляется сразу после последней существующей строки.

• matrixName add columns n

  Добавляет к матрице n столбцов. Новые ячейки заполняются пустыми строками. Новые столбцы добавляются сразу после последнего существующего столбца. Значение n, равное 0 или меньшее 0, недопустимо.

• matrixName add rows n

  Добавляет к матрице n строк. Новые ячейки заполняются пустыми строками. Новые строки добавляются сразу после последней существующей строки. Значение n, равное 0 или меньшее 0, недопустимо.

• matrixName cells

  Возвращает количество ячеек, которыми в данный момент управляет матрица. Это произведение значений rows и columns.

• matrixName cellsize column row

  Возвращает длину строкового представления значения, которое в данный момент содержится в указанной ячейке.

• matrixName columns

  Возвращает количество столбцов, которыми в данный момент управляет матрица.

• matrixName columnwidth column

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

  Примечание: Команда распознаёт управляющие последовательности ANSI для цвета и не учитывает их при вычислении ширины строки, поскольку логически они имеют нулевую ширину.

  Примечание: Команда корректно распознаёт и учитывает иероглифы, занимающие две позиции.

  Иными словами, возвращаемая длина — это количество колонок терминала, занимаемых строкой, а не количество символов.

• matrixName delete column column

  Удаляет указанный столбец из матрицы и сдвигает все столбцы с большими индексами на одну позицию влево.

• matrixName delete columns n

  Удаляет n столбцов справа матрицы. Значение n должно удовлетворять условию «0 < n < [matrixName columns]».

• matrixName delete row row

  Удаляет указанную строку из матрицы и сдвигает все строки с большими индексами на одну позицию вверх.

• matrixName delete rows n

  Удаляет n строк снизу матрицы. Значение n должно удовлетворять условию «0 < n < [matrixName rows]».

• matrixName deserialize serialization

  Это обратная операция к serialize. Она заменяет данные матрицы matrixName матрицей, описанной значением serialization. При выполнении этой операции прежнее содержимое matrixName удаляется.

• matrixName destroy

  Уничтожает матрицу, включая занимаемое ею пространство для хранения и связанную с ней команду.

• matrixName format 2string ?report?

  Форматирует матрицу с помощью указанного объекта отчёта и возвращает строку с результатом этой операции. Отчёт должен поддерживать метод printmatrix. Если report не указан, система использует для форматирования матрицы внутреннее определение отчёта.

• matrixName format 2chan ??report? channel?

  Форматирует матрицу с помощью указанного объекта отчёта и записывает строку с результатом этой операции в канал. Отчёт должен поддерживать метод printmatrix2channel. Если report не указан, система использует для форматирования матрицы внутреннее определение отчёта. Если channel не указан, система использует stdout.

• matrixName get cell column row

  Возвращает значение, содержащееся в данный момент в ячейке, заданной индексами строки и столбца.

• matrixName get column column

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

• matrixName get rect column_tl row_tl column_br row_br

  Возвращает список списков со значениями ячеек. В результат входят значения подматрицы, верхняя левая и нижняя правая ячейки которой заданы соответственно аргументами column_tl, row_tl и column_br, row_br. Обратите внимание, что должны выполняться следующие условия: «column_tl <= column_br» и «row_tl <= row_br». Результат организован следующим образом: внешний список содержит строки, а его элементы — списки, представляющие отдельные строки. Строка с наименьшим индексом является первым элементом внешнего списка. Элементы списков строк представляют выбранные значения ячеек. Ячейка с наименьшим индексом является первым элементом каждого списка строк.

• matrixName get row row

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

• matrixName insert column column ?values?

  Добавляет к матрице один столбец и, если указаны values, применяет к новому столбцу команду set column (см. ниже). Если values не указаны, новые ячейки заполняются пустыми строками. Новый столбец вставляется непосредственно перед столбцом с указанным индексом. Это означает, что если значение column меньше или равно нулю, новый столбец вставляется в начале матрицы, перед первым столбцом. Если значение column равно end или больше либо равно количеству столбцов матрицы, новый столбец добавляется в конец матрицы, после последнего столбца. Прежний столбец с выбранным индексом и все столбцы с большими индексами сдвигаются на одну позицию вправо.

• matrixName insert row row ?values?

  Добавляет к матрице одну строку и, если указаны values, применяет к новой строке команду set row (см. ниже). Если values не указаны, новые ячейки заполняются пустыми строками. Новая строка вставляется непосредственно перед строкой с указанным индексом. Это означает, что если значение row меньше или равно нулю, новая строка вставляется в начале матрицы, перед первой строкой. Если значение row равно end или больше либо равно количеству строк матрицы, новая строка добавляется в конец матрицы, после последней строки. Прежняя строка с этим индексом и все строки с большими индексами сдвигаются на одну позицию вниз.

• matrixName link ?-transpose? arrayvar

  Связывает матрицу с указанной переменной массива. Это означает, что содержимое всех ячеек матрицы также сохраняется в массиве, а все изменения матрицы передаются и ему. Содержимое ячейки (column,row) сохраняется в массиве под ключом column,row. Если указан параметр -transpose, вместо него используется ключ row,column. Матрицу можно связать с несколькими массивами. Обратите внимание, что связь двунаправленная: изменения массива также отражаются в матрице.

• matrixName links

  Возвращает список имён всех переменных массивов, с которыми матрица была связана вызовом метода link.

• matrixName rowheight row

  Возвращает высоту указанной строки в строках текста. Она равна наибольшему количеству строк, занимаемых ячейкой среди всех ячеек этой строки.

• matrixName rows

  Возвращает количество строк, которыми в данный момент управляет матрица.

• matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern

  Ищет во всей матрице ячейки, соответствующие шаблону pattern, и возвращает список всех совпадений. Каждый элемент этого списка сам является списком и содержит индекс столбца и индекс строки соответствующей ячейки именно в таком порядке. Результаты упорядочены сначала по столбцу, а затем по строке; в обоих случаях — по возрастанию. Это означает, что совпадения слева и сверху матрицы идут раньше совпадений справа и снизу.

  Тип шаблона (строка, шаблон glob или регулярное выражение) определяется параметром после ключевого слова search. Если параметр не задан, используется значение по умолчанию -exact.

  Если указан параметр -nocase, поиск выполняется без учёта регистра.

• matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pattern

  Аналогично search all, но поиск ограничен указанным столбцом.

• matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern

  Аналогично search all, но поиск ограничен указанной строкой.

• matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl row_tl column_br row_br pattern

  Аналогично search all, но поиск ограничен указанной прямоугольной областью матрицы.

• matrixName serialize ?column_tl row_tl column_br row_br?

  Этот метод сериализует подматрицу, охватываемую заданным прямоугольником. Иными словами, он возвращает Tcl-значение, полностью описывающее эту матрицу. Если прямоугольник не указан, сериализуется вся матрица. Это позволяет, например, передавать объекты матриц (или их части) по произвольным каналам, сохранять их и т. д. Этот метод также служит основой для конструктора копирования и оператора присваивания.

  Результат этого метода должен быть семантически идентичным во всех реализациях интерфейса матрицы. Это позволит копировать данные матриц между различными реализациями одного интерфейса.

  Результат представляет собой список ровно из трёх элементов.

  Первые два элемента списка задают количество строк и столбцов матрицы именно в таком порядке. Их значения — целые числа, большие или равные нулю.

  Последний элемент списка содержит значения сериализованных ячеек матрицы в виде значения, подобного возвращаемому командой get rect. Однако пустые ячейки справа и снизу матрицы можно не включать в это значение, поскольку информация о размере в сериализованных данных позволяет принимающей стороне создать матрицу нужного размера, несмотря на отсутствие этих значений.

  # A possible serialization for the matrix structure
  #
  # | a b d g |
  # | c e     |
  # | f       |
  #
  # is
  #
  # 3 4 {{a b d g} {c e} {f}}
  

• matrixName set cell column row value

  Устанавливает в ячейке, заданной индексами строки и столбца, значение, переданное третьим аргументом.

• matrixName set column column values

  Задаёт значения ячеек столбца с указанным индексом элементами списка, переданного третьим аргументом. Каждый элемент списка присваивается отдельной ячейке: первый элемент помещается в ячейку строки 0, а последующие — в ячейки следующих строк. Если элементов списка меньше, чем строк, оставшиеся строки заполняются пустыми строками. Если элементов списка больше, чем строк, лишние элементы игнорируются. Эта операция не расширяет матрицу.

• matrixName set rect column row values

  Принимает список списков со значениями ячеек и записывает их в подматрицу, верхняя левая ячейка которой задаётся двумя индексами. Если вложенные списки внешнего списка имеют разную длину, более короткие дополняются пустыми строками до длины самого длинного списка. Если подматрица, заданная верхней левой ячейкой и количеством строк и столбцов в values, выходит за границы изменяемой матрицы, выходящие за границы части значений игнорируются, то есть фактически отсекаются. Эта подкоманда ожидает данные в формате, возвращаемом командой get rect.

• matrixName set row row values

  Задаёт значения ячеек строки с указанным индексом элементами списка, переданного третьим аргументом. Каждый элемент списка присваивается отдельной ячейке: первый элемент помещается в ячейку столбца 0, а последующие — в ячейки следующих столбцов. Если элементов списка меньше, чем столбцов, оставшиеся столбцы заполняются пустыми строками. Если элементов списка больше, чем столбцов, лишние элементы игнорируются. Эта операция не расширяет матрицу.

• matrixName sort columns ?-increasing|-decreasing? row

  Сортирует столбцы матрицы, используя данные указанной row в качестве ключа сортировки. Параметры -increasing и -decreasing имеют тот же смысл, что и для lsort. Если параметр не указан, предполагается значение -increasing.

• matrixName sort rows ?-increasing|-decreasing? column

  Сортирует строки матрицы, используя данные указанного column в качестве ключа сортировки. Параметры -increasing и -decreasing имеют тот же смысл, что и для lsort. Если параметр не указан, предполагается значение -increasing.

• matrixName swap columns column_a column_b

  Меняет местами содержимое двух указанных столбцов.

• matrixName swap rows row_a row_b

  Меняет местами содержимое двух указанных строк.

• matrixName transpose

  Транспонирует содержимое матрицы, то есть меняет строки и столбцы местами.

• matrixName unlink arrayvar

  Удаляет связь между матрицей и указанной переменной массива, если такая связь существует.

ПРИМЕРЫ

В приведённых ниже примерах предполагается, что матрица M имеет размер 5x5, а в первой строке содержатся значения от 1 до 5, причём 1 находится в верхней левой ячейке. Каждая следующая строка содержит значения предыдущей строки, сдвинутые на одну ячейку вправо.

% M get rect 0 0 4 4
{{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}}

% M set rect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
% M get rect 0 0 4 4
{{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}}

Предполагается, что определения стилей из раздела примеров справочной страницы пакета report уже загружены в интерпретатор; далее приведён пример форматирования матрицы в виде табличного отчёта. Код заполнения матрицы данными не показан. Матрица содержит полезные данные.

% ::struct::matrix m
% # ... fill m with data, assume 5 columns
% ::report::report r 5 style captionedtable 1
% m format 2string r
+---+-------------------+-------+-------+--------+
|000|VERSIONS:          |2:8.4a3|1:8.4a3|1:8.4a3%|
+---+-------------------+-------+-------+--------+
|001|CATCH return ok    |7      |13     |53.85   |
|002|CATCH return error |68     |91     |74.73   |
|003|CATCH no catch used|7      |14     |50.00   |
|004|IF if true numeric |12     |33     |36.36   |
|005|IF elseif          |15     |47     |31.91   |
|   |true numeric       |       |       |        |
+---+-------------------+-------+-------+--------+
%
% # alternate way of doing the above
% r printmatrix m

Ошибки, идеи, отзывы

В этом документе и описываемом в нём пакете неизбежно могут содержаться ошибки и другие проблемы. Сообщайте о них в категории struct :: matrix в системе отслеживания ошибок Tcllib. Также сообщайте о любых идеях по улучшению пакета и/или документации.

Предлагая изменения кода, предоставляйте унифицированные различия, то есть вывод команды diff -u.

Обратите также внимание: настоятельно рекомендуется прикладывать вложения, а не вставлять патчи непосредственно в текст. Чтобы добавить вложение, сразу после создания заявки перейдите к форме Edit и нажмите самую левую кнопку на дополнительной панели навигации.

КАТЕГОРИЯ

Структуры данных

АВТОРСКИЕ ПРАВА

Авторские права © 2002-2013,2019,2022 Andreas Kupries