Why does arrayAppend return true and listAppend return the list?

Question

In ColdFusion, the arrayAppend() function takes an array and an item to be appended. It modifies the array that was passed in and returns true if successful.

The listAppend() function, however, takes a list and an item to be appended, and returns a new list with the item appended. It doesn't modify the list that was passed in.

Why do these functions operate in two different ways? I'm always turning to the documentation to remember the return value of each.

Answer 1

This is because there is no "List" data type in ColdFusion.

A "List" is a delimited string, simple as that. It is comma-delimited by default, but you can choose the delimiter. "ListAppend()" is a string concatenation operation, and as such it returns the result of its work just like "string1 & string2" would.

The only thing that "ListAppend()" does for you is: It takes care of the delimiter handling, preventing needless double delimiters - something that "string1 & string2" cannot do.

An array is a real data type and (in contrast to a string) can be modified in-place. This is what ArrayAppend() does.

Answer 2

ListAppend is essentially a string manipulation function that appends the element to the end of the list, and then returns the new list. In order to perform string manipulations that change the size of a string, you can't just append that data in memory. What if the next location in memory contains other important data? Instead, the system has to allocate a block of data equal (or greater) to the size of the new string. This block is in a new location, so the reference needs to be returned so the caller has access to the new data.

With arrayAppend, the size of the array is constant and doesn't change, so no new reference needs to be created.

Answer 3

To understand why this happens you need to know a little bit about how Strings work in Java because the underlying implementation of a list in ColdFusion is a java.lang.String.

<cfset list = "a,b,c"/>
<cfoutput>#list.getClass()#</cfoutput>

In Java, Strings are immutable and have no methods to modify the contents of a String. If you did the following in Java, you would be creating a new instance of a String and assigning it to s for each statement:

String s = "abc";
s = "def";
s = s.concat("ghi");

Using the listAppend() method in ColdFusion is creating a new instance of a String under the hood and returning it, thus the need to do something like this whenever you append values to a list.

<cfset list = "a,b,c"/>
<cfset list = listAppend(list,'d')/>
<cfoutput>#list#</cfoutput>

However, when you modify an array with arrayAppend(), you are directly modifying the array, thus there is no need to reassign the value to itself again like you need to with listAppend().

Answer 4

Also note that, even though all of the built-in array functions modify the array in-place, for user-defined functions, arrays are passed by value! This means that you cannot write a UDF that modifies an array in-place. (Unless you wrap the array in an object that is passed by reference, such as a struct or a CFC.)

The upshot of this is that if you write your own array utility functions, you often have to end up calling them like this:

<cfset MyArray = DoSomethingWithArray(MyArray)>

Answer 5

this is one of the stupidest things about CF. Reagrdless of the reasons behind it, List shares so many similarities with array but they act differently in this way.

The most annoying thing is that the page runs without throwing an error - making you think its fine.

So glad I found this page!