Manual Pages for UNIX Darwin command on man matrix

matrix(n) Tcl Data Structures matrix(n)

NAME

matrix - Create and manipulate matrix objects

SYNOPSIS

package require TTccll 88..22 package require ssttrruucctt ??22..00??

::::ssttrruucctt::::mmaattrriixx ?matrixName? ?==|::==|aass|ddeesseerriiaalliizzee source?

mmaattrriixxNNaammee option ?arg arg ...?

matrixName == sourcematrix

matrixName -->> destmatrix

matrixName aadddd ccoolluummnn ?values?

matrixName aadddd rrooww ?values?

matrixName aadddd ccoolluummnnss n

matrixName aadddd rroowwss n

matrixName cceellllss

matrixName cceellllssiizzee column row

matrixName ccoolluummnnss

matrixName ccoolluummnnwwiiddtthh column

matrixName ddeelleettee ccoolluummnn column

matrixName ddeelleettee ccoolluummnnss n

matrixName ddeelleettee rrooww row

matrixName ddeelleettee rroowwss n

matrixName ddeesseerriiaalliizzee serialization

matrixName ddeessttrrooyy

matrixName ffoorrmmaatt 22ssttrriinngg ?report?

matrixName ffoorrmmaatt 22cchhaann ??report? channel?

matrixName ggeett cceellll column row

matrixName ggeett ccoolluummnn column

matrixName ggeett rreecctt columntl rowtl columnbr rowbr

matrixName ggeett rrooww row

matrixName iinnsseerrtt ccoolluummnn column ?values?

matrixName iinnsseerrtt rrooww row ?values?

matrixName lliinnkk ?-transpose? arrayvar

matrixName lliinnkkss

matrixName rroowwhheeiigghhtt row

matrixName rroowwss

matrixName sseeaarrcchh ?-nocase? ?-exact|-glob|-regexp? aallll pattern

matrixName sseeaarrcchh ?-nocase? ?-exact|-glob|-regexp? ccoolluummnn column pat-

tern

matrixName sseeaarrcchh ?-nocase? ?-exact|-glob|-regexp? rrooww row pattern

matrixName sseeaarrcchh ?-nocase? ?-exact|-glob|-regexp? rreecctt columntl

rowtl columnbr rowbr pattern

matrixName sseerriiaalliizzee ?columntl rowtl columnbr rowbr?

matrixName sseett cceellll column row value

matrixName sseett ccoolluummnn column values

matrixName sseett rreecctt column row values

matrixName sseett rrooww row values

matrixName ssoorrtt ccoolluummnnss ?-iinnccrreeaassiinngg|-ddeeccrreeaassiinngg? row

matrixName ssoorrtt rroowwss ?-iinnccrreeaassiinngg|-ddeeccrreeaassiinngg? column

matrixName sswwaapp ccoolluummnnss columna columnb

matrixName sswwaapp rroowwss rowa rowb

matrixName ttrraannssppoossee

matrixName uunnlliinnkk 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 sec-

ond (right) number specifying the row the cell is in. These indices are

counted from 0 upward. The special non-numeric index eenndd refers to the

last row or column in the matrix, depending on the context. Indices of

the form eenndd-nnuummbbeerr 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:

::::ssttrruucctt::::mmaattrriixx ?matrixName? ?==|::==|aass|ddeesseerriiaalliizzee 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: mmaattrriixxNNaammee 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 ini-

tialized to it. For the operators ==, ::==, and aass the argument source is

interpreted as the name of another matrix object, and the assignment

operator == will be executed. For ddeesseerriiaalliizzee the source is a serialized

matrix object and ddeesseerriiaalliizzee 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 ddeesseerriiaalliizzee [sourcematrix sseerriiaalliizzee]

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 ddeesseerriiaalliizzee [matrixName sseerriiaalliizzee]

matrixName aadddd ccoolluummnn ?values?

Extends the matrix by one column and then acts like sseett ccoolluummnn

(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 aadddd rrooww ?values?

Extends the matrix by one row and then acts like sseett rrooww (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 aadddd ccoolluummnnss 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 aadddd rroowwss 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 cceellllss

Returns the number of cells currently managed by the matrix.

This is the product of rroowwss and ccoolluummnnss.

matrixName cceellllssiizzee column row

Returns the length of the string representation of the value currently contained in the addressed cell.

matrixName ccoolluummnnss

Returns the number of columns currently managed by the matrix.

matrixName ccoolluummnnwwiiddtthh 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 ddeelleettee ccoolluummnn column

Deletes the specified column from the matrix and shifts all col-

umns with higher indices one index down.

matrixName ddeelleettee ccoolluummnnss n

Deletes n columns from the right of the matrix. The value of n

has to satisfy the constraint "0 < n < [mmaattrriixxNNaammee ccoolluummnnss]"

matrixName ddeelleettee rrooww row

Deletes the specified row from the matrix and shifts all row

with higher indices one index down.

matrixName ddeelleettee rroowwss n

Deletes n rows from the bottom of the matrix. The value of n has

to satisfy the constraint "0 < n < [mmaattrriixxNNaammee rroowwss]"

matrixName ddeesseerriiaalliizzee serialization

This is the complement to sseerriiaalliizzee. 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 ddeessttrrooyy

Destroys the matrix, including its storage space and associated

command.

matrixName ffoorrmmaatt 22ssttrriinngg ?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 pprriinnttmmaattrriixx method. If no report is specified the system will use an internal report definition to format the

matrix.

matrixName ffoorrmmaatt 22cchhaann ??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 pprriinnttmmaattrriixx22cchhaannnneell

method. If no report is specified the system will use an inter-

nal report definition to format the matrix. If no channel is

specified the system will use ssttddoouutt.

matrixName ggeett cceellll column row

Returns the value currently contained in the cell identified by row and column index.

matrixName ggeett ccoolluummnn column

Returns a list containing the values from all cells in the col-

umn identified by the index. The contents of the cell in row 0 are stored as the first element of this list.

matrixName ggeett rreecctt columntl rowtl columnbr rowbr

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 columntl, rowtl and columnbr, rowbr

resp. Note that the following equations have to be true: "col-

umntl <= columnbr" and "rowtl <= rowbr". The result is orga-

nized as follows: The outer list is the list of rows, its ele-

ments are lists representing 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 ggeett rrooww 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 iinnsseerrtt ccoolluummnn column ?values?

Extends the matrix by one column and then acts like sseett ccoolluummnn

(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 eenndd, 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 col-

umns with higher indices are shifted one index upward.

matrixName iinnsseerrtt rrooww row ?values?

Extends the matrix by one row and then acts like sseett rrooww (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 eenndd, 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 lliinnkk ?-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 -ttrraannssppoossee 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 bidi-

rectional, i.e. changes to the array are mirrored in the matrix

too.

matrixName lliinnkkss

Returns a list containing the names of all array variables the

matrix was linked to through a call to method lliinnkk.

matrixName rroowwhheeiigghhtt 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 rroowwss

Returns the number of rows currently managed by the matrix.

matrixName sseeaarrcchh ?-nocase? ?-exact|-glob|-regexp? aallll 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 sseeaarrcchh keyword. If no option

is given it defaults to -eexxaacctt.

If the option -nnooccaassee is specified the search will be case-

insensitive.

matrixName sseeaarrcchh ?-nocase? ?-exact|-glob|-regexp? ccoolluummnn column pat-

tern Like sseeaarrcchh aallll, but the search is restricted to the specified column.

matrixName sseeaarrcchh ?-nocase? ?-exact|-glob|-regexp? rrooww row pattern

Like sseeaarrcchh aallll, but the search is restricted to the specified row.

matrixName sseeaarrcchh ?-nocase? ?-exact|-glob|-regexp? rreecctt columntl

rowtl columnbr rowbr pattern Like sseeaarrcchh aallll, but the search is restricted to the specified

rectangular area of the matrix.

matrixName sseerriiaalliizzee ?columntl rowtl columnbr rowbr?

This method serializes the sub-matrix spanned up by the rectan-

gle specification. In other words it returns a tcl value com-

pletely 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 ggeett rreecctt. 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 cre-

ation of a matrix with the proper size despite the missing val-

ues.

# 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 sseett cceellll column row value

Sets the value in the cell identified by row and column index to the data in the third argument.

matrixName sseett ccoolluummnn 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 ele-

ment 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 sseett rreecctt 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 ggeettrreecctt.

matrixName sseett rrooww 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 ele-

ment 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 ssoorrtt ccoolluummnnss ?-iinnccrreeaassiinngg|-ddeeccrreeaassiinngg? row

Sorts the columns in the matrix using the data in the specified

row as the key to sort by. The options -iinnccrreeaassiinngg and -ddeeccrreeaass-

iinngg have the same meaning as for llssoorrtt. If no option is speci-

fied -iinnccrreeaassiinngg is assumed.

matrixName ssoorrtt rroowwss ?-iinnccrreeaassiinngg|-ddeeccrreeaassiinngg? column

Sorts the rows in the matrix using the data in the specified

column as the key to sort by. The options -iinnccrreeaassiinngg and

-ddeeccrreeaassiinngg have the same meaning as for llssoorrtt. If no option is

specified -iinnccrreeaassiinngg is assumed.

matrixName sswwaapp ccoolluummnnss columna columnb

Swaps the contents of the two specified columns.

matrixName sswwaapp rroowwss rowa rowb

Swaps the contents of the two specified rows.

matrixName ttrraannssppoossee

Transposes the contents of the matrix, i.e. swaps rows for col-

umns and vice versa.

matrixName uunnlliinnkk arrayvar

Removes the link between the matrix and the specified arrayvari-

able, if there is one. EEXXAAMMPPLLEESS

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 man-

page for the package rreeppoorrtt 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

KKEEYYWWOORRDDSS