diff options
Diffstat (limited to 'doc/lset.n')
| -rw-r--r--[-rwxr-xr-x] | doc/lset.n | 93 |
1 files changed, 60 insertions, 33 deletions
diff --git a/doc/lset.n b/doc/lset.n index 969aba9..954bd30 100755..100644 --- a/doc/lset.n +++ b/doc/lset.n @@ -1,19 +1,17 @@ '\" -'\" Copyright (c) 2001 by Kevin B. Kenny. All rights reserved. +'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: lset.n,v 1.9 2005/05/10 18:34:02 kennykb Exp $ -'\" -.so man.macros .TH lset n 8.4 Tcl "Tcl Built-In Commands" +.so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME lset \- Change an element in a list .SH SYNOPSIS -\fBlset \fIvarName ?index...? newValue\fR +\fBlset \fIvarName ?index ...? newValue\fR .BE .SH DESCRIPTION .PP @@ -26,13 +24,17 @@ Tcl list and presented as a single argument. Finally, it accepts a new value for an element of \fIvarName\fR. .PP If no indices are presented, the command takes the form: +.PP .CS -lset varName newValue +\fBlset\fR varName newValue .CE +.PP or +.PP .CS -lset varName {} newValue +\fBlset\fR varName {} newValue .CE +.PP In this case, \fInewValue\fR replaces the old value of the variable \fIvarName\fR. .PP @@ -49,71 +51,96 @@ replaced with \fInewValue\fR. This new list is stored in the variable \fIvarName\fR, and is also the return value from the \fBlset\fR command. .PP -If \fIindex\fR is negative or greater than or equal to the number +If \fIindex\fR is negative or greater than the number of elements in \fI$varName\fR, then an error occurs. .PP -.VS 8.5 +If \fIindex\fR is equal to the number of elements in \fI$varName\fR, +then the given element is appended to the list. +.PP The interpretation of each simple \fIindex\fR value is the same as for the command \fBstring index\fR, supporting simple index arithmetic and indices relative to the end of the list. -.VE 8.5 .PP If additional \fIindex\fR arguments are supplied, then each argument is used in turn to address an element within a sublist designated by the previous indexing operation, -allowing the script to alter elements in sublists. The command, +allowing the script to alter elements in sublists (or append elements +to sublists). The command, +.PP .CS -lset a 1 2 newValue +\fBlset\fR a 1 2 newValue .CE +.PP or +.PP .CS -lset a {1 2} newValue +\fBlset\fR a {1 2} newValue .CE +.PP replaces element 2 of sublist 1 with \fInewValue\fR. .PP The integer appearing in each \fIindex\fR argument must be greater than or equal to zero. The integer appearing in each \fIindex\fR -argument must be strictly less than the length of the corresponding -list. In other words, the \fBlset\fR command cannot change the size -of a list. If an index is outside the permitted range, an error is reported. +argument must be less than or equal to the length of the corresponding +list. In other words, the \fBlset\fR command can change the size +of a list only by appending an element (setting the one after the current +end). If an index is outside the permitted range, an error is reported. .SH EXAMPLES +.PP In each of these examples, the initial value of \fIx\fR is: +.PP .CS set x [list [list a b c] [list d e f] [list g h i]] - => {a b c} {d e f} {g h i} + \fI\(-> {a b c} {d e f} {g h i}\fR .CE +.PP The indicated return value also becomes the new value of \fIx\fR (except in the last case, which is an error which leaves the value of \fIx\fR unchanged.) +.PP .CS -lset x {j k l} => j k l -lset x {} {j k l} => j k l -lset x 0 j => j {d e f} {g h i} -lset x 2 j => {a b c} {d e f} j -lset x end j => {a b c} {d e f} j -lset x end-1 j => {a b c} j {g h i} -lset x 2 1 j => {a b c} {d e f} {g j i} -lset x {2 1} j => {a b c} {d e f} {g j i} -lset x {2 3} j => \fIlist index out of range\fR +\fBlset\fR x {j k l} + \fI\(-> j k l\fR +\fBlset\fR x {} {j k l} + \fI\(-> j k l\fR +\fBlset\fR x 0 j + \fI\(-> j {d e f} {g h i}\fR +\fBlset\fR x 2 j + \fI\(-> {a b c} {d e f} j\fR +\fBlset\fR x end j + \fI\(-> {a b c} {d e f} j\fR +\fBlset\fR x end-1 j + \fI\(-> {a b c} j {g h i}\fR +\fBlset\fR x 2 1 j + \fI\(-> {a b c} {d e f} {g j i}\fR +\fBlset\fR x {2 1} j + \fI\(-> {a b c} {d e f} {g j i}\fR +\fBlset\fR x {2 3} j + \fI\(-> list index out of range\fR .CE +.PP In the following examples, the initial value of \fIx\fR is: +.PP .CS set x [list [list [list a b] [list c d]] \e [list [list e f] [list g h]]] - => {{a b} {c d}} {{e f} {g h}} + \fI\(-> {{a b} {c d}} {{e f} {g h}}\fR .CE +.PP The indicated return value also becomes the new value of \fIx\fR. +.PP .CS -lset x 1 1 0 j => {{a b} {c d}} {{e f} {j h}} -lset x {1 1 0} j => {{a b} {c d}} {{e f} {j h}} +\fBlset\fR x 1 1 0 j + \fI\(-> {{a b} {c d}} {{e f} {j h}}\fR +\fBlset\fR x {1 1 0} j + \fI\(-> {{a b} {c d}} {{e f} {j h}}\fR .CE .SH "SEE ALSO" list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), lsort(n), lrange(n), lreplace(n), -.VS 8.5 string(n) -.VE - - .SH KEYWORDS element, index, list, replace, set +'\"Local Variables: +'\"mode: nroff +'\"End: |