# matrix man page

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*arg*s 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.

## Category

Data structures

## Copyright

`Copyright (c) 2002-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>`