summaryrefslogtreecommitdiffstats
path: root/doc/lset.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/lset.n')
-rw-r--r--doc/lset.n50
1 files changed, 34 insertions, 16 deletions
diff --git a/doc/lset.n b/doc/lset.n
index c191ebf..954bd30 100644
--- a/doc/lset.n
+++ b/doc/lset.n
@@ -11,7 +11,7 @@
.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
@@ -24,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
@@ -47,42 +51,53 @@ 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]]
\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
@@ -103,13 +118,17 @@ The indicated return value also becomes the new value of \fIx\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
@@ -119,10 +138,9 @@ The indicated return value also becomes the new value of \fIx\fR.
.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: