Import Tcl-core 8.6.6 (as of svn r86089)

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: