You can use lindex and lrange to retrieve one or more elements from a list. If you use lindex, the typical behavior is to specify an index value to retrieve. However, as you can see from its syntax diagram, the index value to fetch is optional. If you omit index, lindex returns the value of the list. Otherwise, lindex returns the element that corresponds to the specified index. For example, consider the following script:

set faceCards [list Ace King Queen Jack]
puts [lindex $faceCards 1]
puts [lindex $faceCards]

Executed (see lindex.tcl in this chapter’s code directory), the output of this script should be:

$ ./lindex.tcl
King
Ace King Queen Jack

So, lindex makes it possible to retrieve either a single list element or the entire list. If you request an index greater than the number of elements in the list or less than zero, lindex returns an empty string.

If you specify multiple indices, each index except for the last one returns a sublist of listVar. The last index value is the one that returns an actual list element. Before I explain what that means in more detail, let me show you an example (cards.tcl in this chapter’s code directory):

# Return a random integer between 0 and the number of elements in
# the list specified by cardList
proc Random {list} {
    set index [expr {int(1 + rand() * ([llength $list]) - 1)}]    return $index
}

set values [list Ace King Queen Jack 10 9 8 7 6 5 4 3 2]
set suits [list Clubs Diamonds Hearts Spades]
lappend cards $values $suits

# "Deal" a draw poker hand
for {set i 1} {$i <= 5} {incr i} {
    puts "Card $i: [lindex $cards 0 [Random $values]] of
        [lindex $cards 1 [Random $suits]]"
}

When you execute this script, the output will be a (reasonably) random hand of draw poker:

$ ./cards.tcl
Card 1: Queen of Diamonds
Card 2: 3 of Diamonds
Card 3: 9 of Spades
Card 4: 10 of Hearts
Card 5: 5 of Diamonds

Yes, this poker hand is a loser. To understand how multi-valued index arguments work, consider the first lindex command in the example, [lindex $cards 0 [Random $values]]. Next, break it down into its components. $cards is the list variable from which I want to extract a value. $cards is a two-element list; the first element is the sublist $values ({Ace King Queen Jack 10 9 8 7 6 5 4 3 2}), and the second element is the sublist, $suits ({Clubs Diamonds Hearts Spades}).

The index values are 0 and the return value of the procedure, [Random $values]. As you can see from the comment above its definition, my Random procedure returns a random integer between 0 and the number of elements in the list passed to it. I only specified two indices, which means that the first index, 0, selects the sublist from which the second index, the return value of [Random $values], selects the desired element.

Given that the sublist of $cards at index 0 is {Ace King Queen Jack 10 9 8 7 6 5 4 3 2}, if [Random $values] returns 2, then the entire expression evaluates to King. To express it another way, the command, [lindex $cards 0 [Random $values]] is equivalent to and a more concise way of writing the following commands:

set sublist [lindex $cards 0]
set index [Random $values]
set suit [lindex $sublist $index]

I readily concede that specifying multi-valued indices to lindex is confusing. Using multivalued indices is most appropriate when you are working with nested lists, that is, lists containing elements that are themselves lists. If you are more comfortable using multiple commands to achieve the same result, do so. As you grow more comfortable with Tcl, it will become more natural to use multi-valued indices. More importantly, you might encounter such expressions in other people’s Tcl code, so you’ll need to be able to parse and understand such code, even if you don’t like it or use it yourself.

Happily, the command to return multiple consecutive elements from a list, lrange, is much less subtle than lindex. By way of reminder, lrange’s syntax is:

lrange listVar start end

start and end indicate the first and last indices, respectively, of the values which lrange should return. lrange returns a new list that consists of the elements between start and end, inclusive. Consider the following short script (lrange.tcl in this chapter’s code directory):

set values [list Ace King Queen Jack 10 9 8 7 6 5 4 3 2]
set suits [list Clubs Diamonds Hearts Spades]

puts [lrange $values 5 8]
puts [lrange [list $values $suits] 1 2]

The output should resemble the following:

$ ./lrange.tcl
9 8 7 6
{Clubs Diamonds Hearts Spades}

