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|deserializesource?
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:
matrixNameoption ?argarg...?
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
matrixNamedeserialize [sourcematrixserialize]
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
destmatrixdeserialize [matrixNameserialize]
matrixNameaddcolumn ?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 column.
matrixNameaddrow ?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
appended immediately behind the last existing row.
matrixNameaddcolumnsn
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.
matrixNameaddrowsn
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.
matrixNamecells
Returns the number of cells currently managed by the matrix. This is the product of rows and
columns.
matrixNamecellsizecolumnrow
Returns the length of the string representation of the value currently contained in the addressed
cell.
matrixNamecolumns
Returns the number of columns currently managed by the matrix.
matrixNamecolumnwidthcolumn
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.
Note: The command properly recognizes and accounts for Asian double-wide characters.
Inotherwords, the returned length is the number of terminal columns taken by the string, and not
the number of characters.
matrixNamedeletecolumncolumn
Deletes the specified column from the matrix and shifts all columns with higher indices one index
down.
matrixNamedeletecolumnsn
Deletes n columns from the right of the matrix. The value of n has to satisfy the constraint "0 <
n < [matrixNamecolumns]"
matrixNamedeleterowrow
Deletes the specified row from the matrix and shifts all row with higher indices one index down.
matrixNamedeleterowsn
Deletes n rows from the bottom of the matrix. The value of n has to satisfy the constraint "0 < n
< [matrixNamerows]"
matrixNamedeserializeserialization
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.
matrixNamedestroy
Destroys the matrix, including its storage space and associated command.
matrixNameformat2string ?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.
matrixNameformat2chan ??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.
matrixNamegetcellcolumnrow
Returns the value currently contained in the cell identified by row and column index.
matrixNamegetcolumncolumn
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.
matrixNamegetrectcolumn_tlrow_tlcolumn_brrow_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.
matrixNamegetrowrow
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.
matrixNameinsertcolumncolumn ?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 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.
matrixNameinsertrowrow ?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.
matrixNamelink ?-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.
matrixNamelinks
Returns a list containing the names of all array variables the matrix was linked to through a call
to method link.
matrixNamerowheightrow
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.
matrixNamerows
Returns the number of rows currently managed by the matrix.
matrixNamesearch ?-nocase? ?-exact|-glob|-regexp? allpattern
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.
matrixNamesearch ?-nocase? ?-exact|-glob|-regexp? columncolumnpattern
Like searchall, but the search is restricted to the specified column.
matrixNamesearch ?-nocase? ?-exact|-glob|-regexp? rowrowpattern
Like searchall, but the search is restricted to the specified row.
matrixNamesearch ?-nocase? ?-exact|-glob|-regexp? rectcolumn_tlrow_tlcolumn_brrow_brpattern
Like searchall, but the search is restricted to the specified rectangular area of the matrix.
matrixNameserialize ?column_tlrow_tlcolumn_brrow_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 getrect. 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}}
matrixNamesetcellcolumnrowvalue
Sets the value in the cell identified by row and column index to the data in the third argument.
matrixNamesetcolumncolumnvalues
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.
matrixNamesetrectcolumnrowvalues
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.
matrixNamesetrowrowvalues
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.
matrixNamesortcolumns ?-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.
matrixNamesortrows ?-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.
matrixNameswapcolumnscolumn_acolumn_b
Swaps the contents of the two specified columns.
matrixNameswaprowsrow_arow_b
Swaps the contents of the two specified rows.
matrixNametranspose
Transposes the contents of the matrix, i.e. swaps rows for columns and vice versa.
matrixNameunlinkarrayvar
Removes the link between the matrix and the specified arrayvariable, if there is one.
Install Now
SVG Icons
PNG Icons
