NAME¶
struct::matrix - Create and manipulate matrix objects
SYNOPSIS¶
package require
Tcl 8.2
package require
struct::matrix ?2.0.1?
::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.
- 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
getrect.
- 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 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 SF Trackers
[
http://sourceforge.net/tracker/?group_id=12883]. Please also report any ideas
for enhancements you may have for either package and/or documentation.
KEYWORDS¶
matrix
CATEGORY¶
Data structures
COPYRIGHT¶
Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>
