Category:LSL List

A list is a special kind of data type which can contain zero or more elements.

Lists are signified by square brackets surrounding their elements; the elements inside are separated by commas.

Examples:

[0,1,2,3,4]

["Yes","No","Perhaps"]

(Note: to be clear for those who have other programming backgrounds, there are no arrays in LSL: only lists.)

Diverse Data Types

Not all elements in a list need to be the same type of element. In the same list, you can store strings, integers, floats, vectors, etc, right side by side.

Example: //a list with an integer, a float, a string, and a vector.

[1,14.154,"Isn't this fun?",<0,0,0>]

However, a list may not contain another list (i.e. you can't nest them.)

[1, "one", 2, "two"] + [3, "three"] returns [1, "one", 2, "two", 3, "three"]

not

[1, "one", 2, "two", [3, "three"]]

When you add an element to a list, the list remembers automatically what data type the value was.

Generally, because you're the one adding something to a list, you know what datatype is in what place in the list, and you retrieve it out of the list with the appropriate llList2<type> function such as: llList2String, llList2Vector, etc. (more on this later.)

If for some reason, though, you need to test what data type an element is in a list, you can use the llGetListEntryType function.

Tip! When adding a float to a list, always add it with a decimal point (e.g 1.0 as opposed to 1) to ensure that it is preserved as a float.

Counting place in a list vs list length

It's important at the outset to note the following (which can trip up even experienced minds when they are battle-weary):

["Yes","No","Perhaps"]

The length of this list is 3, because it has 3 elements in it. The length of a list is returned by the llGetListLength() function:

integer length = llGetListLength(mylist);

BUT, counting to determine an element's place in its list (aka "indexing") starts at 0 -- NOT 1.

The position of "Yes" in the above list is 0, "No" is at position 1, and "Perhaps" is at position 2.

Consequently, if you have 7 elements in a list, the last item in the list will be at position 6.

Thus to retrieve the last element in a list, without having to know in advance what position it is at, you can just go:

integer length = llGetListLength(mylist);
string item = llList2String(myList,length - 1);

List Limits

While a script is running, a list can grow dynamically as large as needed, limited only by the amount of memory that is available in the script.

However, at compile (aka save) time, there is a 72 element limit to pre-defined lists hardcoded in the script. Such long, predefined lists are common, for example, when someone is offering the user a plethora of colour choices.

Tip! If you really need 72 or more such choices in a pre-defined list, just make 2 (or more) lists that don't upset the compiler, and join them together in state_entry() or wherever appropriate:

biggerlist = biglist01 + biglist02;

Adding an Element to a list

There are three ways used to append an element to an existing list:

1) myList = myList + [new_item]; 2) myList += [new_item]; 3) myList = (myList=[]) + myList + "new_item";

The third way saves memory. SL Psyke Phaeton has reported that when adding around 90 elements to a list, 3-4KB of memory can be saved. Why it works continues to be the topic of some discussion. It was invented, possibly, by Strife Onizuka.

Joining Lists (aka Concatenation)

Lists can be joined simply by using the + sign:

newlist = list01 + list02;

newlist = list01 + ["red","brown",<0,0,0>];

Clearing a List

To clear a list, set it equal to two square, empty brackets like this:

myList = [];

Strided lists

One common use of lists is to duplicate the functionality of structs, structured collections of data, which are available in many programming languages but not in LSL. As an example, you might use a list to track the names, gender and rezzdates of a group of avatars:

["John Adams", "male", "2007-06-22", "Shirley Bassey", "female", "2005-11-02", "Matt Damon", "male", "2008-05-19"]

This example has a stride of three, because the instance has three data elements. Index 0 ("John Adams") is the start of the first instance, index 3 ("Shirley Bassey") is the start of the second instance, and so on.

It is important that the types of information are always entered in the same sequence for every instance in the list! i.e. in this case that the name is always entered first. You should consider carefully the order in which you record information because the function to sort a list, llListSort, will only sort on the first element of the instances. In other words, if the avatar's rezzdate was the most important attribute for your script, then you would need to record it first, and the name second.

Extended List Operations

These functions have been created and contributed by LSL users to perform operations not covered by built-in LSL functions.