NAME

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


SYNOPSIS

       package require struct ?1.0?

       ::struct::matrix matrixName

_________________________________________________________________


DESCRIPTION

       The  ::struct::matrix  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.

       A matrix is a rectangular collection of cells, i.e.  orga­
       nized  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 nei­
       ther 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  col­
              umn.

       matrixName add row ?values?
              Extends  the  matrix  by one row and then acts like

              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 col­
              umn. 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 represen­
              tation 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 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.

              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.

       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.

       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  ele­
              ment 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  organized as follows: The outer list is
              the list of rows, its elements are lists represent­
              ing  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 ele­
              ment 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. 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 col­
              umn. If column has the  value  end,  or  if  it  is
              greater  than  or equal to the number of columns in

              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 bidirectional, i.e.
              changes to the array are  mirrored  in  the  matrix
              too.

       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 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 col­
              umn 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

              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  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 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  speci­
              fied 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.

       So

              M getrect 0 0 4 4

       returns

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

       returns

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


KEYWORDS

       matrix


Man(1) output converted with man2html