The first lrange command returns the elements between indices 5 and 8 (remember, list indices are zero-based). The second lrange returns the elements between indices 1 and 2 of the two-element list created by the embedded list command. However, because there is no index 2 (that is, no third element), lrange treats that value as if it were end, which refers to the last element in the list. Similarly, if the starting index is less than zero, lrange will treat it as if it were 0 and return the first element in the list.

To insert one or more elements into a list at a specific location, use the linsert command. Its syntax is:

linsert listVar index item ?item ...?

This command inserts each new element (denoted by item) into the list specified by listVar immediately before the index specified by index. listVar itself is not modified. Rather, linsert returns a new list with the inserted values. If index is less than zero, the new elements will be inserted at the beginning of the list (at index 0); if greater than the number of elements in the list, the new elements will be appended to the end of the list. You can specify the end of the list using the special index value end.

The following example demonstrates linsert usage (see linsert.tcl in this chapter’s code directory):

set oldList [list 1 2 3 4 5]
set newList [linsert $oldList 0 0]
set newerList [linsert $newList 2 2.5]
set newestList [linsert $newerList [expr [llength $newerList] + 1] 6]

puts "oldList   : $oldList"
puts "newList   : $newList"
puts "newerList : $newerList"
puts "newestList: $newestList"

The second linsert command inserts the element 0 at the front of the list. The third linsert command inserts the element 2.5 in the middle of the list (before index 2). The final linsert command adds the element 6 to the end of the list. In this command, I deliberately set the insertion index to a value greater than the length of the list ([expr [llength $newerList] + 5] evaluates to 10) to show how linsert treats an index value greater than the length of the list.

If you execute this script, the output should match the following:

$ ./linsert.tcl
oldList   : 1 2 3 4 5
newList   : 0 1 2 3 4 5
newerList : 0 1 2.5 2 3 4 5
newestList: 0 1 2.5 2 3 4 5 6

Notice that the source lists, the lists passed to linsert as arguments, are not modified.

To replace one or more list elements with new ones, use the lreplace command. Its syntax is:

lreplace listVar start end ?item ...?

lreplace returns a new list created by replacing the element or elements between index values start and end in listVar with the elements specified by item. Omitting item has the effect of deleting the corresponding element from the list. If you specify fewer items than there are indices between start and end, the excess elements in listVar will be deleted from the returned list. Similarly, specifying more items than there are indices results in inserting the extra elements following the last replaced item, effectively expanding the list at that point. As with other list commands, if start is less than zero, it will be treated like zero. If end is less than start, all of the specified elements will be inserted at the beginning of the list without replacing existing list elements. Finally, if the list specified by listVar is empty, all of the specified items will be appended to the list. Despite all of the niggling evaluation rules, lreplace behaves the way you would expect it to. The following trivial example illustrates simple lreplace usage (see lreplace.tcl in this chapter’s code directory).

set oldList [list 1 2 3 4 5]

set newList [lreplace $oldList 0 end one two three four five six]

puts "Original list: $oldList (length: [llength $oldList])"
puts "Replaced list: $newList (length: [llength $newList]);"

lsearch’s general syntax is:

lsearch ?option ...? listVar pattern

lsearch searches each element of listVar for a match with the specified pattern. It returns the index of the first matching element by default or -1 if there are no matches. The option arguments control how the match is performed and the nature of lsearch’s return value. The only default option is -glob, which forces a glob-style match using the same rules as the string match command (described in Chapter 4). Table 5.1 lists the permissible options.

Don’t let the number of options intimidate you. Most of them have to be used in combination with -sorted to even apply. You can perform three types of searches:

By default, lsearch returns the index of the first match. If you want the index values of all matches, specify -all and lsearch will return a list of matches. If you want the elements themselves rather than their indices, specify -inline. Again, unless you also specify -all, -inline will return only the first match. Finally, to start the search at a specific index, rather than at the beginning of the list, specify -start index, where index is the index value at which to commence the search.

