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