list - Create a list http://purl.org/tcl/home/man/tcl8.5/TclCmd/list.htm

list ?arg arg ...?

This command returns a string formatted as a Tcl list, where each list element corresponds to each arg, or an empty string if no args are specified.

---

What is a list? edit

From a usage point of view, a list is an ordered tuple of values; in other languages this is sometimes known as an array or vector. Every list has a length, which is an integer >=0, and the llength command computes the length of any list for you. Every element of the list is identified by its index into the list, which is an integer >=0 and < the list length. To retrieve the element at a particular index one uses the lindex command. New lists can be constructed using the list command. Elements can be appended to a list stored in a variable using the lappend command. (Hence, Tcl lists are not fixed-length once created, as is the case in some other languages.)

From a more technical perspective, a list is just a string with a particular syntax. Therefore, in Tcl, a string is either a valid list or not. The main characteristic of strings that are lists is that literal { and } characters are balanced or escaped, since list commands use them as delimiters around elements. The exact syntax is like that for the words of a Tcl command (see the dodekalogue), but employs only the rules about braces ({ and }), quotes ("), and backslash (\) substitution.

(There is an even more technical perspective, taking into account the implementation in C of Tcl 8.x lists as a type of Tcl_Obj, which has the effect that even though Tcl lists semantically behave as a class of strings, they are not necessarily stored as such in computer memory, but rather as C-style vectors of pointers to the individual element values, plus some extra data. An important consequence of this is that llength and lindex are constant time operations — they are as fast for large lists as they are for small lists.)

How can I operate on lists? edit

Primarily by using the list-commands, which in Tcl are pretty much the commands that begin with l (with load as the only exception): lappend, lassign, lindex, linsert, list, llength, lrange, lrepeat, lreplace, lreverse, lsearch, lset, and lsort. The concat command is fine too (even though it is seldom needed), and foreach is a very important user of lists. split and join are common creators and consumers respectively of lists, but the number of commands that make use of lists in some way is much larger than this.

Since all values (hence also lists) are strings in Tcl, it is always possible to operate on a list with string commands, but doing so is typically a mistake (if not an outright error, then at least inefficient), unless you know what you're doing. The most common mistake is perhaps to compare a list to the empty string to see if it is empty:

  proc foo {bar args} {
     if {$args eq ""} then { # Compares as strings!
        set args $::foo::default_for_args
     }
     # ...
  }

The alternative is to use llength:

  proc foo {bar args} {
     if {![llength $args]} then { # Is $args empty?
        set args $::foo::default_for_args
     }
     # ...
  }

Does Tcl treat lists specially? edit

Tcl, as a general language, does not treat a list differently from other strings. This means it is possible to use lists anywhere one can use arbitrary strings: write to a channel with puts, use as key in an array or dict, show to the user in an entry widget, etc.

HOWEVER, some Tcl functions are written expecting a string formatted as a list as an argument. If those commands are invoked with a string that is not formatted as a list, unexpected results can be expected. Also, Tcl typically keeps track of an "internal representation" of a list that makes it possible to access list elements in O(1) time (access time does not depend on total list length or position within the list).

There are cases in which the C implementation of Tcl treats lists specially, but this is only visible in how fast commands are for suitably prepared data, and must not affect what the results of these commands are. Because of this, there are some common programming idioms which handle lists in not so intuitive ways in order to exploit particular optimisations — perhaps most famously

  eval [list lappend baseList] $listOfElementsToAppend

or even

  eval [linsert $listOfElementsToAppend 0 lappend baseList]

instead of the straightforward

  set baseList [concat $baseList $listOfElementsToAppend]

— but most of those have become obsolete after the introduction of {*} in Tcl 8.5, and now the recommended way to do the above is

  lappend baseList {*}$listOfElementsToAppend

When do I need to care about the string representation of a list? edit

Not very often, but it happens. The most common cases are:

List constants

In some cases, a command accepts a list for an argument, but practically everyone writes that list as an explicit brace-delimited word. This is true for e.g. proc (the arguments command is a list; in fact, it is a list of lists), switch (in the braced patterns-and-bodies form), and string map (the map is a list). These are usually not a problem, but you may need to think about the list syntax when special characters (backslash, braces, whitespace, quotes) are involved. Sometimes, an extra layer of braces are required around a list element, but if it is unbalanced with respect to braces then you may need to backslash-escape all special characters in it instead.

Command construction

Tcl is a dynamic language which lets you construct Tcl scripts at runtime. If there is some piece of variable text in that script (e.g. a user-supplied filename), then you need to "quote" it to make sure Tcl parses it correctly later on. The right way to quote is almost always to feed the string to quote through list and make use of the result from list, even though it is in a "string" context. See Quoting Hell for more information on this.

When is a string not formatted as a list?

A string is not a list if literal (unescaped) { and } characters are not balanced. At this time, the best way to test a string to see if it is a list would be

 set a [list "a" "b" "c"]       ;# or however you get a string into the variable
 if { [catch {llength $a} ] } {
        puts "failed"
 } else {
        puts "succeeded"
 }

When doing experiments to understand these matters, it is a good idea to always put the strings you want to examine into variables before operating on them, since it is hard to keep track of which quoting is interpreted when the command is parsed and which is part of the actual string representation. If you're unsure, you can always use

  set a

to see exactly what string it is that you try to interpret as a list.

What are examples of strings that are not lists, or that are problematic lists?

    set f "ab\{ \{x y"

    set example_due_to_Donal {This might be more excitement than you expected: [exit]}
    
    ... 

How do I force conversion of a string into a list?

Quick answer: Use the split command.

Long answer: It depends on what you mean by "force conversion". If you want some operation with an arbitrary string as input and a list as output, then split will certainly do, but usually when programming it is also relevant what the operation does with its input. If your question is rather "I got some data from a command that returns a string, and now I need to use it as a list, how do I convert it?" then the answer is that you shouldn't need to do anything — since every list is a string, any string used where a list is expected will transparently be parsed as a list, and no explicit conversion step is needed.

In some cases, you may be better using regexp to do the conversion. For example:

set wordList [regexp -all -inline {\S+} $myGnarlyString]

More topics…

Show What is the preferred way to create a list from a string gathered from either a user or an input file?

Show Is there a way to check whether a list element is another list or a simple string?

Show How can I tell the difference between a string and a list?

Show Is a string created with the curly braces { and } around pieces going to be the same as a string created with list?

---

How can one read and write list subsets? edit

LV Question: in Perl, Python, and a number of other languages, one has the ability to read and write to subsets of a list -- slices using an almost array like notation. Is this something that one could simulate without much grief in Tcl?

RS But of course - our old friends (with wordier notation)

 set slice [lrange $list $from $to]
 set newlist [eval lreplace [list $otherlist] $from $to $slice]

The new lset can only replace a single element, but possibly several layers deep in the nesting. For reading access to a slice of a list, check Salt and sugar for how the following is implemented:

         set i [$ {a b c d e f g} 2 4] ==> {c d e}

---

How do I flatten a list of lists into just a list? edit

LV: I recently had a need to turn a list which could potentially contain elements which are lists into a list of individual elements. Apparently, this is commonly referred to as flattening the list. [ericm] suggested the following code to solve the problem:

        proc flatten {args} { 
          foreach arg $args {puts $arg} 
        } 
        set foo [list [list a b] [list c d] [list e f]] 
        eval eval flatten $foo 

Show discussion

AMG: Here's another way to remove one level of nesting:

 concat {*}$nested

It can be applied multiple times:

 proc flatten {data} {concat {*}$data}
 set a {{a {b c}} {d {e f}}}  ; # {a {b c}} {d {e f}}
 flatten $a                   ; # a {b c} d {e f}
 flatten [flatten $a]         ; # a b c d e f

There shouldn't be any type shimmering involved. Right?

Show discussion

---

Information about struct::list - extended list operations edit

Tcllib now contains a struct::list module. Its documentation can be found at http://tcllib.sourceforge.net/doc/struct_list.html . dgp offers this example of making use of it:

 % package require struct 1.3
 1.3
 % namespace eval my {
    namespace import ::struct::list
    set l [::list 1 2 3]
    puts [list reverse $l]
 }
 3 2 1

Show  More explanation…

---

What would a Tcl version of the list command look like? edit

AMG: Is this an acceptable implementation of [list]?

 proc list {args} {return $args}

Looks right to me... - RS To me too. That's because args is already a list, as by the Tcl parser... I'd just write

 proc list args {set args}

AMG: Chuckle.

 proc list args [list set args]

---

Transform a list into a list of fixed size lists edit

Show discussion

---

Other related topics edit

caspian recommends that you see Tcl list related commands such as: lappend, lassign, lindex, linsert, llength, lrange, lrepeat, lreplace, lreverse, lsearch, lset, lsort, concat, foreach, join, split, string (and in particular, string is list), apply, expr

Some Tcl core commands require lists as argument or return lists - after, array, binary. chan, dde, dict, oo::define, oo::next, encoding, exec, fconfigure, file, glob, [htt], info, interp, library, msgcat, namespace, open, package, packagens, pid, pkgMkIndex, platform, proc, read, oo::refchan, regexp, registry, return, safe, scan, oo::self, socket, switch, tcltest, tm, trace,

---

Making lists with list vs lappend edit

Show discussion

---

Other uses of [list] edit

Show discussion

---

See also: edit

• Sorted Lists
• Concatenating lists
• Listex
• list level
• Additional list functions
• another list comprehension
• Binary trees, Decision trees
• Bit vectors can nicely be implemented with lists
• Chart of existing list functionality
• Chart of proposed list functionality
• Complex data structures for struct: named access to list positions
• Counting Elements in a List
• Internal organization of the list extension
• keyed list
• Power set of a list
• pure list
• Showing sublists in a listbox
• Shuffle a list - Shuffle a list: graph results - Shuffling a list
• Shuffling a list
• Stacks and queues
• Striding a list
• Summing a list
• Use while to iterate over a list
• Using expr on lists
• lshift -Adding Unique Items to Lists of Fixed Length
• Recursive list searching
• listcomp -Compare the Contents of two Lists
• Depth of a list
• list map and list grep
• set operations for Tcl lists
• List Comprehension
• linked lists
• Cartesian product of a list of lists
• list stripping
• string is list
• lpop

---

---