1lset(n)                      Tcl Built-In Commands                     lset(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       lset - Change an element in a list
9

SYNOPSIS

11       lset varName ?index ...? newValue
12______________________________________________________________________________
13

DESCRIPTION

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
22       If no indices are presented, the command takes the form:
23
24              lset varName newValue
25
26       or
27
28              lset varName {} newValue
29
30       In this case, newValue replaces the old value of the variable varName.
31
32       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
42       If index is negative or greater than the number of  elements  in  $var‐
43       Name, then an error occurs.
44
45       If index is equal to the number of elements in $varName, then the given
46       element is appended to the list.
47
48       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
52       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
57              lset a 1 2 newValue
58
59       or
60
61              lset a {1 2} newValue
62
63       replaces element 2 of sublist 1 with newValue.
64
65       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

EXAMPLES

73       In each of these examples, the initial value of x is:
74
75              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
78       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
82              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
101       In the following examples, the initial value of x is:
102
103              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
107       The indicated return value also becomes the new value of x.
108
109              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

SEE ALSO

115       list(n), lappend(n),  lindex(n),  linsert(n),  llength(n),  lsearch(n),
116       lsort(n), lrange(n), lreplace(n), string(n)
117

KEYWORDS

119       element, index, list, replace, set
120
121
122
123Tcl                                   8.4                              lset(n)
Impressum