:TITLE: Adding & Deleting members of a list ;# ;# RCSID: $Header: /cvsroot/tcl/tcltutorial/original/Tcl15.lsn,v 1.1 2004/11/04 16:01:13 davidw Exp $ ;# Copyright (c) 1995 Clif Flynt ;# 9300 Fleming Rd. ;# Dexter, MI 48130 ;# clif@cflynt.com ;# See file "NOTICE" for licensing terms. ;# :LESSON_TEXT_START_LEVEL 0: The commands for adding and deleting list members are:

concat ?arg1 arg2 ... argn?: Concatenates the args into a single list. It also eliminates leading and trailing spaces in the arg's and adds a single separator space between arg's. Args to concat may be either individual elements, or lists. If an arg is already a list, the contents of that list is concatenated with the other args.
lappend listName ?arg1 arg2 ... argn?: Appends the args to the list listName treating each arg as a list element.
linsert listName index arg1 ?arg2 ... argn?: Returns a new list with the new listelements inserted just before the indexth element of listName. Each element argument will become a separate element of the new list. If index is less than or equal to zero, then the new elements are inserted at the beginning of the list. If index has the value end, or if it is greater than or equal to the number of elements in the list, then the new elements are appended to the list.
lreplace listName first last ?arg1 ... argn?: Returns a new list with N elements of listName replaced by the args. If first is less than or equal to 0, lreplace starts replacing from the first element of the list. If first is greater than the end of the list, or the word end, then lreplace behaves like lappend. If there are fewer args than the number of positions between first and last, then the positions for which there are no args are deleted.

:TEXT_END: :LESSON_TEXT_START_LEVEL 1: The commands for adding and deleting list members are:

concat ?arg1 arg2 ... argn?: Concatenates the args into a single list. It also eliminates leading and trailing spaces in the arg's and adds a single separator space between arg's. Args to concat may be either individual elements, or lists. If an arg is already a list, the contents of that list is concatenated with the other args.
lappend listName ?arg1 arg2 ... argn?: Appends the args to the list listName treating each arg as a list element.
linsert listName index arg1 ?arg2 ... argn?: Returns a new list with the new listelements inserted just before the indexth element of listName. Each element argument will become a separate element of the new list. If index is less than or equal to zero, then the new elements are inserted at the beginning of the list. If index has the value end, or if it is greater than or equal to the number of elements in the list, then the new elements are appended to the list.
lreplace listName first last ?arg1 ... argn?: Returns a new list with N elements of listName replaced by the args. If first is less than or equal to 0, lreplace starts replacing from the first element of the list. If first is greater than the end of the list, or the word end, then lreplace behaves like lappend. If there are fewer args than the number of positions between first and last, then the positions for which there are no args are deleted.

Take a look at the example code, and pay special attention to the way that sets of characters are grouped into single list elements. :TEXT_END: :LESSON_TEXT_START_LEVEL 2: The list would be useful even if the only actions you could perform on it were to create and access members. However there are also a set of functions that allow you to add and delete items from a list.

These commands are:

concat ?arg1 arg2 ... argn?: Concatenates the args into a single list. It also eliminates leading and trailing spaces in the arg's and adds a single separator space between arg's. Args to concat may be either individual elements, or lists. If an arg is already a list, the contents of that list is concatenated with the other args.
lappend listName ?arg1 arg2 ... argn?: Appends the args to the list listName treating each arg as a list element.
linsert listName index arg1 ?arg2 ... argn?: Returns a new list with the new listelements inserted just before the indexth element of listName. Each element argument will become a separate element of the new list. If index is less than or equal to zero, then the new elements are inserted at the beginning of the list. If index has the value end, or if it is greater than or equal to the number of elements in the list, then the new elements are appended to the list.
lreplace listName first last ?arg1 ... argn?: Returns a new list with N elements of listName replaced by the args. If first is less than or equal to 0, lreplace starts replacing from the first element of the list. If first is greater than the end of the list, or the word end, then lreplace behaves like lappend. If there are fewer args than the number of positions between first and last, then the positions for which there are no args are deleted.
You can use this feature delete items from a list by giving the indexes of the range of items you wish to delete, and supplying *no* args.

Run the example, and examine it while you read the rest of this lesson.

Examine the way that list items are grouped in the example code. The {c d e} in the first example is a three element list consisting of three letters, while {f {g h}} is a two element list consisting of one letter, and a list of two letters. When these are joined into one list with the list command, each list within the string becomes an individual list element.

When the string is converted to a list with the split command, it splits on the whitespace, but treats the braces as meaningless characters. In order to keep other list commands from trying to interpret the braces as grouping operators, they are escaped with backslashes. Try using braces as the splitChars, and see what list gets created then.

Finally, when the lists are grouped with concat, the list elements of the lists are concat'ed into one list. :TEXT_END: :CODE_START: set b [list a b {c d e} {f {g h}}] puts "Treated as a list: $b\n" set b [split "a b {c d e} {f {g h}}"] puts "Transformed by split: $b\n" set a [concat a b {c d e} {f {g h}}] puts "Concated: $a\n" lappend a {ij K lm} ;# Note: {ij K lm} is a single element puts "After lappending: $a\n" set b [linsert $a 3 "1 2 3"] ;# "1 2 3" is a single element puts "After linsert at position 3: $b\n" ;# "AA" and "BB" are two list elements. set b [lreplace $b 3 5 "AA" "BB"] puts "After lreplacing 3 positions with 2 values at position 3: $b\n" :TEXT_END: