matrix1 man page on Ubuntu

Man page or keyword search:  
man Server   6591 pages
apropos Keyword Search (all sections)
Output format
Ubuntu logo
[printable version]

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

       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 col‐
	      umns 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 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.
	      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 col‐
	      umns 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.

	      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 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 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
	      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%|
	   +---+-------------------+-------+-------+--------+
	   |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		 struct::matrix1(3tcl)
[top]

List of man pages available for Ubuntu

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net