diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2017-09-22 18:57:19 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2017-09-22 18:57:19 (GMT) |
commit | 2aff4a96fa0286d875bddec0019648e2c6431cbc (patch) | |
tree | f7a9a4800a3f3ad4b77470b8383529176d8b7181 /tcl8.6/doc/lset.n | |
parent | 3fa8e6dc88e8041b6cb88d1b1e9c05676d3346b7 (diff) | |
parent | 29ccecd87709feda60d191f6aaba324ccad91f55 (diff) | |
download | blt-2aff4a96fa0286d875bddec0019648e2c6431cbc.zip blt-2aff4a96fa0286d875bddec0019648e2c6431cbc.tar.gz blt-2aff4a96fa0286d875bddec0019648e2c6431cbc.tar.bz2 |
Merge commit '29ccecd87709feda60d191f6aaba324ccad91f55' as 'tcl8.6'
Diffstat (limited to 'tcl8.6/doc/lset.n')
-rw-r--r-- | tcl8.6/doc/lset.n | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/tcl8.6/doc/lset.n b/tcl8.6/doc/lset.n new file mode 100644 index 0000000..e425274 --- /dev/null +++ b/tcl8.6/doc/lset.n @@ -0,0 +1,146 @@ +'\" +'\" 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. +'\" +.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 +.BE +.SH DESCRIPTION +.PP +The \fBlset\fR command accepts a parameter, \fIvarName\fR, which +it interprets as the name of a variable containing a Tcl list. +It also accepts zero or more \fIindices\fR into +the list. The indices may be presented either consecutively on the +command line, or grouped in a +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 +\fBlset\fR varName newValue +.CE +.PP +or +.PP +.CS +\fBlset\fR varName {} newValue +.CE +.PP +In this case, \fInewValue\fR replaces the old value of the variable +\fIvarName\fR. +.PP +When presented with a single index, the \fBlset\fR command +treats the content of the \fIvarName\fR variable as a Tcl list. +It addresses the \fIindex\fR'th element in it +(0 refers to the first element of the list). +When interpreting the list, \fBlset\fR observes the same rules +concerning braces and quotes and backslashes as the Tcl command +interpreter; however, variable +substitution and command substitution do not occur. +The command constructs a new list in which the designated element is +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 the number +of elements in \fI$varName\fR, then an error occurs. +.PP +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. +.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 (or append elements +to sublists). The command, +.PP +.CS +\fBlset\fR a 1 2 newValue +.CE +.PP +or +.PP +.CS +\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 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]] + \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 +\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]]] + \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 +\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), +string(n) +.SH KEYWORDS +element, index, list, replace, set +'\"Local Variables: +'\"mode: nroff +'\"End: |