struct::matrix(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

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

🌸 NAME 🌸

struct::matrix — create and manipulate matrix objects, bestie 💅

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

Okay so bestie, a matrix is literally a rectangular collection of cells, like a spreadsheet but make it Tcl. It's 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. 🌈

Note: The command properly recognizes and accounts for Asian double-wide characters. 🌏

In other words, the returned length is the number of terminal columns taken by the string, and not the number of characters. 💅

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

🫶 insert column — matrixName insert column column ?values?

Bestie, this one grows your matrix by a whole column, then — if you actually handed it some values — it does the set column thing (scroll down, it's there) on the brand-new column. No values? No problem, every new cell just gets the empty string. 💅

Where does it go, though? Right before the column at the index you gave it. So:

  • column less than or equal to zero → the new column slides in at the very beginning, ahead of the first column.
  • column set to end, or greater than/equal to the number of columns → it gets appended at the back, behind the last column.

And the old column that was sitting at your chosen index, plus every column with a higher index? They all shift up one index. Periodt. ✨

🌸 insert row — matrixName insert row row ?values?

Same energy, but rows this time. Extends the matrix by one row, then acts like set row on the new row if values came along for the ride. No values → new cells are the empty string, as always.

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

  • row less than or equal to zero → new row goes at the top of the matrix, before the first row.
  • row is end, or greater than/equal to the number of rows → appended at the bottom, behind the last row.

The old row at that index and all rows with higher indices shift one index upward. Slay. 🦋

Okay so this one bonds your matrix to an array variable. Every cell's contents live in the array too, and every change to the matrix gets propagated over there. 💖

The cell at (column,row) gets stored in the array under the key column,row. Pass -transpose and the key becomes row,column instead. You can link a matrix to more than one array, no judgement. 👑

Heads up: the link is bidirectional, meaning changes to the array get mirrored back into the matrix too. It's giving mutual, fr fr.

Returns a list with the names of every array variable the matrix got linked to through a link call. It's the receipts of who you're bonded with. ✨

📏 rowheight — matrixName rowheight row

Gives you the height of the specified row, measured in lines. That's the highest number of lines spanned by any single cell across all the cells in that row. Tallest queen wins. 👑

🌈 rows — matrixName rows

Returns the number of rows the matrix is currently managing. That's it. Short, sweet, iconic.

🔍 search — the whole family

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

Searches the entire matrix for cells matching pattern and returns a list with all the matches. Each item in that list is itself a list holding the column index and the row index of the matching cell — in that order, don't flip them. 🙈

Results are ordered by column first, then row, both ascending. Translation: 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 that comes after the search keyword. No option at all? It defaults to -exact. And if -nocase is in the mix, the search goes case-insensitive. 💅

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

Like search all, but restricted to the column you named. 🦋

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

Like search all, but restricted to the row you named. 🌸

matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl row_tl column_br row_br pattern

Like search all, but restricted to the rectangular area of the matrix you specified. Very choosey of you, love that. 🎀

📦 serialize — 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 that completely describes that matrix. Give it no rectangle and the whole matrix gets serialized. This is how you yeet matrix objects (or chunks of them) across arbitrary channels, do persistence, all that good stuff. It's also literally the basis for both the copy constructor and the assignment operator. 🔥

The result of this method has to be semantically identical across every implementation of the matrix interface — that's what makes copying matrix data between different implementations of the same interface possible. Teamwork, bestie. 🫶

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. These 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 serialized, in the form of a value like the one returned by get rect.

However! Empty cells to the right and bottom of the matrix can be left out of that value, because the size information in the serialization lets the receiver build a matrix with the proper size anyway, missing values and all. 🌈

# A possible serialization for the matrix structure
#
# | a b d g |
# | c e     |
# | f       |
#
# is
#
# 3 4 {{a b d g} {c e} {f}}

✍️ set cell — matrixName set cell column row value

Sets the value in the cell identified by the row and column index to the data in the third argument. Direct. To the point. Iconic. 💅

💖 set column — matrixName set column column values

Sets the values in the cells identified by the column index to the elements of the list you passed as the third argument. Each element gets assigned to one cell, with the first element going into the cell in row 0 and then upward. 🦋

  • Fewer values in the list than there are rows? The remaining rows get set to the empty string.
  • More values in the list than there are rows? The superfluous elements are just ignored, no cap.
The matrix is not extended by this operation. It stays exactly the size it was, bestie.

🎁 set rect — 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 aren't all the same length, the shorter sublists get filled with empty strings up to the length of the longest sublist. 🌸

And if the submatrix specified by the top-left cell plus the number of rows and columns in values extends beyond the matrix you're modifying? The over-extending parts of the values get ignored — essentially cut off. This subcommand expects its input in the format returned by get rect. 🎀

🌟 set row — 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 gets assigned to one cell, with the first element going into the cell in column 0 and then upward. ✨

  • Fewer values than there are columns? Remaining columns become the empty string.
  • More values than there are columns? Superfluous elements ignored.
Again: the matrix is not extended by this operation. 🙈

🔤 sort columns — 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 mean exactly the same thing as they do for lsort. No option specified? -increasing is assumed. 💜

🔡 sort rows — 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 mean the same as for lsort. No option specified? -increasing is assumed. 💜

🔄 swap columns — matrixName swap columns column_a column_b

Swaps the contents of the two specified columns. Trading places, main character energy. 👑

🔁 swap rows — matrixName swap rows row_a row_b

Swaps the contents of the two specified rows. Same deal, different axis. ✨

🌈 transpose — matrixName transpose

Transposes the contents of the matrix, i.e. swaps rows for columns and vice versa. The glow-up is real. 💅

Removes the link between the matrix and the specified arrayvariable, if there is one. Not every bond is forever, and that's okay. 🥲

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

Okay bestie, real talk: this doc? and the whole package it's describing? They will have bugs. Like, undoubtedly. That's just the deal with software, no cap. 😭

So if you find something broken, please report it! Slide into the category struct :: matrix of the Tcllib Trackers:

http://core.tcl.tk/tcllib/reportlist

And it's not just bugs, ok?? If you have ideas for enhancements for either the package and/or the documentation, report those too. We want the glow-up, we want the range. 🦋

🌸 A lil note on proposing code changes 🌸

When you're proposing code changes, please provide unified diffs — that means literally the output of:

diff -u

That's it. That's the format. Periodt. 💅

⚠️ Also, heads up: attachments are strongly preferred over inlined patches. Not a vibe thing, just the rules. To attach something, go to the Edit form of the ticket right after you create it, then use the left-most button in the secondary navigation bar. Iconic little path, I know. 🎀

🔑 KEYWORDS 🔑

  • matrix

🗂️ CATEGORY 🗂️

Data structures

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

And that's the whole page, bestie!! 🫶 This little masterpiece lives in tcllib, version 2.2, and the manual page is dated struct::matrix(n) — go forth and matrix responsibly, you absolute legend 💜✨🍓

📦 where this page comes from