matrix(3tcl)
NAME
struct::matrix - Create and manipulate matrix objects
SYNOPSIS
package require Tcl 8.2 package require struct::matrix ?2.0.3? ::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 ______________________________________________________________________________
DESCRIPTION
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:
matrixName option ?arg arg ...?
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:
matrixName = sourcematrix
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]
matrixName --> destmatrix
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]
matrixName add column ?values?
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.
matrixName add row ?values?
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.
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.
Note: The command recognizes ANSI color control sequences and
excludes them from the width of a line, as they are logically of
zero width.
matrixName delete column column
Deletes the specified column from the matrix and shifts all
columns with higher indices one index down.
matrixName delete columns n
Deletes n columns from the right of the matrix. The value of n
has to satisfy the constraint "0 < n < [matrixName columns]"
matrixName delete row row
Deletes the specified row from the matrix and shifts all row
with higher indices one index down.
matrixName delete rows n
Deletes n rows from the bottom of the matrix. The value of n has
to satisfy the constraint "0 < n < [matrixName rows]"
matrixName deserialize serialization
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.
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 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
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 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.
matrixName insert row row ?values?
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.
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 serialize ?column_tl row_tl column_br row_br?
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}}
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 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 get
rect.
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 transpose
Transposes the contents of the matrix, i.e. swaps rows for
columns and vice versa.
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 contains
the contents of the row above it, rotated by one cell to the right.
% M get rect 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 set rect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
% M get rect 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 Trackers [http://core.tcl.tk/tcllib/reportlist]. 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-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
