1`struct::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

## COPYRIGHT

560`Copyright (c) 2002-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>`

561`562`

`563`

`564`

`565`

`tcllib 2.0.3 struct::matrix(n)`