1[comment {-*- tcl -*-}] 2[manpage_begin struct::matrix n 2.0.1] 3[copyright {2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Tcl Data Structures}] 5[titledesc {Create and manipulate matrix objects}] 6[category {Data structures}] 7[require Tcl 8.2] 8[require struct::matrix [opt 2.0.1]] 9[description] 10[para] 11 12A matrix is a rectangular collection of cells, i.e. organized in rows 13and columns. Each cell contains exactly one value of arbitrary 14form. The cells in the matrix are addressed by pairs of integer 15numbers, with the first (left) number in the pair specifying the 16column and the second (right) number specifying the row the cell is 17in. These indices are counted from 0 upward. The special non-numeric 18index [const end] refers to the last row or column in the matrix, 19depending on the context. Indices of the form 20 21[const end]-[var number] are counted from the end of the row or 22column, like they are for standard Tcl lists. Trying to access 23non-existing cells causes an error. 24 25[para] 26 27The matrices here are created empty, i.e. they have neither rows nor 28columns. The user then has to add rows and columns as needed by his 29application. A specialty of this structure is the ability to export an 30array-view onto its contents. Such can be used by tkTable, for 31example, to link the matrix into the display. 32 33[para] 34 35 36The main command of the package is: 37 38[list_begin definitions] 39 40[call [cmd ::struct::matrix] [opt [arg matrixName]] [opt "[const =]|[const :=]|[const as]|[const deserialize] [arg source]"]] 41 42The command creates a new matrix object with an associated global Tcl 43command whose name is [arg matrixName]. This command may be used to 44invoke various operations on the matrix. It has the following general 45form: 46 47[list_begin definitions] 48[call [cmd matrixName] [arg option] [opt [arg "arg arg ..."]]] 49 50[arg Option] and the [arg arg]s determine the exact behavior of the 51command. 52 53[list_end] 54[para] 55 56If [arg matrixName] is not specified a unique name will be generated 57by the package itself. If a [arg source] is specified the new matrix 58will be initialized to it. For the operators [const =], [const :=], 59and [const as] the argument [arg source] is interpreted as the name of 60another matrix object, and the assignment operator [method =] will be 61executed. For [const deserialize] the [arg source] is a serialized 62matrix object and [method deserialize] will be executed. 63 64[para] 65 66In other words 67[para] 68[example { 69 ::struct::matrix mymatrix = b 70}] 71[para] 72is equivalent to 73[para] 74[example { 75 ::struct::matrix mymatrix 76 mymatrix = b 77}] 78[para] 79and 80[para] 81[example { 82 ::struct::matrix mymatrix deserialize $b 83}] 84[para] 85is equivalent to 86[para] 87[example { 88 ::struct::matrix mymatrix 89 mymatrix deserialize $b 90}] 91 92 93[list_end] 94 95[para] 96 97The following commands are possible for matrix objects: 98 99[list_begin definitions] 100 101[call [arg matrixName] [method =] [arg sourcematrix]] 102 103This is the assignment operator for matrix objects. It copies the matrix 104contained in the matrix object [arg sourcematrix] over the matrix data in 105[arg matrixName]. The old contents of [arg matrixName] are deleted by 106this operation. 107 108[para] 109 110This operation is in effect equivalent to 111[para] 112[example_begin] 113 [arg matrixName] [method deserialize] [lb][arg sourcematrix] [method serialize][rb] 114[example_end] 115 116 117[call [arg matrixName] [method -->] [arg destmatrix]] 118 119This is the reverse assignment operator for matrix objects. It copies 120the matrix contained in the matrix object [arg matrixName] over the matrix 121data in the object [arg destmatrix]. 122 123The old contents of [arg destmatrix] are deleted by this operation. 124 125[para] 126 127This operation is in effect equivalent to 128[para] 129[example_begin] 130 [arg destmatrix] [method deserialize] [lb][arg matrixName] [method serialize][rb] 131[example_end] 132 133 134[call [arg matrixName] [method {add column}] [opt [arg values]]] 135 136Extends the matrix by one column and then acts like [method {set column}] 137(see below) on this new column if there were [arg values] 138supplied. Without [arg values] the new cells will be set to the empty 139string. The new column is appended immediately behind the last 140existing column. 141 142[call [arg matrixName] [method {add row}] [opt [arg values]]] 143 144Extends the matrix by one row and then acts like [method {set row}] (see 145below) on this new row if there were [arg values] supplied. Without 146[arg values] the new cells will be set to the empty string. The new 147row is appended immediately behind the last existing row. 148 149[call [arg matrixName] [method {add columns}] [arg n]] 150 151Extends the matrix by [arg n] columns. The new cells will be set to 152the empty string. The new columns are appended immediately behind the 153last existing column. A value of [arg n] equal to or smaller than 0 is 154not allowed. 155 156[call [arg matrixName] [method {add rows}] [arg n]] 157 158Extends the matrix by [arg n] rows. The new cells will be set to the 159empty string. The new rows are appended immediately behind the last 160existing row. A value of [arg n] equal to or smaller than 0 is not 161allowed. 162 163[call [arg matrixName] [method cells]] 164 165Returns the number of cells currently managed by the matrix. This is 166the product of [method rows] and [method columns]. 167 168[call [arg matrixName] [method cellsize] [arg {column row}]] 169 170Returns the length of the string representation of the value currently 171contained in the addressed cell. 172 173[call [arg matrixName] [method columns]] 174 175Returns the number of columns currently managed by the matrix. 176 177[call [arg matrixName] [method columnwidth] [arg column]] 178 179Returns the length of the longest string representation of all the 180values currently contained in the cells of the addressed column if 181these are all spanning only one line. For cell values spanning 182multiple lines the length of their longest line goes into the 183computation. 184 185[call [arg matrixName] [method {delete column}] [arg column]] 186 187Deletes the specified column from the matrix and shifts all columns 188with higher indices one index down. 189 190 191[call [arg matrixName] [method {delete columns}] [arg n]] 192 193Deletes [arg n] columns from the right of the matrix. The value of 194[arg n] has to satisfy the constraint 195 196"0 < [arg n] < [lb][cmd matrixName] [method columns][rb]" 197 198 199[call [arg matrixName] [method {delete row}] [arg row]] 200 201Deletes the specified row from the matrix and shifts all row with 202higher indices one index down. 203 204 205[call [arg matrixName] [method {delete rows}] [arg n]] 206 207Deletes [arg n] rows from the bottom of the matrix. The value of 208[arg n] has to satisfy the constraint 209 210"0 < [arg n] < [lb][cmd matrixName] [method rows][rb]" 211 212 213[call [arg matrixName] [method deserialize] [arg serialization]] 214 215This is the complement to [method serialize]. It replaces matrix data 216in [arg matrixName] with the matrix described by the [arg serialization] 217value. The old contents of [arg matrixName] are deleted by this 218operation. 219 220 221[call [arg matrixName] [method destroy]] 222 223Destroys the matrix, including its storage space and associated 224command. 225 226[call [arg matrixName] [method {format 2string}] [opt [arg report]]] 227 228Formats the matrix using the specified report object and returns the 229string containing the result of this operation. The report has to 230support the [method printmatrix] method. If no [arg report] is 231specified the system will use an internal report definition to format 232the matrix. 233 234[call [arg matrixName] [method {format 2chan}] [opt "[opt [arg report]] [arg channel]"]] 235 236Formats the matrix using the specified report object and writes the 237string containing the result of this operation into the channel. The 238report has to support the [method printmatrix2channel] method. If no 239[arg report] is specified the system will use an internal report 240definition to format the matrix. If no [arg channel] is specified the 241system will use [const stdout]. 242 243[call [arg matrixName] [method {get cell}] [arg {column row}]] 244 245Returns the value currently contained in the cell identified by row 246and column index. 247 248[call [arg matrixName] [method {get column}] [arg column]] 249 250Returns a list containing the values from all cells in the column 251identified by the index. The contents of the cell in row 0 are stored 252as the first element of this list. 253 254[call [arg matrixName] [method {get rect}] [arg {column_tl row_tl column_br row_br}]] 255 256Returns a list of lists of cell values. The values stored in the 257result come from the sub-matrix whose top-left and bottom-right cells 258are specified by [arg {column_tl, row_tl}] and 259 260[arg {column_br, row_br}] resp. Note that the following equations have 261to be true: "[arg column_tl] <= [arg column_br]" and "[arg row_tl] <= 262[arg row_br]". The result is organized as follows: The outer list is 263the list of rows, its elements are lists representing a single 264row. The row with the smallest index is the first element of the outer 265list. The elements of the row lists represent the selected cell 266values. The cell with the smallest index is the first element in each 267row list. 268 269[call [arg matrixName] [method {get row}] [arg row]] 270 271Returns a list containing the values from all cells in the row 272identified by the index. The contents of the cell in column 0 are 273stored as the first element of this list. 274 275[call [arg matrixName] [method {insert column}] [arg column] [opt [arg values]]] 276 277Extends the matrix by one column and then acts like [method {set column}] 278(see below) on this new column if there were [arg values] 279supplied. Without [arg values] the new cells will be set to the empty 280string. The new column is inserted just before the column specified by 281the given index. This means, if [arg column] is less than or equal to 282zero, then the new column is inserted at the beginning of the matrix, 283before the first column. If [arg column] has the value [const end], 284or if it is greater than or equal to the number of columns in the 285matrix, then the new column is appended to the matrix, behind the last 286column. The old column at the chosen index and all columns with higher 287indices are shifted one index upward. 288 289[call [arg matrixName] [method {insert row}] [arg row] [opt [arg values]]] 290 291Extends the matrix by one row and then acts like [method {set row}] (see 292below) on this new row if there were [arg values] supplied. Without 293[arg values] the new cells will be set to the empty string. The new 294row is inserted just before the row specified by the given index. This 295means, if [arg row] is less than or equal to zero, then the new row is 296inserted at the beginning of the matrix, before the first row. If 297 298[arg row] has the value [const end], or if it is greater than or 299equal to the number of rows in the matrix, then the new row is 300appended to the matrix, behind the last row. The old row at that index 301and all rows with higher indices are shifted one index upward. 302 303[call [arg matrixName] [method link] [opt -transpose] [arg arrayvar]] 304 305Links the matrix to the specified array variable. This means that the 306contents of all cells in the matrix is stored in the array too, with 307all changes to the matrix propagated there too. The contents of the 308cell [arg (column,row)] is stored in the array using the key 309 310[arg column,row]. If the option [option -transpose] is specified the 311key [arg row,column] will be used instead. It is possible to link the 312matrix to more than one array. Note that the link is bidirectional, 313i.e. changes to the array are mirrored in the matrix too. 314 315 316[call [arg matrixName] [method links]] 317 318Returns a list containing the names of all array variables the matrix 319was linked to through a call to method [method link]. 320 321 322[call [arg matrixName] [method rowheight] [arg row]] 323 324Returns the height of the specified row in lines. This is the highest 325number of lines spanned by a cell over all cells in the row. 326 327[call [arg matrixName] [method rows]] 328 329Returns the number of rows currently managed by the matrix. 330 331[call [arg matrixName] [method search] [opt -nocase] [opt -exact|-glob|-regexp] [method all] [arg pattern]] 332 333Searches the whole matrix for cells matching the [arg pattern] and 334returns a list with all matches. Each item in the aforementioned list 335is a list itself and contains the column and row index of the matching 336cell, in this order. The results are ordered by column first and row 337second, both times in ascending order. This means that matches to the 338left and the top of the matrix come before matches to the right and 339down. 340 341[para] 342 343The type of the pattern (string, glob, regular expression) is 344determined by the option after the [method search] keyword. If no 345option is given it defaults to [option -exact]. 346 347[para] 348 349If the option [option -nocase] is specified the search will be 350case-insensitive. 351 352[call [arg matrixName] [method search] [opt -nocase] [opt -exact|-glob|-regexp] [method column] [arg {column pattern}]] 353 354Like [method {search all}], but the search is restricted to the 355specified column. 356 357[call [arg matrixName] [method search] [opt -nocase] [opt -exact|-glob|-regexp] [method row] [arg {row pattern}]] 358 359Like [method {search all}], but the search is restricted to the 360specified row. 361 362[call [arg matrixName] [method search] [opt -nocase] [opt -exact|-glob|-regexp] [method rect] [arg {column_tl row_tl column_br row_br pattern}]] 363 364Like [method {search all}], but the search is restricted to the 365specified rectangular area of the matrix. 366 367 368[call [arg matrixName] [method serialize] [opt [arg {column_tl row_tl column_br row_br}]]] 369 370This method serializes the sub-matrix spanned up by the rectangle 371specification. In other words it returns a tcl [emph value] completely 372describing that matrix. If no rectangle is specified the whole matrix 373will be serialized. 374 375This allows, for example, the transfer of matrix objects (or parts 376thereof) over arbitrary channels, persistence, etc. 377 378This method is also the basis for both the copy constructor and the 379assignment operator. 380 381[para] 382 383The result of this method has to be semantically identical over all 384implementations of the matrix interface. This is what will enable us 385to copy matrix data between different implementations of the same 386interface. 387 388[para] 389 390The result is a list containing exactly three items. 391 392[para] 393 394The first two elements of the list specify the number of rows and 395columns of the matrix, in that order. The values integer numbers 396greater than or equal to zero. 397 398[para] 399 400The last element of the list contains the values of the matrix cells 401we have serialized, in the form of a value like it is returned by the 402[method {get rect}]. However empty cells to the right and bottom of 403the matrix can be left out of that value as the size information in 404the serialization allows the receiver the creation of a matrix with 405the proper size despite the missing values. 406 407[example { 408 # A possible serialization for the matrix structure 409 # 410 # | a b d g | 411 # | c e | 412 # | f | 413 # 414 # is 415 # 416 # 3 4 {{a b d g} {c e} {f}} 417}] 418[para] 419 420 421[call [arg matrixName] [method {set cell}] [arg {column row value}]] 422 423Sets the value in the cell identified by row and column index to the 424data in the third argument. 425 426[call [arg matrixName] [method {set column}] [arg {column values}]] 427 428Sets the values in the cells identified by the column index to the 429elements of the list provided as the third argument. Each element of 430the list is assigned to one cell, with the first element going into 431the cell in row 0 and then upward. If there are less values in the 432list than there are rows the remaining rows are set to the empty 433string. If there are more values in the list than there are rows the 434superfluous elements are ignored. The matrix is not extended by this 435operation. 436 437[call [arg matrixName] [method {set rect}] [arg {column row values}]] 438 439Takes a list of lists of cell values and writes them into the 440submatrix whose top-left cell is specified by the two indices. If the 441sublists of the outerlist are not of equal length the shorter sublists 442will be filled with empty strings to the length of the longest 443sublist. If the submatrix specified by the top-left cell and the 444number of rows and columns in the [arg values] extends beyond the 445matrix we are modifying the over-extending parts of the values are 446ignored, i.e. essentially cut off. This subcommand expects its input 447in the format as returned by [method getrect]. 448 449[call [arg matrixName] [method {set row}] [arg {row values}]] 450 451Sets the values in the cells identified by the row index to the 452elements of the list provided as the third argument. Each element of 453the list is assigned to one cell, with the first element going into 454the cell in column 0 and then upward. If there are less values in the 455list than there are columns the remaining columns are set to the empty 456string. If there are more values in the list than there are columns 457the superfluous elements are ignored. The matrix is not extended by 458this operation. 459 460[call [arg matrixName] [method {sort columns}] [opt [option -increasing]|[option -decreasing]] [arg row]] 461 462Sorts the columns in the matrix using the data in the specified 463[arg row] as the key to sort by. The options [option -increasing] 464and [option -decreasing] have the same meaning as for [cmd lsort]. 465If no option is specified [option -increasing] is assumed. 466 467[call [arg matrixName] [method {sort rows}] [opt [option -increasing]|[option -decreasing]] [arg column]] 468 469Sorts the rows in the matrix using the data in the specified 470[arg column] as the key to sort by. The options [option -increasing] 471and [option -decreasing] have the same meaning as for [cmd lsort]. 472If no option is specified [option -increasing] is assumed. 473 474[call [arg matrixName] [method {swap columns}] [arg {column_a column_b}]] 475 476Swaps the contents of the two specified columns. 477 478[call [arg matrixName] [method {swap rows}] [arg {row_a row_b}]] 479 480Swaps the contents of the two specified rows. 481 482 483[call [arg matrixName] [method transpose]] 484 485Transposes the contents of the matrix, i.e. swaps rows for columns and 486vice versa. 487 488 489[call [arg matrixName] [method unlink] [arg arrayvar]] 490 491Removes the link between the matrix and the specified arrayvariable, 492if there is one. 493 494[list_end] 495 496[section EXAMPLES] 497[para] 498 499The examples below assume a 5x5 matrix M with the first row containing 500the values 1 to 5, with 1 in the top-left cell. Each other row 501contains the contents of the row above it, rotated by one cell to the 502right. 503 504[para] 505[example { 506 % M getrect 0 0 4 4 507 {{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}} 508}] 509 510[para] 511[example { 512 % M setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}} 513 % M getrect 0 0 4 4 514 {{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}} 515}] 516 517[para] 518 519Assuming that the style definitions in the example section of the 520manpage for the package [package report] are loaded into the 521interpreter now an example which formats a matrix into a tabular 522report. The code filling the matrix with data is not shown. contains 523useful data. 524 525[para] 526 527[example { 528 % ::struct::matrix m 529 % # ... fill m with data, assume 5 columns 530 % ::report::report r 5 style captionedtable 1 531 % m format 2string r 532 +---+-------------------+-------+-------+--------+ 533 |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%| 534 +---+-------------------+-------+-------+--------+ 535 |001|CATCH return ok |7 |13 |53.85 | 536 |002|CATCH return error |68 |91 |74.73 | 537 |003|CATCH no catch used|7 |14 |50.00 | 538 |004|IF if true numeric |12 |33 |36.36 | 539 |005|IF elseif |15 |47 |31.91 | 540 | |true numeric | | | | 541 +---+-------------------+-------+-------+--------+ 542 % 543 % # alternate way of doing the above 544 % r printmatrix m 545}] 546 547[section {BUGS, IDEAS, FEEDBACK}] 548 549This document, and the package it describes, will undoubtedly contain 550bugs and other problems. 551 552Please report such in the category [emph {struct :: matrix}] of the 553[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 554 555Please also report any ideas for enhancements you may have for either 556package and/or documentation. 557 558 559[keywords matrix] 560[manpage_end] 561