struct::matrix1(3tcl)						Tcl Data Structures					     struct::matrix1(3tcl)

__________________________________________________________________________________________________________________________________________________

NAME

       struct::matrix1 - Create and manipulate matrix objects (version 1)

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

       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 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 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. 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 exam-
       ple, 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 com-
	      putation.

       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.

       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 internal report  defini-
	      tion 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 column 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: "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.

       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. 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 bidirectional, 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 pattern
	      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 column_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 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.

       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 long-
	      est 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 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 -decreasing
	      have the same meaning as for lsort.  If no option is specified -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 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 con-
       tains 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

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://sourceforge.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						     struct::matrix1(3tcl)