'''`[http://www.tcl.tk/man/tcl/TclCmd/append.htm%|%append]`''' appends strings to the value stored in a variable.



** Synopsis ** 

    :   '''append''' ''varName'' ?''value value value ...''?


 
** Documentation ** 

    [http://www.tcl.tk/man/tcl/TclCmd/append.htm%|%official reference]:   



** Description **

Appends each ''value'' to the value stored in the variable named by ''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.

`append` is a ''string'' command.  When working with lists, definitely use
`[concat]` or `[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
======

 
** See Also ** 

   [string]:   more string functions

   [concat]:   concatenate values. 

   [lappend]:   append a [word] to a list

<<discussion>>


----
Is the result of an append of two lists a list as you might expect it?

(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
======

The third word in 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]: For performance reasons, when concatenating the results of multiple substitutions or interspersing subtitutions with literal text, it's better to give [[append]] many arguments than to give it a single value argument.

======
append var xxx$a$b$c    ;# Has to compute $a$b$c to serve as argument
append var xxx $a $b $c ;# No temporary strings
======

----
[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], update: I feel this is a bug and is inconstent with the documentation.  It makes more sense to me that single-argument [[append]] create the variable with empty string as its initial value, same as `append var {}` described below.

foo: by traditional wisdom, `append var` is very likely to be a mistake, which 'should' raise an error to alert the programmer. OTOH, a lot of commands (e.g. `file delete`, `global`, etc) have been redefined to accept zero arguments in the wake of the expansion syntax (`append var {*}$anEmptyList` is equivalent to `append var`). However, in line with those commands, it should be a no-op, leaving `var` unchanged.


----
[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 is created and the value set to the [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