


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


______________________________________________________________________________

NAME
       struct::matrix v1 - Create and manipulate matrix objects

SYNOPSIS
       package require Tcl  8.2

       package require struct::matrix  ?1.2.1?

       matrixName option ?arg arg ...?

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

       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




struct                        1.2.1                             1





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


       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 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 unlink arrayvar

_________________________________________________________________

DESCRIPTION
       The  ::struct::matrix command creates a new matrix object with an asso-
       ciated global Tcl command whose name is matrixName.  This  command  may
       be used to invoke various operations on the matrix.  It has the follow-
       ing 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. 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 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.



struct                        1.2.1                             2





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


       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 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
              column.

       matrixName add 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 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.

       matrixName delete column column
              Deletes  the  specified  column  from  the matrix and shifts all
              columns with higher indices one index down.



struct                        1.2.1                             3





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


       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.

       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 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  setcolumn
              (see  below)  on  this new column if there were values supplied.
              Without values the new cells will be set to  the  empty  string.



struct                        1.2.1                             4





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


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




struct                        1.2.1                             5





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


              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.

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



struct                        1.2.1                             6





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


              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 unlink arrayvar
              Removes the link between the matrix and the specified arrayvari-
              able, 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 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%|



struct                        1.2.1                             7





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


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

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





























struct                        1.2.1                             8


