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







struct::matrix - Create and manipulate matrix objects








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


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












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:







  

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



  

  
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]
    

  

  

  
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]
    

  

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
Returns the number of cells currently managed by the matrix. This is the
      product of rows and columns.

  

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

  

  
Returns the number of columns currently managed by the matrix.

  

  
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.

  

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

  

  
Deletes n columns from the right of the matrix. The value of
      n has to satisfy the constraint "0 < n <
      [matrixName columns]"

  

  
Deletes the specified row from the matrix and shifts all row with higher
      indices one index down.

  

  
Deletes n rows from the bottom of the matrix. The value of n
      has to satisfy the constraint "0 < n <
      [matrixName rows]"

  

  
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.

  

  
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. If no report is specified the system
      will use an internal report definition to format the matrix.

  

  
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.

  

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

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
Returns a list containing the names of all array variables the matrix was
      linked to through a call to method link.

  

  
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.

  

  
Returns the number of rows currently managed by the matrix.

  

  
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.

  

  

  
Like search all, but the search is restricted to the specified
      column.

  

  
Like search all, but the search is restricted to the specified
    row.

  

  
Like search all, but the search is restricted to the specified
      rectangular area of the matrix.

  

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

    

  

  

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

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
Swaps the contents of the two specified columns.

  

  
Swaps the contents of the two specified rows.

  

  
Transposes the contents of the matrix, i.e. swaps rows for columns and
      vice versa.

  

  
Removes the link between the matrix and the specified arrayvariable, if
      there is one.










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









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://sourceforge.net/tracker/?group_id=12883]. Please also report any
    ideas for enhancements you may have for either package and/or
  documentation.








matrix








Data structures








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








  

    2.0.1
    struct