1struct::matrix(n) Tcl Data Structures struct::matrix(n)
2______________________________________________________________________________
6
8 struct::matrix - Create and manipulate matrix objects
9
11 package require Tcl 8.2
12 package require struct::matrix ?2.0.3?
14 ::struct::matrix ?matrixName? ?=|:=|as|deserialize source?
16 matrixName option ?arg arg ...?
18 matrixName = sourcematrix
20 matrixName --> destmatrix
22 matrixName add column ?values?
24 matrixName add row ?values?
26 matrixName add columns n
28 matrixName add rows n
30 matrixName cells
32 matrixName cellsize column row
34 matrixName columns
36 matrixName columnwidth column
38 matrixName delete column column
40 matrixName delete columns n
42 matrixName delete row row
44 matrixName delete rows n
46 matrixName deserialize serialization
48 matrixName destroy
50 matrixName format 2string ?report?
52 matrixName format 2chan ??report? channel?
54 matrixName get cell column row
56 matrixName get column column
58 matrixName get rect column_tl row_tl column_br row_br
60 matrixName get row row
62 matrixName insert column column ?values?
64 matrixName insert row row ?values?
66 matrixName link ?-transpose? arrayvar
68 matrixName links
70 matrixName rowheight row
72 matrixName rows
74 matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
76 matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pat‐
78 tern
79 matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
81 matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl
83 row_tl column_br row_br pattern
84 matrixName serialize ?column_tl row_tl column_br row_br?
86 matrixName set cell column row value
88 matrixName set column column values
90 matrixName set rect column row values
92 matrixName set row row values
94 matrixName sort columns ?-increasing|-decreasing? row
96 matrixName sort rows ?-increasing|-decreasing? column
98 matrixName swap columns column_a column_b
100 matrixName swap rows row_a row_b
102 matrixName transpose
104 matrixName unlink arrayvar
106______________________________________________________________________________
108
110 A matrix is a rectangular collection of cells, i.e. organized in rows
111 and columns. Each cell contains exactly one value of arbitrary form.
112 The cells in the matrix are addressed by pairs of integer numbers, with
113 the first (left) number in the pair specifying the column and the sec‐
114 ond (right) number specifying the row the cell is in. These indices are
115 counted from 0 upward. The special non-numeric index end refers to the
116 last row or column in the matrix, depending on the context. Indices of
117 the form end-number are counted from the end of the row or column, like
118 they are for standard Tcl lists. Trying to access non-existing cells
119 causes an error.
120 The matrices here are created empty, i.e. they have neither rows nor
122 columns. The user then has to add rows and columns as needed by his
123 application. A specialty of this structure is the ability to export an
124 array-view onto its contents. Such can be used by tkTable, for example,
125 to link the matrix into the display.
126 The main command of the package is:
128 ::struct::matrix ?matrixName? ?=|:=|as|deserialize source?
130 The command creates a new matrix object with an associated
131 global Tcl command whose name is matrixName. This command may
132 be used to invoke various operations on the matrix. It has the
133 following general form:
134 matrixName option ?arg arg ...?
136 Option and the args determine the exact behavior of the
137 command.
138 If matrixName is not specified a unique name will be generated by the
140 package itself. If a source is specified the new matrix will be ini‐
141 tialized to it. For the operators =, :=, and as the argument source is
142 interpreted as the name of another matrix object, and the assignment
143 operator = will be executed. For deserialize the source is a serialized
144 matrix object and deserialize will be executed.
145 In other words
147 ::struct::matrix mymatrix = b
151 is equivalent to
154 ::struct::matrix mymatrix
158 mymatrix = b
159 and
162 ::struct::matrix mymatrix deserialize $b
166 is equivalent to
169 ::struct::matrix mymatrix
173 mymatrix deserialize $b
174 The following commands are possible for matrix objects:
177 matrixName = sourcematrix
179 This is the assignment operator for matrix objects. It copies
180 the matrix contained in the matrix object sourcematrix over the
181 matrix data in matrixName. The old contents of matrixName are
182 deleted by this operation.
183 This operation is in effect equivalent to
185 matrixName deserialize [sourcematrix serialize]
189 matrixName --> destmatrix
192 This is the reverse assignment operator for matrix objects. It
193 copies the matrix contained in the matrix object matrixName over
194 the matrix data in the object destmatrix. The old contents of
195 destmatrix are deleted by this operation.
196 This operation is in effect equivalent to
198 destmatrix deserialize [matrixName serialize]
202 matrixName add column ?values?
205 Extends the matrix by one column and then acts like set column
206 (see below) on this new column if there were values supplied.
207 Without values the new cells will be set to the empty string.
208 The new column is appended immediately behind the last existing
209 column.
210 matrixName add row ?values?
212 Extends the matrix by one row and then acts like set row (see
213 below) on this new row if there were values supplied. Without
214 values the new cells will be set to the empty string. The new
215 row is appended immediately behind the last existing row.
216 matrixName add columns n
218 Extends the matrix by n columns. The new cells will be set to
219 the empty string. The new columns are appended immediately
220 behind the last existing column. A value of n equal to or
221 smaller than 0 is not allowed.
222 matrixName add rows n
224 Extends the matrix by n rows. The new cells will be set to the
225 empty string. The new rows are appended immediately behind the
226 last existing row. A value of n equal to or smaller than 0 is
227 not allowed.
228 matrixName cells
230 Returns the number of cells currently managed by the matrix.
231 This is the product of rows and columns.
232 matrixName cellsize column row
234 Returns the length of the string representation of the value
235 currently contained in the addressed cell.
236 matrixName columns
238 Returns the number of columns currently managed by the matrix.
239 matrixName columnwidth column
241 Returns the length of the longest string representation of all
242 the values currently contained in the cells of the addressed
243 column if these are all spanning only one line. For cell values
244 spanning multiple lines the length of their longest line goes
245 into the computation.
246 Note: The command recognizes ANSI color control sequences and
248 excludes them from the width of a line, as they are logically of
249 zero width.
250 matrixName delete column column
252 Deletes the specified column from the matrix and shifts all col‐
253 umns with higher indices one index down.
254 matrixName delete columns n
256 Deletes n columns from the right of the matrix. The value of n
257 has to satisfy the constraint "0 < n < [matrixName columns]"
258 matrixName delete row row
260 Deletes the specified row from the matrix and shifts all row
261 with higher indices one index down.
262 matrixName delete rows n
264 Deletes n rows from the bottom of the matrix. The value of n has
265 to satisfy the constraint "0 < n < [matrixName rows]"
266 matrixName deserialize serialization
268 This is the complement to serialize. It replaces matrix data in
269 matrixName with the matrix described by the serialization value.
270 The old contents of matrixName are deleted by this operation.
271 matrixName destroy
273 Destroys the matrix, including its storage space and associated
274 command.
275 matrixName format 2string ?report?
277 Formats the matrix using the specified report object and returns
278 the string containing the result of this operation. The report
279 has to support the printmatrix method. If no report is specified
280 the system will use an internal report definition to format the
281 matrix.
282 matrixName format 2chan ??report? channel?
284 Formats the matrix using the specified report object and writes
285 the string containing the result of this operation into the
286 channel. The report has to support the printmatrix2channel
287 method. If no report is specified the system will use an inter‐
288 nal report definition to format the matrix. If no channel is
289 specified the system will use stdout.
290 matrixName get cell column row
292 Returns the value currently contained in the cell identified by
293 row and column index.
294 matrixName get column column
296 Returns a list containing the values from all cells in the col‐
297 umn identified by the index. The contents of the cell in row 0
298 are stored as the first element of this list.
299 matrixName get rect column_tl row_tl column_br row_br
301 Returns a list of lists of cell values. The values stored in the
302 result come from the sub-matrix whose top-left and bottom-right
303 cells are specified by column_tl, row_tl and column_br, row_br
304 resp. Note that the following equations have to be true: "col‐
305 umn_tl <= column_br" and "row_tl <= row_br". The result is orga‐
306 nized as follows: The outer list is the list of rows, its ele‐
307 ments are lists representing a single row. The row with the
308 smallest index is the first element of the outer list. The ele‐
309 ments of the row lists represent the selected cell values. The
310 cell with the smallest index is the first element in each row
311 list.
312 matrixName get row row
314 Returns a list containing the values from all cells in the row
315 identified by the index. The contents of the cell in column 0
316 are stored as the first element of this list.
317 matrixName insert column column ?values?
319 Extends the matrix by one column and then acts like set column
320 (see below) on this new column if there were values supplied.
321 Without values the new cells will be set to the empty string.
322 The new column is inserted just before the column specified by
323 the given index. This means, if column is less than or equal to
324 zero, then the new column is inserted at the beginning of the
325 matrix, before the first column. If column has the value end, or
326 if it is greater than or equal to the number of columns in the
327 matrix, then the new column is appended to the matrix, behind
328 the last column. The old column at the chosen index and all col‐
329 umns with higher indices are shifted one index upward.
330 matrixName insert row row ?values?
332 Extends the matrix by one row and then acts like set row (see
333 below) on this new row if there were values supplied. Without
334 values the new cells will be set to the empty string. The new
335 row is inserted just before the row specified by the given
336 index. This means, if row is less than or equal to zero, then
337 the new row is inserted at the beginning of the matrix, before
338 the first row. If row has the value end, or if it is greater
339 than or equal to the number of rows in the matrix, then the new
340 row is appended to the matrix, behind the last row. The old row
341 at that index and all rows with higher indices are shifted one
342 index upward.
343 matrixName link ?-transpose? arrayvar
345 Links the matrix to the specified array variable. This means
346 that the contents of all cells in the matrix is stored in the
347 array too, with all changes to the matrix propagated there too.
348 The contents of the cell (column,row) is stored in the array
349 using the key column,row. If the option -transpose is specified
350 the key row,column will be used instead. It is possible to link
351 the matrix to more than one array. Note that the link is bidi‐
352 rectional, i.e. changes to the array are mirrored in the matrix
353 too.
354 matrixName links
356 Returns a list containing the names of all array variables the
357 matrix was linked to through a call to method link.
358 matrixName rowheight row
360 Returns the height of the specified row in lines. This is the
361 highest number of lines spanned by a cell over all cells in the
362 row.
363 matrixName rows
365 Returns the number of rows currently managed by the matrix.
366 matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
368 Searches the whole matrix for cells matching the pattern and
369 returns a list with all matches. Each item in the aforementioned
370 list is a list itself and contains the column and row index of
371 the matching cell, in this order. The results are ordered by
372 column first and row second, both times in ascending order. This
373 means that matches to the left and the top of the matrix come
374 before matches to the right and down.
375 The type of the pattern (string, glob, regular expression) is
377 determined by the option after the search keyword. If no option
378 is given it defaults to -exact.
379 If the option -nocase is specified the search will be case-
381 insensitive.
382 matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pat‐
384 tern
385 Like search all, but the search is restricted to the specified
386 column.
387 matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
389 Like search all, but the search is restricted to the specified
390 row.
391 matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl
393 row_tl column_br row_br pattern
394 Like search all, but the search is restricted to the specified
395 rectangular area of the matrix.
396 matrixName serialize ?column_tl row_tl column_br row_br?
398 This method serializes the sub-matrix spanned up by the rectan‐
399 gle specification. In other words it returns a tcl value com‐
400 pletely describing that matrix. If no rectangle is specified the
401 whole matrix will be serialized. This allows, for example, the
402 transfer of matrix objects (or parts thereof) over arbitrary
403 channels, persistence, etc. This method is also the basis for
404 both the copy constructor and the assignment operator.
405 The result of this method has to be semantically identical over
407 all implementations of the matrix interface. This is what will
408 enable us to copy matrix data between different implementations
409 of the same interface.
410 The result is a list containing exactly three items.
412 The first two elements of the list specify the number of rows
414 and columns of the matrix, in that order. The values integer
415 numbers greater than or equal to zero.
416 The last element of the list contains the values of the matrix
418 cells we have serialized, in the form of a value like it is
419 returned by the get rect. However empty cells to the right and
420 bottom of the matrix can be left out of that value as the size
421 information in the serialization allows the receiver the cre‐
422 ation of a matrix with the proper size despite the missing val‐
423 ues.
424 # A possible serialization for the matrix structure
427 #
428 # | a b d g |
429 # | c e |
430 # | f |
431 #
432 # is
433 #
434 # 3 4 {{a b d g} {c e} {f}}
435 matrixName set cell column row value
439 Sets the value in the cell identified by row and column index to
440 the data in the third argument.
441 matrixName set column column values
443 Sets the values in the cells identified by the column index to
444 the elements of the list provided as the third argument. Each
445 element of the list is assigned to one cell, with the first ele‐
446 ment going into the cell in row 0 and then upward. If there are
447 less values in the list than there are rows the remaining rows
448 are set to the empty string. If there are more values in the
449 list than there are rows the superfluous elements are ignored.
450 The matrix is not extended by this operation.
451 matrixName set rect column row values
453 Takes a list of lists of cell values and writes them into the
454 submatrix whose top-left cell is specified by the two indices.
455 If the sublists of the outerlist are not of equal length the
456 shorter sublists will be filled with empty strings to the length
457 of the longest sublist. If the submatrix specified by the top-
458 left cell and the number of rows and columns in the values
459 extends beyond the matrix we are modifying the over-extending
460 parts of the values are ignored, i.e. essentially cut off. This
461 subcommand expects its input in the format as returned by get
462 rect.
463 matrixName set row row values
465 Sets the values in the cells identified by the row index to the
466 elements of the list provided as the third argument. Each ele‐
467 ment of the list is assigned to one cell, with the first element
468 going into the cell in column 0 and then upward. If there are
469 less values in the list than there are columns the remaining
470 columns are set to the empty string. If there are more values in
471 the list than there are columns the superfluous elements are
472 ignored. The matrix is not extended by this operation.
473 matrixName sort columns ?-increasing|-decreasing? row
475 Sorts the columns in the matrix using the data in the specified
476 row as the key to sort by. The options -increasing and -decreas‐
477 ing have the same meaning as for lsort. If no option is speci‐
478 fied -increasing is assumed.
479 matrixName sort rows ?-increasing|-decreasing? column
481 Sorts the rows in the matrix using the data in the specified
482 column as the key to sort by. The options -increasing and
483 -decreasing have the same meaning as for lsort. If no option is
484 specified -increasing is assumed.
485 matrixName swap columns column_a column_b
487 Swaps the contents of the two specified columns.
488 matrixName swap rows row_a row_b
490 Swaps the contents of the two specified rows.
491 matrixName transpose
493 Transposes the contents of the matrix, i.e. swaps rows for col‐
494 umns and vice versa.
495 matrixName unlink arrayvar
497 Removes the link between the matrix and the specified arrayvari‐
498 able, if there is one.
499
501 The examples below assume a 5x5 matrix M with the first row containing
502 the values 1 to 5, with 1 in the top-left cell. Each other row contains
503 the contents of the row above it, rotated by one cell to the right.
504 % M get rect 0 0 4 4
506 {{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}}
507 % M set rect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
510 % M get rect 0 0 4 4
511 {{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}}
512 Assuming that the style definitions in the example section of the man‐
515 page for the package report are loaded into the interpreter now an
516 example which formats a matrix into a tabular report. The code filling
517 the matrix with data is not shown. contains useful data.
518 % ::struct::matrix m
520 % # ... fill m with data, assume 5 columns
521 % ::report::report r 5 style captionedtable 1
522 % m format 2string r
523 +---+-------------------+-------+-------+--------+
524 |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%|
525 +---+-------------------+-------+-------+--------+
526 |001|CATCH return ok |7 |13 |53.85 |
527 |002|CATCH return error |68 |91 |74.73 |
528 |003|CATCH no catch used|7 |14 |50.00 |
529 |004|IF if true numeric |12 |33 |36.36 |
530 |005|IF elseif |15 |47 |31.91 |
531 | |true numeric | | | |
532 +---+-------------------+-------+-------+--------+
533 %
534 % # alternate way of doing the above
535 % r printmatrix m
536
539 This document, and the package it describes, will undoubtedly contain
540 bugs and other problems. Please report such in the category struct ::
541 matrix of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].
542 Please also report any ideas for enhancements you may have for either
543 package and/or documentation.
544 When proposing code changes, please provide unified diffs, i.e the out‐
546 put of diff -u.
547 Note further that attachments are strongly preferred over inlined
549 patches. Attachments can be made by going to the Edit form of the
550 ticket immediately after its creation, and then using the left-most
551 button in the secondary navigation bar.
552
554 matrix
555
557 Data structures
558
560 Copyright (c) 2002-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>
561tcllib 2.0.3 struct::matrix(n)