Provided by: tcllib_1.19-dfsg-2_all 
NAME
struct::matrix - Create and manipulate matrix objects
SYNOPSIS
package require Tcl 8.2
package require struct::matrix ?2.0.3?
::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
_________________________________________________________________________________________________
DESCRIPTION
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 main command of the package is:
::struct::matrix ?matrixName? ?=|:=|as|deserialize source?
The 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:
matrixName option ?arg arg ...?
Option and the args determine the exact behavior of the command.
If matrixName is not specified a unique name will be generated by the package itself. If a
source is specified the new matrix will be initialized to it. For the operators =, :=, and
as the argument source is interpreted as the name of another matrix object, and the
assignment operator = will be executed. For deserialize the source is a serialized matrix
object and deserialize will be executed.
In other words
::struct::matrix mymatrix = b
is equivalent to
::struct::matrix mymatrix
mymatrix = b
and
::struct::matrix mymatrix deserialize $b
is equivalent to
::struct::matrix mymatrix
mymatrix deserialize $b
The following commands are possible for matrix objects:
matrixName = sourcematrix
This is the assignment operator for matrix objects. It copies the matrix contained
in the matrix object sourcematrix over the matrix data in matrixName. The old
contents of matrixName are deleted by this operation.
This operation is in effect equivalent to
matrixName deserialize [sourcematrix serialize]
matrixName --> destmatrix
This is the reverse assignment operator for matrix objects. It copies the matrix
contained in the matrix object matrixName over the matrix data in the object
destmatrix. The old contents of destmatrix are deleted by this operation.
This operation is in effect equivalent to
destmatrix deserialize [matrixName serialize]
matrixName add column ?values?
Extends the matrix by one column and then acts like set column (see below) on this
new column if there were values supplied. Without values the new cells will be set
to the empty string. The new column is appended immediately behind the last
existing column.
matrixName add row ?values?
Extends the matrix by one row and then acts like set row (see below) on this new
row if there were values supplied. Without values the new cells will be set to the
empty string. The new row is appended immediately behind the last existing row.
matrixName add columns n
Extends the matrix by n columns. The new cells will be set to the empty string. The
new columns are appended immediately behind the last existing column. A value of n
equal to or smaller than 0 is not allowed.
matrixName add rows n
Extends the matrix by n rows. The new cells will be set to the empty string. The
new rows are appended immediately behind the last existing row. A value of n equal
to or smaller than 0 is not allowed.
matrixName cells
Returns the number of cells currently managed by the matrix. This is the product of
rows and columns.
matrixName cellsize column row
Returns the length of the string representation of the value currently contained in
the addressed cell.
matrixName columns
Returns the number of columns currently managed by the matrix.
matrixName columnwidth column
Returns the length of the longest string representation of all the values currently
contained in the cells of the addressed column if these are all spanning only one
line. For cell values spanning multiple lines the length of their longest line goes
into the computation.
Note: The command recognizes ANSI color control sequences and excludes them from
the width of a line, as they are logically of zero width.
matrixName delete column column
Deletes the specified column from the matrix and shifts all columns with higher
indices one index down.
matrixName delete columns n
Deletes n columns from the right of the matrix. The value of n has to satisfy the
constraint "0 < n < [matrixName columns]"
matrixName delete row row
Deletes the specified row from the matrix and shifts all row with higher indices
one index down.
matrixName delete rows n
Deletes n rows from the bottom of the matrix. The value of n has to satisfy the
constraint "0 < n < [matrixName rows]"
matrixName deserialize serialization
This is the complement to serialize. It replaces matrix data in matrixName with the
matrix described by the serialization value. The old contents of matrixName are
deleted by this operation.
matrixName destroy
Destroys the matrix, including its storage space and associated command.
matrixName format 2string ?report?
Formats the matrix using the specified report object and returns the string
containing the result of this operation. The report has to support the printmatrix
method. If no report is specified the system will use an internal report definition
to format the matrix.
matrixName format 2chan ??report? channel?
Formats the matrix using the specified report object and writes the string
containing the result of this operation into the channel. The report has to support
the printmatrix2channel method. If no report is specified the system will use an
internal report definition to format the matrix. If no channel is specified the
system will use stdout.
matrixName get cell column row
Returns the value currently contained in the cell identified by row and column
index.
matrixName get column column
Returns a list containing the values from all cells in the column identified by the
index. The contents of the cell in row 0 are stored as the first element of this
list.
matrixName get rect column_tl row_tl column_br row_br
Returns a list of lists of cell values. The values stored in the result come from
the sub-matrix whose top-left and bottom-right cells are specified by column_tl,
row_tl and column_br, row_br resp. Note that the following equations have to be
true: "column_tl <= column_br" and "row_tl <= row_br". The result is organized as
follows: The outer list is the list of rows, its elements are lists representing a
single row. The row with the smallest index is the first element of the outer list.
The elements of the row lists represent the selected cell values. The cell with the
smallest index is the first element in each row list.
matrixName get row row
Returns a list containing the values from all cells in the row identified by the
index. The contents of the cell in column 0 are stored as the first element of this
list.
matrixName insert column column ?values?
Extends the matrix by one column and then acts like set column (see below) on this
new column if there were values supplied. Without values the new cells will be set
to the empty string. The new column is inserted just before the column specified by
the given index. This means, if column is less than or equal to zero, then the new
column is inserted at the beginning of the matrix, before the first column. If
column has the value end, or if it is greater than or equal to the number of
columns in the matrix, then the new column is appended to the matrix, behind the
last column. The old column at the chosen index and all columns with higher indices
are shifted one index upward.
matrixName insert row row ?values?
Extends the matrix by one row and then acts like set row (see below) on this new
row if there were values supplied. Without values the new cells will be set to the
empty string. The new row is inserted just before the row specified by the given
index. This means, if row is less than or equal to zero, then the new row is
inserted at the beginning of the matrix, before the first row. If row has the value
end, or if it is greater than or equal to the number of rows in the matrix, then
the new row is appended to the matrix, behind the last row. The old row at that
index and all rows with higher indices are shifted one index upward.
matrixName link ?-transpose? arrayvar
Links the matrix to the specified array variable. This means that the contents of
all cells in the matrix is stored in the array too, with all changes to the matrix
propagated there too. The contents of the cell (column,row) is stored in the array
using the key column,row. If the option -transpose is specified the key row,column
will be used instead. It is possible to link the matrix to more than one array.
Note that the link is bidirectional, i.e. changes to the array are mirrored in the
matrix too.
matrixName links
Returns a list containing the names of all array variables the matrix was linked to
through a call to method link.
matrixName rowheight row
Returns the height of the specified row in lines. This is the highest number of
lines spanned by a cell over all cells in the row.
matrixName rows
Returns the number of rows currently managed by the matrix.
matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
Searches the whole matrix for cells matching the pattern and returns a list with
all matches. Each item in the aforementioned list is a list itself and contains the
column and row index of the matching cell, in this order. The results are ordered
by column first and row second, both times in ascending order. This means that
matches to the left and the top of the matrix come before matches to the right and
down.
The type of the pattern (string, glob, regular expression) is determined by the
option after the search keyword. If no option is given it defaults to -exact.
If the option -nocase is specified the search will be case-insensitive.
matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pattern
Like search all, but the search is restricted to the specified column.
matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
Like search all, but the search is restricted to the specified row.
matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl row_tl column_br row_br
pattern
Like search all, but the search is restricted to the specified rectangular area of
the matrix.
matrixName serialize ?column_tl row_tl column_br row_br?
This method serializes the sub-matrix spanned up by the rectangle specification. In
other words it returns a tcl value completely describing that matrix. If no
rectangle is specified the whole matrix will be serialized. This allows, for
example, the transfer of matrix objects (or parts thereof) over arbitrary channels,
persistence, etc. This method is also the basis for both the copy constructor and
the assignment operator.
The result of this method has to be semantically identical over all implementations
of the matrix interface. This is what will enable us to copy matrix data between
different implementations of the same interface.
The result is a list containing exactly three items.
The first two elements of the list specify the number of rows and columns of the
matrix, in that order. The values integer numbers greater than or equal to zero.
The last element of the list contains the values of the matrix cells we have
serialized, in the form of a value like it is returned by the get rect. However
empty cells to the right and bottom of the matrix can be left out of that value as
the size information in the serialization allows the receiver the creation of a
matrix with the proper size despite the missing values.
# 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
Sets the value in the cell identified by row and column index to the data in the
third argument.
matrixName set column column values
Sets the values in the cells identified by the column index to the elements of the
list provided as the third argument. Each element of the list is assigned to one
cell, with the first element going into the cell in row 0 and then upward. If there
are less values in the list than there are rows the remaining rows are set to the
empty string. If there are more values in the list than there are rows the
superfluous elements are ignored. The matrix is not extended by this operation.
matrixName set rect column row values
Takes a list of lists of cell values and writes them into the submatrix whose top-
left cell is specified by the two indices. If the sublists of the outerlist are not
of equal length the shorter sublists will be filled with empty strings to the
length of the longest sublist. If the submatrix specified by the top-left cell and
the number of rows and columns in the values extends beyond the matrix we are
modifying the over-extending parts of the values are ignored, i.e. essentially cut
off. This subcommand expects its input in the format as returned by get rect.
matrixName set row row values
Sets the values in the cells identified by the row index to the elements of the
list provided as the third argument. Each element of the list is assigned to one
cell, with the first element going into the cell in column 0 and then upward. If
there are less values in the list than there are columns the remaining columns are
set to the empty string. If there are more values in the list than there are
columns the superfluous elements are ignored. The matrix is not extended by this
operation.
matrixName sort columns ?-increasing|-decreasing? row
Sorts the columns in the matrix using the data in the specified row as the key to
sort by. The options -increasing and -decreasing have the same meaning as for
lsort. If no option is specified -increasing is assumed.
matrixName sort rows ?-increasing|-decreasing? column
Sorts the rows in the matrix using the data in the specified column as the key to
sort by. The options -increasing and -decreasing have the same meaning as for
lsort. If no option is specified -increasing is assumed.
matrixName swap columns column_a column_b
Swaps the contents of the two specified columns.
matrixName swap rows row_a row_b
Swaps the contents of the two specified rows.
matrixName transpose
Transposes the contents of the matrix, i.e. swaps rows for columns and vice versa.
matrixName unlink arrayvar
Removes the link between the matrix and the specified arrayvariable, if there is
one.
EXAMPLES
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 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}}
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
[http://core.tcl.tk/tcllib/reportlist]. 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.
KEYWORDS
matrix
CATEGORY
Data structures
COPYRIGHT
Copyright (c) 2002-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>