1struct::matrix_v1(n)          Tcl Data Structures         struct::matrix_v1(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       struct::matrix_v1 - Create and manipulate matrix objects
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require struct::matrix  ?1.2.2?
14
15       matrixName option ?arg arg ...?
16
17       matrixName add column ?values?
18
19       matrixName add row ?values?
20
21       matrixName add columns n
22
23       matrixName add rows n
24
25       matrixName cells
26
27       matrixName cellsize column row
28
29       matrixName columns
30
31       matrixName columnwidth column
32
33       matrixName delete column column
34
35       matrixName delete row row
36
37       matrixName destroy
38
39       matrixName format 2string ?report?
40
41       matrixName format 2chan ??report? channel?
42
43       matrixName get cell column row
44
45       matrixName get column column
46
47       matrixName get rect column_tl row_tl column_br row_br
48
49       matrixName get row row
50
51       matrixName insert column column ?values?
52
53       matrixName insert row row ?values?
54
55       matrixName link ?-transpose? arrayvar
56
57       matrixName links
58
59       matrixName rowheight row
60
61       matrixName rows
62
63       matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
64
65       matrixName  search  ?-nocase? ?-exact|-glob|-regexp? column column pat‐
66       tern
67
68       matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
69
70       matrixName  search  ?-nocase?  ?-exact|-glob|-regexp?  rect   column_tl
71       row_tl column_br row_br pattern
72
73       matrixName set cell column row value
74
75       matrixName set column column values
76
77       matrixName set rect column row values
78
79       matrixName set row row values
80
81       matrixName sort columns ?-increasing|-decreasing? row
82
83       matrixName sort rows ?-increasing|-decreasing? column
84
85       matrixName swap columns column_a column_b
86
87       matrixName swap rows row_a row_b
88
89       matrixName unlink arrayvar
90
91______________________________________________________________________________
92

DESCRIPTION

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
99       matrixName option ?arg arg ...?
100              Option and the args determine the exact behavior of the command.
101
102       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
113       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 ap‐
115       plication.  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
119       The following commands are possible for matrix objects:
120
121       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
128       matrixName add row ?values?
129              Extends the matrix by one row and then acts like setrow (see be‐
130              low) on this new row if there were values supplied. Without val‐
131              ues  the  new cells will be set to the empty string. The new row
132              is appended immediately behind the last existing row.
133
134       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 be‐
137              hind the last existing column. A value of n equal to or  smaller
138              than 0 is not allowed.
139
140       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
146       matrixName cells
147              Returns the number of cells currently  managed  by  the  matrix.
148              This is the product of rows and columns.
149
150       matrixName cellsize column row
151              Returns  the  length  of  the string representation of the value
152              currently contained in the addressed cell.
153
154       matrixName columns
155              Returns the number of columns currently managed by the matrix.
156
157       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
164       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
168       matrixName delete row row
169              Deletes  the  specified  row  from the matrix and shifts all row
170              with higher indices one index down.
171
172       matrixName destroy
173              Destroys the matrix, including its storage space and  associated
174              command.
175
176       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
183       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
191       matrixName get cell column row
192              Returns the value currently contained in the cell identified  by
193              row and column index.
194
195       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
200       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
213       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
218       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
231       matrixName insert row row ?values?
232              Extends the matrix by one row and then acts like setrow (see be‐
233              low) on this new row if there were values supplied. Without val‐
234              ues  the  new cells will be set to the empty string. The new row
235              is inserted just before the row specified by  the  given  index.
236              This  means,  if row is less than or equal to zero, then the new
237              row is inserted at the beginning of the matrix, before the first
238              row. If row has the value end, or if it is greater than or equal
239              to the number of rows in the matrix, then the  new  row  is  ap‐
240              pended  to  the matrix, behind the last row. The old row at that
241              index and all rows with higher indices are shifted one index up‐
242              ward.
243
244       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 us‐
249              ing  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
255       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
259       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
264       matrixName rows
265              Returns the number of rows currently managed by the matrix.
266
267       matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
268              Searches the whole matrix for cells matching the pattern and re‐
269              turns  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
276              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
280              If the option -nocase is specified the search will  be  case-in‐
281              sensitive.
282
283       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
288       matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
289              Like  search  all, but the search is restricted to the specified
290              row.
291
292       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
297       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
301       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
311       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 ex‐
318              tends 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  ge‐
321              trect.
322
323       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 ig‐
331              nored. The matrix is not extended by this operation.
332
333       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
339       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  -de‐
342              creasing  have  the  same meaning as for lsort.  If no option is
343              specified -increasing is assumed.
344
345       matrixName swap columns column_a column_b
346              Swaps the contents of the two specified columns.
347
348       matrixName swap rows row_a row_b
349              Swaps the contents of the two specified rows.
350
351       matrixName unlink arrayvar
352              Removes the link between the matrix and the specified arrayvari‐
353              able, if there is one.
354

EXAMPLES

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
360               % 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
363
364               % 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
368
369       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  ex‐
371       ample  which  formats  a matrix into a tabular report. The code filling
372       the matrix with data is not shown.  contains useful data.
373
374                  % ::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
392

BUGS, IDEAS, FEEDBACK

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
400       When proposing code changes, please provide unified diffs, i.e the out‐
401       put of diff -u.
402
403       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

KEYWORDS

409       matrix
410

CATEGORY

412       Data structures
413
415       Copyright (c) 2002,2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
416
417
418
419
420tcllib                               1.2.2                struct::matrix_v1(n)
Impressum