Tcl Library Source Code

Bounty program for improvements to Tcl and certain Tcl packages.

[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]


struct::matrix_v1 - Create and manipulate matrix objects

Table Of Contents


package require Tcl 8.2
package require struct::matrix ?1.2.2?

matrixName option ?arg arg ...?
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 row row
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 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 unlink arrayvar


The ::struct::matrix command creates a new matrix object with an associated global Tcl command whose name is matrixName. This command may be used to invoke various operations on the matrix. It has the following general form:

A matrix is a rectangular collection of cells, i.e. organized in rows and columns. Each cell contains exactly one value of arbitrary form. The cells in the matrix are addressed by pairs of integer numbers, with the first (left) number in the pair specifying the column and the second (right) number specifying the row the cell is in. These indices are counted from 0 upward. The special non-numeric index end refers to the last row or column in the matrix, depending on the context. Indices of the form end-number are counted from the end of the row or column, like they are for standard Tcl lists. Trying to access non-existing cells causes an error.

The matrices here are created empty, i.e. they have neither rows nor columns. The user then has to add rows and columns as needed by his application. A specialty of this structure is the ability to export an array-view onto its contents. Such can be used by tkTable, for example, to link the matrix into the display.

The following commands are possible for matrix objects:


The examples below assume a 5x5 matrix M with the first row containing the values 1 to 5, with 1 in the top-left cell. Each other row contains the contents of the row above it, rotated by one cell to the right.

% M getrect 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 setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
% M getrect 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}}

Assuming that the style definitions in the example section of the manpage for the package report are loaded into the interpreter now an example which formats a matrix into a tabular report. The code filling the matrix with data is not shown. contains useful data.

% ::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

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category struct :: matrix of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.




Data structures


Copyright © 2002,2019 Andreas Kupries