***COMMAND***
append - Append strings to variable

***USAGE***
    :   '''append''' ''varName'' ?''value value value ...''?
 
***DESCRIPTION***
This [Tcl] command appends all of the ''value'' arguments to the current value
of variable ''varName''. If ''varName'' doesn't exist, it is
given a value equal to the concatenation of all the
''value'' arguments. This command provides an efficient
way to build up long variables incrementally. For
example, 
`append a $b` 
is much more efficient than
`set a $a$b`, 
if `$a` is long.
 
***MAN PAGE***
http://www.tcl.tk/man/tcl/TclCmd/append.htm
 
***SEE ALSO***
other string functions: [string]

similar functions for lists: [concat], [lappend]

***EXAMPLES***
Building a string of comma-separated numbers piecemeal using a loop.
 set var 0
 for {set i 1} {$i<=10} {incr i} {
    append var "," $i
 }
 puts $var
 # Prints 0,1,2,3,4,5,6,7,8,9,10
<<discussion>>
NOTE:   The append command is a ''string'' command. If you want to play with lists, definitely use the [concat] or [lappend] commands
----
Is the result of an append of two lists a list as you might expect it?
<<br>>
(EE: No. The result of an append of two lists is a ''string'', 
which, if it can form a valid list, will shimmer into list form next time it is treated as one.)

 set a [list a b c]
 set b [list 1 2 3]
 append a $b
 puts $a

Note that the third element of this new list is not c, but c1. 
Does anyone know if there are cases where an append would result 
in something '''not''' a list?

----
Here's an example of such a case:

 set l1 [list a {b c}]
 set l2 [list {d e} f]
 append l1 $l2
 llength $l1
[RS]: The intended functionality seems to me to be closer to [concat]. 
But if you wish to use ''append'', just add an extra space to separate the parts:
 append l1 " " $l2

----
[AMG]: Single-argument [[append]] works just like single-argument [[[set]]]: it returns the value of the named variable.  This isn't normally useful, but it might come in handy if the [{*}] expansion operator is used to produce the argument list.

If the variable doesn't exist, [[append]] dies with the same error that [[set]] would in the same situation.  This is the only time [[append]] will complain about the variable not existing, since it's normally a [Dangers of creative writing%|%creative writer].  If the variable exists but is an array, once again single-argument [[append]] gives the same error as [[set]], complaining about its inability to "read" it, once again showing single-argument [[append]] and [[set]] to be identical.  The rest of the time, the errors given by [[append]] complain about not being able to "set" the variable.

----
[AMG]: [[append]] can be used in a one-liner to initialize a variable's value to empty string if it doesn't exist.

======
append var ""
======

In the above code, if $var doesn't exist, it will be created with value set to empty string.  If it does exist, its value will be left unchanged.  According to [[tcl::unsupported::[representation]]], no [shimmering] is induced.

<<discussion>>

<<categories>> Tcl syntax help | Arts and crafts of Tcl-tk programming | Command