


struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


______________________________________________________________________________

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




struct                        2.0.1                             1





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


       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 pat-
       tern

       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



struct                        2.0.1                             2





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


       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 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 ini-
       tialized 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                        2.0.1                             3





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


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



struct                        2.0.1                             4





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


              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



struct                        2.0.1                             5





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


              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 inter-
              nal  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 col-
              umn 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:  "col-
              umn_tl <= column_br" and "row_tl <= row_br". 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 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



struct                        2.0.1                             6





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


              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 bidi-
              rectional, 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 pat-
       tern
              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.





struct                        2.0.1                             7





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


       matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl
       row_tl  col- umn_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 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 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  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 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 ele-
              ment going into the cell in row 0 and then upward. If there  are



struct                        2.0.1                             8





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


              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  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 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 -decreas-
              ing have the same meaning as for lsort.  If no option is  speci-
              fied -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 arrayvari-
              able, if there is one.





struct                        2.0.1                             9





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


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  man-
       page  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://source-
       forge.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




struct                        2.0.1                            10





struct::matrix(n)      Tcl Data Structures      struct::matrix(n)


COPYRIGHT
       Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>























































struct                        2.0.1                            11