The balance of the options assume sorted search input, specified with -sort. Why does this matter? As an optimization, if lsearch knows the input is sorted, it can use a search algorithm best suited to the input rather than a general purpose, one-size-fits-all search algorithm. The most interesting option is -not, which inverts the sense of the search and returns the first non-matching index or value (or all of them if you also specify -all).

Tip: Sort Before Searching

If you need to search a long list, make sure it is sorted first. lsearch does not sort unsorted lists, so you can improve search speed by sorting the list (using lsort) before passing it to lsearch.

I could spend an entire chapter on lsearch alone and not even talk about the -regexp search option. I encourage you to experiment with lsearch and its options to get a better sense of what it can do. To help you out in that respect, programs you encounter later in this book will use a number of lsearch’s options, so you will definitely get plenty of lsearch goodness. In the meantime, the following script illustrates basic lsearch usage:

# Create a list of cards
set cards [list "Queen of Hearts" "3 of Clubs" "9 of Spades" 
    "Ace of Hearts" "5 of Diamonds"]

# Ask user for what to search
puts -nonewline "Card for which to search (such as King, Spade, or 9): "
flush stdout
gets stdin card

# Loop until user inputs a matching card
while {[set index [lsearch $cards *[string totitle $card]*]] < 0} {
    puts "No such card. Please try again."
    puts -nonewline "Card for which to search (such as King, Spade, or 9): "
    flush stdout    gets stdin card
}

# Show the match
puts "Matched the [lindex $cards $index]"

This script creates a list of five cards, asks the user to enter some text that describes a card for which to search, and then searches the list for that card. The prompt-search routine repeats until lsearch finds a match. Upon finding a match, the while loop terminates and the script displays the matching card. Here’s how the output might look (see lsearch.tcl in this chapter’s code directory):

$ ./lsearch.tcl
Card for which to search (such as King, Spade, or 9): 4
No such card. Please try again.
Card for which to search (such as King, Spade, or 9): King
No such card. Please try again.
Card for which to search (such as King, Spade, or 9): queen
Matched the Queen of Hearts

I used the string totitle command to uppercase the first letter of the user’s input. The search pattern, rather, the search glob, is stored in the $card variable. To allow matches to occur in the middle of an element, I added * to the beginning and end of the search pattern so the glob would match the pattern, regardless of where in the element the pattern appears. Finally, notice the loop termination condition. lsearch returns -1 if it doesn’t find a match, so the test condition simply checks for a return value that is less than zero. Obviously, you could check for -1, too.

Tip: On Naming Variables

In lsearch.tcl, I used the plural noun $cards to refer to the list of cards as a whole and the singular noun $card to denote a specific card. This is a convention, or idiom, I use frequently. Most, if not all of my variable names are nouns because, based on my own experience, the “things” that variables represent are usually nouns. When I need to refer to collections (you know, collections like lists) of related values or items, I use the plural form of the noun, such as cards, books, dice, games, and so on. When I need to refer to a particular member or instance of that collection, I use the singular form of the noun (card, book, die, game). The reason I do this is that I can determine at a glance what a variable is and how I’m using it.

You probably noticed that a number of lsearch’s options involved searching a sorted list. Searching for something, in code and in real life, is much more efficient if the material you’re searching is already sorted. To accomplish this in Tcl, use the lsort command. Its general syntax is:

lsort ?options? listVar

lsort sorts listVar and returns a new sorted list. options control how the sort is performed. Not surprisingly, lsort and lsearch share a number of options. Table 5.2 lists lsort’s options, with bold items representing the defaults when no options are specified.

A dictionary sort is handy when the list elements contain mixed alphanumeric values, such as a10 and a2. In the standard (-ascii) sort, a10 would sort before a2 because the first two characters of a10, a1, are “less than” a2. With a -dictionary sort, the numbers are treated as integers, so a2 would sort before a10 because 2 is less than 10.

The -index option needs elaboration. It exists to handle properly sorting lists that consist of sublists. When specified, -index index performs the sort by sorting the list as a whole on the indexth element of each sublist. For example, given the following list of cards, the default sort is by the card value, that is, by index 0:

