void append_by_ref(string varname, mixed var)
void append_by_ref(string varname, mixed var, boolean merge)
This is used to append values to the templates by reference instead of making a copy. See the PHP manual on variable referencing for an explanation. If you pass the optional third parameter of true, the value will be merged with the current array instead of appended.
Technical Note: append_by_ref() is more efficient than append() since it does not create an in-memory copy of the variable. Instead it refers to the actual variable in the memory heap. Be aware if you alter the original variable after it is assigned, the assigned variable sees the changes! PHP 5.0 will take care of referencing automatically, so this function acts as a workaround.
Technical Note: The merge parameter respects array keys, so if you merge two numerically indexed arrays, they may overwrite each other or result in non-sequential keys. This is unlike the array_merge() function of PHP which wipes out numerical keys and renumbers them.