---
name: "lset"
section: "3tcl"
platform: "linux"
package: "tcl8.6-doc"
version: "8.6.16+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/lset"
---

# lset(3tcl)

Change an element in a list

```

```

## NAME

lset - Change an element in a list

## SYNOPSIS

**lset** *varName ?index ...? newValue*

```

```

## DESCRIPTION

The **lset** command accepts a parameter, *varName*, which it interprets as the name of a variable containing a Tcl list. It also accepts zero or more *indices* 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 *varName*.

If no indices are presented, the command takes the form:

```
lset varName newValue
```

or

```
lset varName {} newValue
```

In this case, *newValue* replaces the old value of the variable *varName*.

When presented with a single index, the **lset** command treats the content of the *varName* variable as a Tcl list. It addresses the *index*'th element in it (0 refers to the first element of the list). When interpreting the list, **lset** 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 *newValue*.  This new list is stored in the variable *varName*, and is also the return value from the **lset** command.

If *index* is negative or greater than the number of elements in *$varName*, then an error occurs.

If *index* is equal to the number of elements in *$varName*, then the given element is appended to the list.

The interpretation of each simple *index* value is the same as for the command **string index**, supporting simple index arithmetic and indices relative to the end of the list.

If additional *index* 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,

```
lset a 1 2 newValue
```

or

```
lset a {1 2} newValue
```

replaces element 2 of sublist 1 with *newValue*.

The integer appearing in each *index* argument must be greater than or equal to zero.  The integer appearing in each *index* argument must be less than or equal to the length of the corresponding list.  In other words, the **lset** 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.

## EXAMPLES

In each of these examples, the initial value of *x* is:

```
set x [list [list a b c] [list d e f] [list g h i]]
      → {a b c} {d e f} {g h i}
```

The indicated return value also becomes the new value of *x* (except in the last case, which is an error which leaves the value of *x* unchanged.)

```
lset x {j k l}
      → j k l
lset x {} {j k l}
      → j k l
lset x 0 j
      → j {d e f} {g h i}
lset x 2 j
      → {a b c} {d e f} j
lset x end j
      → {a b c} {d e f} j
lset x end-1 j
      → {a b c} j {g h i}
lset x 2 1 j
      → {a b c} {d e f} {g j i}
lset x {2 1} j
      → {a b c} {d e f} {g j i}
lset x {2 3} j
      → list index out of range
```

In the following examples, the initial value of *x* is:

```
set x [list [list [list a b] [list c d]] \
            [list [list e f] [list g h]]]
      → {{a b} {c d}} {{e f} {g h}}
```

The indicated return value also becomes the new value of *x*.

```
lset x 1 1 0 j
      → {{a b} {c d}} {{e f} {j h}}
lset x {1 1 0} j
      → {{a b} {c d}} {{e f} {j h}}
```

## SEE ALSO

[list(3tcl)](/list/3tcl.md), [lappend(3tcl)](/lappend/3tcl.md), [lindex(3tcl)](/lindex/3tcl.md), [linsert(3tcl)](/linsert/3tcl.md), [llength(3tcl)](/llength/3tcl.md), [lsearch(3tcl)](/lsearch/3tcl.md), [lsort(3tcl)](/lsort/3tcl.md), [lrange(3tcl)](/lrange/3tcl.md), [lreplace(3tcl)](/lreplace/3tcl.md), [string(3tcl)](/string/3tcl.md)

## KEYWORDS

element, index, list, replace, set