% lsort {{King of Diamonds} {Ace of Hearts} {10 of Clubs}}
{10 of Clubs} {Ace of Hearts} {King of Diamonds}

If you want to sort by suit, use the option -index 2 to sort by the third element of each sublist:

% lsort -index 2 {{King of Diamonds} {Ace of Hearts} {10 of Clubs}}
{10 of Clubs} {King of Diamonds} {Ace of Hearts}

The -unique option is a great way to eliminate duplicates from a list. However, it has a subtlety that might bite you if you also specify -index. If you are sorting a list of sublists, the default sort is to sort by each element of each sublist. If you specify -index and - unique and your list contains two sublists with the same element at the same index, only the last one will appear in the sorted list, regardless of the values of the rest of the elements. To illustrate, compare the results of the following three commands:

% lsort -unique {{King of Hearts} {King of Diamonds} {2 of Clubs}
{2 of Clubs} {King of Diamonds} {King of Hearts}
% lsort -unique -index 0 {{King of Hearts} {King of Diamonds} {2 of Clubs}}
{2 of Clubs} {King of Diamonds}
% lsort -unique -index 1 {{King of Hearts} {King of Diamonds} {2 of Clubs}}
{2 of Clubs}

The first lsort command shows the default behavior. The second one shows the result if you sort the list on index 0 alone: the resulting list drops the second King (the King of Hearts). As a pathological example, the third lsort sorts on index 1 (the word of in each sublist), which results in dropping the Kings from the sorted list.

The following script, lsort.tcl in this chapter’s code directory, shows a simple example of lsort’s usage. It uses the rand() function to generate a list of five random numbers and then lsort to sort them, displaying both the unsorted and sorted lists.

# Generate a list of 5 floating point numbers
for {set i 0} {$i < 5} {incr i} {
    lappend floats [expr rand()]
}

puts "Unsorted list:"
foreach float $floats {
    puts "	$float"
}

set s_floats [lsort -real $floats]

puts "
Sorted list:"
foreach s_float $s_floats {
    puts "	$s_float"
}

The only remarkable feature here is that I use the -real option to force the sort to be performed using floating-point comparisons rather than the default Unicode comparisons. Well, I also used the foreach looping command about which you’ll read shortly. When you execute this script, you should see output resembling the following (of course, the list elements will differ):

$ ./lsort.tcl
Unsorted list:
    0.95407820258
    0.192350764383
    0.839296981617
    0.0643700450027
    0.867346360752
Sorted list:
    0.0643700450027
    0.192350764383
    0.839296981617
    0.867346360752
    0.95407820258

Given a string that you want to convert to a Tcl list, the split command makes short work of the task. Its syntax is:

split $string ?chars?

split returns a list created by breaking string into elements at each occurrence of the split characters specified in chars. If you omit chars, the default split character is whitespace. Yes, you can specify multiple split characters in chars. Each occurrence of adjacent or consecutive char results in an empty list element. split also generates an empty list element if the first or last character of string matches a split character.

The following command breaks the sentence “A straight flush beats a full house.” into a list consisting of each word in the sentence:

set words [split $sentence]

If, perversely, you want to break the sentence at, say, the letters a and s, the following command would do:

set words [split $sentence {as}]

Here is the output of both commands. (See split.tcl in this chapter’s code directory.) Notice that the result of the second split command is grouped with braces. This occurs because the resulting list elements contain embedded whitespace, the default list separator. Tcl does this to protect the spaces and maintain the integrity of the resulting list.

$ ./split.tcl
A straight flush beats a full house.
{A } tr {ight flu} {h be} t { } { full hou} e.

Be careful when using split on arbitrary input because stray double quotes or braces will cause an error (see bad_split.tcl in this chapter’s code directory):

% puts [split "A straight {flush "beats a full house."]
extra characters after close-quote

Tip: Breaking Strings into One-Character Lists

If you want to convert a string into a list of single-character elements, specify the empty list, {}, as the split character:

% split {Lots of characters} {}
L o t s { } o f { } c h a r a c t e r s

As you can see, split is a command that is easy to understand and use, as well as being capable and powerful.

Note: You Don’t Always Need split

In many situations, you don’t need to use split to make a list. A string is a list and a list is a string. For example, you can use the list operation lindex on the string “A straight flush beats a full house.” without first using split. In fact, history buffs might appreciate the fact that the string length command was added to eliminate the hack of using llength on a string to test whether or not the string was empty.

join performs the inverse operation of split, converting a list into a string and return the new string. join’s syntax is:

join listVar ?chars?

join works by converting each element of listVar in a string, with each element separated by the character or characters specified by chars. As with the split command, chars can be a list of multiple characters. For example, in the following example (join.tcl in this chapter’s code directory), the first join command splits the list into a single string whose words are separated by newlines, and the second one creates a string whose values are separated by a comma and a space:

% join {Ace King Queen Jack 10} "
"
Ace
King
Queen
Jack
10
% join {{A a} {B b} {C c} d E} ", "
A a, B b, C c, d, E

In the second command, the embedded sublists, such as {A a}, were not joined into strings; join only strips off a single level of list structure.

You’ve already seen the procedure, Random, at the top of the script (refer to the cards.tcl script in the section titled “Accessing Specific List Elements”). It generates a random number between 0 and the number of elements in a list. I use this procedure in Blocks 2 and 3 to deal a reasonably random card. Block 1 just creates a “deck” of cards out of which the script will deal cards—you saw this card in cards.tcl, too. So far, nothing new.

In Block 2, I deal the first two cards, storing them in the list variable named cards. The foreach loop sets the stage for the rest of the game by displaying the player’s initial hand of cards.

The game gets going in Block 3. Now that the user has had a chance to examine his cards, I use the standard input sequence I’ve used throughout the first few chapters of this book to ask the user if he would like another card. If the user types “n,” control moves to the code in Block 4. Otherwise, control enters the while loop, which:

The while loop continues until the user types “n.” Notice the use of string tolower to make sure that the user can type “y” or “Y” for yes. Another feature of the while loop is the prompt itself. Because I need literal [ and ] characters, I have to escape them using backslashes. Without the escapes, the interpreter would try to execute a command or procedure named yn and would generate an error that aborts the script.

After all the cards have been dealt in Block 3, Block 4 scores the hand. I use a foreach loop to iterate through the cards list and assign a score to each card using a switch command. The -glob option was necessary because each card has both a denomination (such as Ace or 8) and a suit. For example, the glob pattern Ace* matches “Ace of Spades,” “Ace of Clubs,” and so forth. The score for each card is stored in the variable value, which is added to the total score, stored in the variable score, at the bottom of the loop.

The scores for Ace and 10 are obvious, but the handling of the other face cards and of the other numeric cards is a little trickier. The command body for a King, Queen, or Jack is -. This means that the body for the following pattern should be used for this pattern. The idea is to share command bodies among several patterns. In this case, the command body for a pattern of 10 will be used for patterns that match King*, Queen*, Jack*, and, of course, 10*. In effect, a body of – allows execution to fall through to a common body.

For the numeric cards, I score them by setting value to the numeric component of the list element (the numeric cards look like “3 of Clubs” or “8 of Spades”). I extract the numeric component using the command lindex $card 0. Once again, you see how nested commands and command substitution make it possible, even trivial, to build powerful compound commands with a minimum of code.

After adding the score of the current card to the total score, the scoring process continues with the next element of the list/card in the user’s hand. When all cards have been scored, Block 5 displays the score along with a short message and the script exits.

Here are some exercises you can try to practice what you learned in this chapter.

Lists are one of Tcl’s two native data structures. The Blackjack game illustrates some of what Tcl’s list-related functionality makes possible. Given data that lends itself to arrangement in a list, Tcl has commands for creating the list, accessing particular list elements, sorting the entire list or only part of it, searching a list for elements that match certain criteria, and adding, deleting, or modifying list elements. In addition, you can convert between lists and strings with the split and join commands. The foreach loop control structure is specifically designed to iterate over lists, and you can even control loop execution by using the break and continue commands. In the next chapter, you’ll learn how to use Tcl’s other native data structure, the array.