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

NAME

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

SYNOPSIS

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

DESCRIPTION

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
121       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
127       The main command of the package is:
128
129       ::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
135              matrixName option ?arg arg ...?
136                     Option  and  the args determine the exact behavior of the
137                     command.
138
139       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
146       In other words
147
148
149
150                  ::struct::matrix mymatrix = b
151
152
153       is equivalent to
154
155
156
157                  ::struct::matrix mymatrix
158                  mymatrix = b
159
160
161       and
162
163
164
165                  ::struct::matrix mymatrix deserialize $b
166
167
168       is equivalent to
169
170
171
172                  ::struct::matrix mymatrix
173                  mymatrix deserialize $b
174
175
176       The following commands are possible for matrix objects:
177
178       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
184              This operation is in effect equivalent to
185
186
187
188                  matrixName deserialize [sourcematrix serialize]
189
190
191       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
197              This operation is in effect equivalent to
198
199
200
201                  destmatrix deserialize [matrixName serialize]
202
203
204       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
211       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
217       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
223       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
229       matrixName cells
230              Returns the number of cells currently  managed  by  the  matrix.
231              This is the product of rows and columns.
232
233       matrixName cellsize column row
234              Returns  the  length  of  the string representation of the value
235              currently contained in the addressed cell.
236
237       matrixName columns
238              Returns the number of columns currently managed by the matrix.
239
240       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
247              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
251       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
255       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
259       matrixName delete row row
260              Deletes the specified row from the matrix  and  shifts  all  row
261              with higher indices one index down.
262
263       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
267       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
272       matrixName destroy
273              Destroys the matrix, including its storage space and  associated
274              command.
275
276       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
283       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
291       matrixName get cell column row
292              Returns the value currently contained in the cell identified  by
293              row and column index.
294
295       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
300       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
313       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
318       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
331       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
344       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
355       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
359       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
364       matrixName rows
365              Returns the number of rows currently managed by the matrix.
366
367       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
376              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
380              If the option -nocase is specified  the  search  will  be  case-
381              insensitive.
382
383       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
388       matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
389              Like  search  all, but the search is restricted to the specified
390              row.
391
392       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
397       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
406              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
411              The result is a list containing exactly three items.
412
413              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
417              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
425
426                  # 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
436
437
438       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
442       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
452       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
464       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
474       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
480       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
486       matrixName swap columns column_a column_b
487              Swaps the contents of the two specified columns.
488
489       matrixName swap rows row_a row_b
490              Swaps the contents of the two specified rows.
491
492       matrixName transpose
493              Transposes  the contents of the matrix, i.e. swaps rows for col‐
494              umns and vice versa.
495
496       matrixName unlink arrayvar
497              Removes the link between the matrix and the specified arrayvari‐
498              able, if there is one.
499

EXAMPLES

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
505               % 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
508
509               % 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
513
514       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
519                  % ::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
537

BUGS, IDEAS, FEEDBACK

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
545       When proposing code changes, please provide unified diffs, i.e the out‐
546       put of diff -u.
547
548       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

KEYWORDS

554       matrix
555

CATEGORY

557       Data structures
558
560       Copyright (c) 2002-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>
561
562
563
564
565tcllib                               2.0.3                   struct::matrix(n)
Impressum