List Data Type

Version: Available or changed with runtime version 1.0.

Represents a strongly typed list of ordered objects that can be accessed by index. Contrary to the Array data type, a List is unbounded, such that its dimension does not need to be specified upon declaration.

Instance methods

The following methods are available on instances of the List data type.

Method name	Description
Add(T)	Adds a value to the end of the List.
AddRange(T [, T,...])	Adds the elements of the specified collection to the end of the list.
AddRange(List of [T])	Adds the elements of the specified collection to the end of the list.
Contains(T)	Determines whether an element is in the List.
Count()	Gets the number of elements contained in the List.
Get(Integer, var T)	Gets the element at the specified index.
Get(Integer)	Gets the element at the specified index. This method will raise an error if the index is outside the valid range.
GetRange(Integer, Integer)	Get a shallow copy of a range of elements in the source.
GetRange(Integer, Integer, var List of [T])	Get a shallow copy of a range of elements in the source.
IndexOf(T)	Searches for the specified value and returns the one-based index of the first occurrence within the entire List.
Insert(Integer, T)	Inserts an element into the List at the specified index.
LastIndexOf(T)	Searches for the specified value and returns the one-based index of the last occurrence within the entire List.
Remove(T)	Removes the first occurrence of a specified value from the List.
RemoveAt(Integer)	Removes the element at the specified index of the List.
RemoveRange(Integer, Integer)	Removes a range of elements from the List.
Reverse()	Reverses the order of the elements in the entire List.
Set(Integer, T)	Sets the element at the specified index.
Set(Integer, T, var T)	Sets the element at the specified index.

Remarks

The List can only be used with simple types i.e. you can have a List of [Integer] but cannot have a List of [Blob]. Similarly, the List data type does not support holding instantiated records. For this purpose, use temporary tables.

Lists are 1-based indexed, that is, the indexing of a List begins with 1.

A List is a reference type, so assigning an instance of a list to another variable or passing as a method parameter by value (for example without var), creates a second variable that reads/writes the same list. It does not create a new list.

To create a new list that contains the same values as the original list, you can do the following to perform a shallow copy:

trigger OnRun()
    var
        l1: List of [Integer];
        l2: List of [Integer];
    begin
        l2 := l1.GetRange(1, l1.Count);
    end;

A shallow copy does not copy the elements within the list, only the list itself, so if the elements within the list are reference types as well, for example a list of lists, they will still be the same lists as in the original list.

To perform a deep copy, meaning to copy reference types within reference types, you will need to apply the same approach to the elements of the list:

trigger OnRun()
    var
        innerlist: List of [Integer];
        l1: List of [List of [Integer]];
        l2: List of [List of [Integer]];
    begin
        foreach innerlist in l1 do begin
            l2.Add(innerlist.GetRange(1, innerlist.Count));
        end;
    end;

Warning

Previously in C/AL, one would have typically used an in-memory temporary table to create an unbounded "array" data structure, as shown in the code below. In AL you use the List Data Type instead.

listRec.Value := ‘Some Value’;​
listRec.Insert();​

Example

In the following example, the variable CustomerNames is a list of Text values which represent customer names. The procedure WorkWithListOfCustomers displays how one would work with the List data type. The Add method is used to add the string 'John' to the CustomerNames list. The Contains method is used to check whether the list contains the specified value, in this case, the string 'John'. We continue by using the Message procedure to display a relevant message.

procedure WorkWithListOfCustomers()
var
    customerNames : List of [Text];
begin
    // Adding an element to the list
    customerNames.Add('John');

    // Checking if the list contains an element
    if customerNames.Contains('John') then
        Message('John is in the list')
    else 
        Message('John is not in the list')
end;

See Also

Get Started with AL
Developing Extensions
Dictionary Data Type