NAME
::struct::matrix - Create and manipulate matrix objects
SYNOPSIS
package require struct ?1.0?
::struct::matrix matrixName
_________________________________________________________________
DESCRIPTION
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:
matrixName option ?arg arg ...?
Option and the args determine the exact behavior of the
command.
A matrix is a rectangular collection of cells, i.e. orga
nized 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 nei
ther 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:
matrixName add column ?values?
Extends the matrix by one column and then acts like
setcolumn (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 col
umn.
matrixName add row ?values?
Extends the matrix by one row and then acts like
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 col
umn. 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 represen
tation 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 row row
Deletes the specified row from the matrix and
shifts all row with higher indices one index down.
matrixName destroy
Destroys the matrix, including its storage space
and associated command.
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.
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.
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 ele
ment 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: col
umn_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 represent
ing a single row. The row with the smallest index
is the first element of the outer list. The ele
ments 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 ele
ment of this list.
matrixName insert column column ?values?
Extends the matrix by one column and then acts like
setcolumn (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 col
umn. If column has the value end, or if it is
greater than or equal to the number of columns in
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
setrow (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 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 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 col
umn 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
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 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 unlink arrayvar
Removes the link between the matrix and the speci
fied 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.
So
M getrect 0 0 4 4
returns
{{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
returns
{{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}}
KEYWORDS
matrix
Man(1) output converted with
man2html