struct::matrix(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 struct::matrix 💖

okay bestie, so this is a page from the Tcl Data Structures manual, and it's about struct::matrix — a package that creates and manipulates matrix objects. it's giving very much "spreadsheet but make it a Tcl command", and honestly? iconic. ✨

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require struct::matrix ?2.2?

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

so like. a matrix is a rectangular collection of cells, okay? rows and columns, the whole vibe. every single cell holds exactly one value, and that value can be of any arbitrary form — no gatekeeping here, bestie, any form is welcome. 💅

the cells get addressed by pairs of integer numbers. the first (left) number in the pair says which column it is, and the second (right) number says which row it's in. these indices count from 0 upward, periodt.

the special non-numeric index end points at the last row or column in the matrix — which one depends on the context, iykyk. and indices shaped like end-number count from the end of the row or column, exactly like they do for standard Tcl lists. tryna access a cell that doesn't exist? boom, error. 😭

okay and here's a thing — the matrices here are created empty, like genuinely empty, they have neither rows nor columns. you, the user, have to add rows and columns as needed for your application. she's low maintenance but she does need you to show up. 🫶

a specialty of this structure (and honestly? the moment) is the ability to export an array-view onto its contents. tkTable can use that, for example, to link the matrix straight into the display. main character behavior honestly. 👑

the main command of the package is this one:

::struct::matrix ?matrixName? ?=|:=|as|deserialize source?

the command creates a new matrix object with an associated global Tcl command whose name is matrixName. that command can then be used to invoke various operations on the matrix. its general form is:

matrixName option ?arg arg ...?

Option and the args are what decide the exact behavior of the command. so yeah, they're kind of a big deal. ✨

if matrixName isn't specified, a unique name gets generated by the package itself. no stress, she'll name herself. 💅 if a source is specified, the new matrix gets initialized to it. for the operators =, :=, and as, the argument source is interpreted as the name of another matrix object, and the assignment operator = gets executed. for deserialize, the source is a serialized matrix object and deserialize gets executed.

in other words, this:

::struct::matrix mymatrix = b

is equivalent to this:

::struct::matrix mymatrix
mymatrix = b

and this:

::struct::matrix mymatrix deserialize $b

is equivalent to this:

::struct::matrix mymatrix
mymatrix deserialize $b

like. same energy. same result. 🦋

🎀 the commands, bestie 🎀

the following commands are possible for matrix objects:

matrixName = sourcematrix

this is the assignment operator for matrix objects. it copies the matrix inside the matrix object sourcematrix over the matrix data in matrixName. the old contents of matrixName get deleted by this operation — no mercy, no leftovers. 💀

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 inside the matrix object matrixName over the matrix data in the object destmatrix. the old contents of destmatrix get deleted by this operation too. yeah she's thorough. 🫶

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 values were supplied. without values, the new cells get set to the empty string. the new column gets 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 values were supplied. without values, the new cells get set to the empty string. the new row gets appended immediately behind the last existing row. ✨

matrixName add columns n

extends the matrix by n columns. the new cells get set to the empty string. the new columns get 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 get set to the empty string. the new rows get 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. math girlies rise. 🧮

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 — that's if they're 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, because logically they are of zero width. slay.
note: the command properly recognizes and accounts for Asian double-wide characters. we love an inclusive queen. 🌈

in other words, the returned length is the number of terminal columns taken by the string, and not the number of characters. important distinction, bestie, don't get it twisted. 💅

matrixName delete column column

deletes the specified column from the matrix and shifts all columns with higher indices one index down. gone, and everything else scoots over. 🦋

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. yes, the original says "all row", we're keeping it fr fr. 💜

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 get deleted by this operation. 💀

matrixName destroy

destroys the matrix, including its storage space and associated command. it's over. she's gone. rest in peace, matrix. 🕊️

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 uses 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 uses an internal report definition to format the matrix. if no channel is specified, the system uses 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 respectively. 📐

note that the following equations have to be true: "column_tl <= column_br" and "row_tl <= row_br".

the result is organized like this: the outer list is the list of rows, and 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. so basically, rows within rows, nested like a lil matryoshka doll. 🪆

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

okay bestie we're not done yet, there's more of this page coming — stay with me, the rest is on the way 💖

matrixName insert column column ?values?

Okay bestie, this one extends the matrix by one column and then basically acts like set column (scroll down, it's there) on that brand-new column if you handed over any values. No values? Then the fresh cells all get set to the empty string, no drama. 🫶

The new column gets inserted just before the column at the index you gave. So:

  • If column is less than or equal to zero → new column goes at the very beginning, before the first column. Main character entrance. 💅
  • If column is end, or greater than or equal to the number of columns in the matrix → new column gets appended behind the last column. Slay.

And the old column sitting at that chosen index, plus all columns with higher indices, get shifted one index upward. Everyone moves over, respectfully. ✨

matrixName insert row row ?values?

Same energy as above but for rows, bestie. Extends the matrix by one row and then acts like set row (yes, it's below, keep reading) on this new row if values were supplied. No values → new cells are the empty string. 🌸

The new row is inserted just before the row at your given index:

  • row less than or equal to zero → inserted at the beginning of the matrix, before the first row.
  • row equal to end, or greater than or equal to the number of rows → appended behind the last row.

The old row at that index and all rows with higher indices are shifted one index upward. Iconic behavior, fr fr. 👑

Links the matrix to the specified array variable. Translation: the contents of all cells in the matrix also live in that array, and every change to the matrix gets propagated there too. 🦋

The contents of the cell (column,row) is stored in the array using the key column,row. If you throw in the -transpose option, the key row,column gets used instead.

You can link the matrix to more than one array, no cap. And heads up — the link is bidirectional, meaning changes to the array are mirrored in the matrix too. It goes both ways, iykyk. 🔥

Returns a list containing the names of all array variables the matrix was linked to through a call to the method link. That's it. Little gossip report of who's connected. 💖

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. Tallest cell wins, basically. 📏

matrixName rows

Returns the number of rows currently managed by the matrix. Just a number, bestie. ⭐

matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern

Searches the whole matrix for cells matching pattern and returns a list with all the matches. Each item in that list is a list itself, containing 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. So matches to the left and the top of the matrix come before matches to the right and down. Left-to-right, top-to-bottom, like reading. 📖

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. Lowercase girlies and UPPERCASE girlies both get found. 💜

matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pattern

Like search all, but the search is restricted to the specified column. Narrow it down, queen. 🌈

matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern

Like search all, but the search is restricted to the specified row. Same vibe, different axis. ✨

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. Top-left and bottom-right corners, and the pattern. 🍓

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 gets 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. Big responsibility energy. 😭

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. No chaotic one-off serializations allowed. 🚫

The result is a list containing exactly three items:

  1. The first two elements of the list specify the number of rows and columns of the matrix, in that order. The values are integer numbers greater than or equal to zero.
  2. 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 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. One cell, one value, done. 💅

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

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. Format match is mandatory, bestie.

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

  • Less values in the list than there are columns → remaining columns get set to the empty string.
  • More values in the list than there are columns → superfluous elements are ignored.
Again: 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. Same rules, other direction. 🔄

matrixName swap columns column_a column_b

Swaps the contents of the two specified columns. Trading places, no notes. 💫

matrixName swap rows row_a row_b

Swaps the contents of the two specified rows. Same deal, row edition. 🌸

matrixName transpose

Transposes the contents of the matrix, i.e. swaps rows for columns and vice versa. Full glow-up, everything rotated. 🦋

Removes the link between the matrix and the specified arrayvariable, if there is one. If there isn't one... nothing happens, we simply move on. 💅

✨ 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 — bestie we KNOW it's not perfect

okay so real talk: this doc? and the whole package it's describing? yeah, they will contain bugs and other problems. no cap, that's just how software is. literally every page you've ever read has something lurking in it. it's giving "we're all just doing our best" energy 💀

so if you find something, pls report it in the category struct :: matrix of the Tcllib Trackers over at [http://core.tcl.tk/tcllib/reportlist] — that's the spot, that's where the magic happens.

and if you have ideas for enhancements ✨ for either the package and/or the documentation? yes pls, also report those. we want them. we're obsessed with them actually 🫶

⚠️ heads up for when you're proposing code changes: please provide unified diffs, i.e. the output of diff -u. that's the vibe. that's the format. anything else and we're gonna have a bad time 😭

also, one more lil note, and this one's important: attachments are strongly preferred over inlined patches. like, strongly. 💅

attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. that's the whole treasure map. go get it bestie 🗺️💖

🔑 KEYWORDS — the searchable vibes

  • matrix

🗂️ CATEGORY — where this page lives

  • Data structures

Copyright (c) 2002-2013,2019,2022 Andreas Kupries <andreas.kupries@gmail.com>

okay and that's a wrap on the whole page 🎀 huge thank you to Andreas Kupries for the copyright above, and to tcllib — this one's from the tcllib 2.2 era, filed under the struct::matrix(3tcl) manual, and honestly? she ate. go build something gorgeous with your matrices bestie, you've got this 💜🦋✨

📦 where this page comes from