147 lines
4.4 KiB
Plaintext
147 lines
4.4 KiB
Plaintext
|
'\"
|
||
|
|
'\" Copyright (c) 2001 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:
|