lset(3tcl)

📦
version 9.0.4 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 lset — the glow-up command for your lists 💖

ok so we're talking about lset, a built-in Tcl command, bestie. it's the one that lets you reach into a list, poke one little element, and swap it out for something new. no cap.

✨ NAME ✨

lset — change an element in a list 🎀

🌸 SYNOPSIS 🌸

lset varName ?index ...? newValue

🦋 DESCRIPTION 🦋

okok so here's the tea. lset takes a parameter, varName, and it's like "yes queen, this is the name of a variable holding a Tcl list." 💅 then it also accepts zero or more indices pointing into that list. those indices can show up two ways:

  • lined up one after another right there on the command line, or
  • all grouped together in a Tcl list and handed over as one single argument.

and finally it takes a newValue for one element of varName. periodt.

no indices? no problem 🫶

if you present no indices at all, the command looks like this:

lset varName newValue

or

lset varName {} newValue

in that case, newValue straight-up replaces the old value of the variable varName. like, total main character takeover.

one index, one glow-up ⭐

when you give it a single index, lset treats the content of the varName variable as a Tcl list. it addresses the index'th element in it — and reminder bestie, 0 refers to the first element of the list. 🔥

when it's interpreting that list, lset observes the same rules concerning braces, quotes and backslashes as the Tcl command interpreter does. however — and this is important — variable substitution and command substitution do not occur. nope, not happening.

the command constructs a new list where the designated element is replaced with newValue. that new list gets stored in the variable varName, and it's also the return value from the lset command. double duty, iconic. 👑

the index rules (read this part fr fr) 📏

  • 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. slay.
  • 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. iykyk.

multiple indices = going deeper 🧚

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. that lets your script alter elements in sublists — or append elements to sublists. nesting hours. ✨

the command:

lset a 1 2 newValue

or

lset a {1 2} newValue

replaces element 2 of sublist 1 with newValue. see how both forms do the exact same thing? cute.

the boundaries, bestie 🚧

  • 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 only change the size of a list 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
      → {a b c} {d e f} {g h i j}
lset x {2 4} 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 🌈

💫 KEYWORDS 💫

element, index, list, replace, set

ok that's the whole page, bestie 🫶 this one's from the Tcl 8.4 era, so go forth and glow up your lists responsibly. mwah 💋 🎀

📦 where this page comes from