1struct::matrix_v1(n) Tcl Data Structures struct::matrix_v1(n)
2______________________________________________________________________________
6
8 struct::matrix_v1 - Create and manipulate matrix objects
9
11 package require Tcl 8.2
12 package require struct::matrix ?1.2.1?
14 matrixName option ?arg arg ...?
16 matrixName add column ?values?
18 matrixName add row ?values?
20 matrixName add columns n
22 matrixName add rows n
24 matrixName cells
26 matrixName cellsize column row
28 matrixName columns
30 matrixName columnwidth column
32 matrixName delete column column
34 matrixName delete row row
36 matrixName destroy
38 matrixName format 2string ?report?
40 matrixName format 2chan ??report? channel?
42 matrixName get cell column row
44 matrixName get column column
46 matrixName get rect column_tl row_tl column_br row_br
48 matrixName get row row
50 matrixName insert column column ?values?
52 matrixName insert row row ?values?
54 matrixName link ?-transpose? arrayvar
56 matrixName links
58 matrixName rowheight row
60 matrixName rows
62 matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
64 matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pat‐
66 tern
67 matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
69 matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl
71 row_tl column_br row_br pattern
72 matrixName set cell column row value
74 matrixName set column column values
76 matrixName set rect column row values
78 matrixName set row row values
80 matrixName sort columns ?-increasing|-decreasing? row
82 matrixName sort rows ?-increasing|-decreasing? column
84 matrixName swap columns column_a column_b
86 matrixName swap rows row_a row_b
88 matrixName unlink arrayvar
90______________________________________________________________________________
92
94 The ::struct::matrix command creates a new matrix object with an asso‐
95 ciated global Tcl command whose name is matrixName. This command may
96 be used to invoke various operations on the matrix. It has the follow‐
97 ing general form:
98 matrixName option ?arg arg ...?
100 Option and the args determine the exact behavior of the command.
101 A matrix is a rectangular collection of cells, i.e. organized in rows
103 and columns. Each cell contains exactly one value of arbitrary form.
104 The cells in the matrix are addressed by pairs of integer numbers, with
105 the first (left) number in the pair specifying the column and the sec‐
106 ond (right) number specifying the row the cell is in. These indices are
107 counted from 0 upward. The special non-numeric index end refers to the
108 last row or column in the matrix, depending on the context. Indices of
109 the form end-number are counted from the end of the row or column, like
110 they are for standard Tcl lists. Trying to access non-existing cells
111 causes an error.
112 The matrices here are created empty, i.e. they have neither rows nor
114 columns. The user then has to add rows and columns as needed by his
115 application. A specialty of this structure is the ability to export an
116 array-view onto its contents. Such can be used by tkTable, for example,
117 to link the matrix into the display.
118 The following commands are possible for matrix objects:
120 matrixName add column ?values?
122 Extends the matrix by one column and then acts like setcolumn
123 (see below) on this new column if there were values supplied.
124 Without values the new cells will be set to the empty string.
125 The new column is appended immediately behind the last existing
126 column.
127 matrixName add row ?values?
129 Extends the matrix by one row and then acts like setrow (see
130 below) on this new row if there were values supplied. Without
131 values the new cells will be set to the empty string. The new
132 row is appended immediately behind the last existing row.
133 matrixName add columns n
135 Extends the matrix by n columns. The new cells will be set to
136 the empty string. The new columns are appended immediately
137 behind the last existing column. A value of n equal to or
138 smaller than 0 is not allowed.
139 matrixName add rows n
141 Extends the matrix by n rows. The new cells will be set to the
142 empty string. The new rows are appended immediately behind the
143 last existing row. A value of n equal to or smaller than 0 is
144 not allowed.
145 matrixName cells
147 Returns the number of cells currently managed by the matrix.
148 This is the product of rows and columns.
149 matrixName cellsize column row
151 Returns the length of the string representation of the value
152 currently contained in the addressed cell.
153 matrixName columns
155 Returns the number of columns currently managed by the matrix.
156 matrixName columnwidth column
158 Returns the length of the longest string representation of all
159 the values currently contained in the cells of the addressed
160 column if these are all spanning only one line. For cell values
161 spanning multiple lines the length of their longest line goes
162 into the computation.
163 matrixName delete column column
165 Deletes the specified column from the matrix and shifts all col‐
166 umns with higher indices one index down.
167 matrixName delete row row
169 Deletes the specified row from the matrix and shifts all row
170 with higher indices one index down.
171 matrixName destroy
173 Destroys the matrix, including its storage space and associated
174 command.
175 matrixName format 2string ?report?
177 Formats the matrix using the specified report object and returns
178 the string containing the result of this operation. The report
179 has to support the printmatrix method. If no report is specified
180 the system will use an internal report definition to format the
181 matrix.
182 matrixName format 2chan ??report? channel?
184 Formats the matrix using the specified report object and writes
185 the string containing the result of this operation into the
186 channel. The report has to support the printmatrix2channel
187 method. If no report is specified the system will use an inter‐
188 nal report definition to format the matrix. If no channel is
189 specified the system will use stdout.
190 matrixName get cell column row
192 Returns the value currently contained in the cell identified by
193 row and column index.
194 matrixName get column column
196 Returns a list containing the values from all cells in the col‐
197 umn identified by the index. The contents of the cell in row 0
198 are stored as the first element of this list.
199 matrixName get rect column_tl row_tl column_br row_br
201 Returns a list of lists of cell values. The values stored in the
202 result come from the sub-matrix whose top-left and bottom-right
203 cells are specified by column_tl, row_tl and column_br, row_br
204 resp. Note that the following equations have to be true: "col‐
205 umn_tl <= column_br" and "row_tl <= row_br". The result is orga‐
206 nized as follows: The outer list is the list of rows, its ele‐
207 ments are lists representing a single row. The row with the
208 smallest index is the first element of the outer list. The ele‐
209 ments of the row lists represent the selected cell values. The
210 cell with the smallest index is the first element in each row
211 list.
212 matrixName get row row
214 Returns a list containing the values from all cells in the row
215 identified by the index. The contents of the cell in column 0
216 are stored as the first element of this list.
217 matrixName insert column column ?values?
219 Extends the matrix by one column and then acts like setcolumn
220 (see below) on this new column if there were values supplied.
221 Without values the new cells will be set to the empty string.
222 The new column is inserted just before the column specified by
223 the given index. This means, if column is less than or equal to
224 zero, then the new column is inserted at the beginning of the
225 matrix, before the first column. If column has the value end, or
226 if it is greater than or equal to the number of columns in the
227 matrix, then the new column is appended to the matrix, behind
228 the last column. The old column at the chosen index and all col‐
229 umns with higher indices are shifted one index upward.
230 matrixName insert row row ?values?
232 Extends the matrix by one row and then acts like setrow (see
233 below) on this new row if there were values supplied. Without
234 values the new cells will be set to the empty string. The new
235 row is inserted just before the row specified by the given
236 index. This means, if row is less than or equal to zero, then
237 the new row is inserted at the beginning of the matrix, before
238 the first row. If row has the value end, or if it is greater
239 than or equal to the number of rows in the matrix, then the new
240 row is appended to the matrix, behind the last row. The old row
241 at that index and all rows with higher indices are shifted one
242 index upward.
243 matrixName link ?-transpose? arrayvar
245 Links the matrix to the specified array variable. This means
246 that the contents of all cells in the matrix is stored in the
247 array too, with all changes to the matrix propagated there too.
248 The contents of the cell (column,row) is stored in the array
249 using the key column,row. If the option -transpose is specified
250 the key row,column will be used instead. It is possible to link
251 the matrix to more than one array. Note that the link is bidi‐
252 rectional, i.e. changes to the array are mirrored in the matrix
253 too.
254 matrixName links
256 Returns a list containing the names of all array variables the
257 matrix was linked to through a call to method link.
258 matrixName rowheight row
260 Returns the height of the specified row in lines. This is the
261 highest number of lines spanned by a cell over all cells in the
262 row.
263 matrixName rows
265 Returns the number of rows currently managed by the matrix.
266 matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
268 Searches the whole matrix for cells matching the pattern and
269 returns a list with all matches. Each item in the aforementioned
270 list is a list itself and contains the column and row index of
271 the matching cell, in this order. The results are ordered by
272 column first and row second, both times in ascending order. This
273 means that matches to the left and the top of the matrix come
274 before matches to the right and down.
275 The type of the pattern (string, glob, regular expression) is
277 determined by the option after the search keyword. If no option
278 is given it defaults to -exact.
279 If the option -nocase is specified the search will be case-
281 insensitive.
282 matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pat‐
284 tern
285 Like search all, but the search is restricted to the specified
286 column.
287 matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
289 Like search all, but the search is restricted to the specified
290 row.
291 matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl
293 row_tl column_br row_br pattern
294 Like search all, but the search is restricted to the specified
295 rectangular area of the matrix.
296 matrixName set cell column row value
298 Sets the value in the cell identified by row and column index to
299 the data in the third argument.
300 matrixName set column column values
302 Sets the values in the cells identified by the column index to
303 the elements of the list provided as the third argument. Each
304 element of the list is assigned to one cell, with the first ele‐
305 ment going into the cell in row 0 and then upward. If there are
306 less values in the list than there are rows the remaining rows
307 are set to the empty string. If there are more values in the
308 list than there are rows the superfluous elements are ignored.
309 The matrix is not extended by this operation.
310 matrixName set rect column row values
312 Takes a list of lists of cell values and writes them into the
313 submatrix whose top-left cell is specified by the two indices.
314 If the sublists of the outerlist are not of equal length the
315 shorter sublists will be filled with empty strings to the length
316 of the longest sublist. If the submatrix specified by the top-
317 left cell and the number of rows and columns in the values
318 extends beyond the matrix we are modifying the over-extending
319 parts of the values are ignored, i.e. essentially cut off. This
320 subcommand expects its input in the format as returned by
321 getrect.
322 matrixName set row row values
324 Sets the values in the cells identified by the row index to the
325 elements of the list provided as the third argument. Each ele‐
326 ment of the list is assigned to one cell, with the first element
327 going into the cell in column 0 and then upward. If there are
328 less values in the list than there are columns the remaining
329 columns are set to the empty string. If there are more values in
330 the list than there are columns the superfluous elements are
331 ignored. The matrix is not extended by this operation.
332 matrixName sort columns ?-increasing|-decreasing? row
334 Sorts the columns in the matrix using the data in the specified
335 row as the key to sort by. The options -increasing and -decreas‐
336 ing have the same meaning as for lsort. If no option is speci‐
337 fied -increasing is assumed.
338 matrixName sort rows ?-increasing|-decreasing? column
340 Sorts the rows in the matrix using the data in the specified
341 column as the key to sort by. The options -increasing and
342 -decreasing have the same meaning as for lsort. If no option is
343 specified -increasing is assumed.
344 matrixName swap columns column_a column_b
346 Swaps the contents of the two specified columns.
347 matrixName swap rows row_a row_b
349 Swaps the contents of the two specified rows.
350 matrixName unlink arrayvar
352 Removes the link between the matrix and the specified arrayvari‐
353 able, if there is one.
354
356 The examples below assume a 5x5 matrix M with the first row containing
357 the values 1 to 5, with 1 in the top-left cell. Each other row contains
358 the contents of the row above it, rotated by one cell to the right.
359 % M getrect 0 0 4 4
361 {{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}}
362 % M setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
365 % M getrect 0 0 4 4
366 {{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}}
367 Assuming that the style definitions in the example section of the man‐
370 page for the package report are loaded into the interpreter now an
371 example which formats a matrix into a tabular report. The code filling
372 the matrix with data is not shown. contains useful data.
373 % ::struct::matrix m
375 % # ... fill m with data, assume 5 columns
376 % ::report::report r 5 style captionedtable 1
377 % m format 2string r
378 +---+-------------------+-------+-------+--------+
379 |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%|
380 +---+-------------------+-------+-------+--------+
381 |001|CATCH return ok |7 |13 |53.85 |
382 |002|CATCH return error |68 |91 |74.73 |
383 |003|CATCH no catch used|7 |14 |50.00 |
384 |004|IF if true numeric |12 |33 |36.36 |
385 |005|IF elseif |15 |47 |31.91 |
386 | |true numeric | | | |
387 +---+-------------------+-------+-------+--------+
388 %
389 % # alternate way of doing the above
390 % r printmatrix m
391
394 This document, and the package it describes, will undoubtedly contain
395 bugs and other problems. Please report such in the category struct ::
396 matrix of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].
397 Please also report any ideas for enhancements you may have for either
398 package and/or documentation.
399 When proposing code changes, please provide unified diffs, i.e the out‐
401 put of diff -u.
402 Note further that attachments are strongly preferred over inlined
404 patches. Attachments can be made by going to the Edit form of the
405 ticket immediately after its creation, and then using the left-most
406 button in the secondary navigation bar.
407
409 matrix
410
412 Data structures
413
415 Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>
416tcllib 1.2.1 struct::matrix_v1(n)