1lset(n) Tcl Built-In Commands lset(n)
2______________________________________________________________________________
6
8 lset - Change an element in a list
9
11 lset varName ?index ...? newValue
12______________________________________________________________________________
13
15 The lset command accepts a parameter, varName, which it interprets as
16 the name of a variable containing a Tcl list. It also accepts zero or
17 more indices into the list. The indices may be presented either con‐
18 secutively on the command line, or grouped in a Tcl list and presented
19 as a single argument. Finally, it accepts a new value for an element
20 of varName.
21 If no indices are presented, the command takes the form:
23 lset varName newValue
25 or
27 lset varName {} newValue
29 In this case, newValue replaces the old value of the variable varName.
31 When presented with a single index, the lset command treats the content
33 of the varName variable as a Tcl list. It addresses the index'th ele‐
34 ment in it (0 refers to the first element of the list). When inter‐
35 preting the list, lset observes the same rules concerning braces and
36 quotes and backslashes as the Tcl command interpreter; however, vari‐
37 able substitution and command substitution do not occur. The command
38 constructs a new list in which the designated element is replaced with
39 newValue. This new list is stored in the variable varName, and is also
40 the return value from the lset command.
41 If index is negative or greater than the number of elements in $var‐
43 Name, then an error occurs.
44 If index is equal to the number of elements in $varName, then the given
46 element is appended to the list.
47 The interpretation of each simple index value is the same as for the
49 command string index, supporting simple index arithmetic and indices
50 relative to the end of the list.
51 If additional index arguments are supplied, then each argument is used
53 in turn to address an element within a sublist designated by the previ‐
54 ous indexing operation, allowing the script to alter elements in sub‐
55 lists (or append elements to sublists). The command,
56 lset a 1 2 newValue
58 or
60 lset a {1 2} newValue
62 replaces element 2 of sublist 1 with newValue.
64 The integer appearing in each index argument must be greater than or
66 equal to zero. The integer appearing in each index argument must be
67 less than or equal to the length of the corresponding list. In other
68 words, the lset command can change the size of a list only by appending
69 an element (setting the one after the current end). If an index is
70 outside the permitted range, an error is reported.
71
73 In each of these examples, the initial value of x is:
74 set x [list [list a b c] [list d e f] [list g h i]]
76 → {a b c} {d e f} {g h i}
77 The indicated return value also becomes the new value of x (except in
79 the last case, which is an error which leaves the value of x un‐
80 changed.)
81 lset x {j k l}
83 → j k l
84 lset x {} {j k l}
85 → j k l
86 lset x 0 j
87 → j {d e f} {g h i}
88 lset x 2 j
89 → {a b c} {d e f} j
90 lset x end j
91 → {a b c} {d e f} j
92 lset x end-1 j
93 → {a b c} j {g h i}
94 lset x 2 1 j
95 → {a b c} {d e f} {g j i}
96 lset x {2 1} j
97 → {a b c} {d e f} {g j i}
98 lset x {2 3} j
99 → list index out of range
100 In the following examples, the initial value of x is:
102 set x [list [list [list a b] [list c d]] \
104 [list [list e f] [list g h]]]
105 → {{a b} {c d}} {{e f} {g h}}
106 The indicated return value also becomes the new value of x.
108 lset x 1 1 0 j
110 → {{a b} {c d}} {{e f} {j h}}
111 lset x {1 1 0} j
112 → {{a b} {c d}} {{e f} {j h}}
113
115 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
116 lsort(n), lrange(n), lreplace(n), string(n)
117
119 element, index, list, replace, set
120Tcl 8.4 lset(n)