Tcl Lists

All variables in Tcl are lists. Lists can contain integers (such as list of node IDs), real numbers (such as coordinates of a node), strings, lists of other lists, or a combination of all the above. A standard variable in Tcl is a list of length 1.

A list can be converted to a string when manipulated by string commands, a list can be part of an array, and an array can be converted to and from a list. Regardless of the contents, the means of manipulating lists does not change.

The following list contains some commonly used list manipulation commands and a summary of their usage. For more in-depth explanations and a complete listing, referred to http://www.tcl.tk/man/ or to a Tcl/Tk handbook.

list va11 va12 …: Creates a list from va11 va12 …
lappend listvarname val1 val2 …: Appends val1, val2, etc… as a single entry in the list listvarname. Note that there is no $ before listvarname, as the original list is modified.
lindex $listvarname index: Extracts an entry from a list by referencing its location in the list.
linsert $listvarname index val1 val2 …: Returns a list consisting of the entry or entries contained in val1, val2, etc… inserted into the list listvarname at the position given by index.
llength $listvarname: Returns the number of entries in the list, that is, the length of the list.
lrange $listvarname index1 index2: Extracts a sequential range of entries from a list.
lreplace $listvarname index1 index2 val1 val2 …: Replaces the entries at index1 through index2 with the entries specified by val1, val2, etc…
lsearch ?mode? $listvarname pattern: Returns the index of the first occurrence described by pattern.
lsort ?options? $listvarname: Returns a list with entries sorted according to an array of options.
concat $listvarname1 $listvarname2 …: Joins together multiple lists.
join $listvarname joinstring: Generates a string from a list by combining the list contents using the characters in joinstring.
split $listvarname charset: Creates a list from a string by breaking the string at each occurrence of the characters included in charset.

Indices for lists always begin with 0. Instead of using the index, the last entry can alternatively be referenced by using the special index end, the next to last entry by end-1, etc…

Lists are automatically defined when variable data contains spaces.

set item_list "item1 item2 item3 item4";
item1 item2 item3 item4

To find the length of a list:

llength $item_list;
4

To return a value in a list:

lindex $item_list 0;
item1

lindex $item_list 3;
item4

lindex $item_list end;
item4

lindex $item_list end-1;
item3

To return a range of values from a list:

lrange $item_list 1 3;
item2 item3 item4

Sub-lists are easily created by grouping items in lists with braces, {}. An example using HyperGraph is to create a list of curves for each window on a page.

set page_list "{p1w1c1 p1w1c2 p1w1c3} {p1w2c1 p1w2c2 p1w2c3}";
lindex $page_list 1;
p1w2c1 p1w2c2 p1w2c3

set page2 "[lindex $page_list 1]";
lindex $page2 0;
p1w2c1