{"title":"List data type","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/methods-auto/list/list-data-type/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/list/list-data-type, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/list/list-data-type","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Represents a strongly typed list of ordered objects that can be accessed by index.","date":"2026-10-01","meta":{"topic":"reference"},"outline":[{"level":2,"title":"Instance methods","slug":"instance-methods","at":269,"chars":1904},{"level":2,"title":"Remarks","slug":"remarks","at":2173,"chars":2781}],"text":"> Version: _Available or changed with runtime version 1.0._\nRepresents 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.\n## Instance methods\nThe following methods are available on instances of the List data type.\nMethod name|Description\nAdd(T)<list-add-method>|Adds a value to the end of the List.\nlist-addrange-t-t-method|Adds the elements of the specified collection to the end of the list.\nlist-addrange-list[t]-method|Adds the elements of the specified collection to the end of the list.\nContains(T)<list-contains-method>|Determines whether an element is in the List.\nlist-count-method|Gets the number of elements contained in the List.\nGet(Integer, var T)<list-get-integer-t-method>|Gets the element at the specified index.\nlist-get-integer-method|Gets the element at the specified index. This method will raise an error if the index is outside the valid range.\nlist-getrange-integer-integer-method|Get a shallow copy of a range of elements in the source.\nGetRange(Integer, Integer, var List of [T])<list-getrange-integer-integer-list[t]-method>|Get a shallow copy of a range of elements in the source.\nIndexOf(T)<list-indexof-method>|Searches for the specified value and returns the one-based index of the first occurrence within the entire List.\nInsert(Integer, T)<list-insert-method>|Inserts an element into the List at the specified index.\nLastIndexOf(T)<list-lastindexof-method>|Searches for the specified value and returns the one-based index of the last occurrence within the entire List.\nRemove(T)<list-remove-method>|Removes the first occurrence of a specified value from the List.\nRemoveAt(Integer)<list-removeat-method>|Removes the element at the specified index of the List.\nRemoveRange(Integer, Integer)<list-removerange-method>|Removes a range of elements from the List.\nlist-reverse-method|Reverses the order of the elements in the entire List.\nlist-set-integer-t-method|Sets the element at the specified index.\nSet(Integer, T, var T)<list-set-integer-t-t-method>|Sets the element at the specified index.\n## Remarks\nThe 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.\nLists are 1-based indexed, that is, the indexing of a List begins with 1.\nA 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.\nTo create a new list that contains the same values as the original list, you can do the following to perform a shallow copy:\n```al\ntrigger OnRun()\n    var\n        l1: List of [Integer];\n        l2: List of [Integer];\n    begin\n        l2 := l1.GetRange(1, l1.Count);\n    end;\n```\nA 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.\nTo 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:\n```al\ntrigger OnRun()\n    var\n        innerlist: List of [Integer];\n        l1: List of [List of [Integer]];\n        l2: List of [List of [Integer]];\n    begin\n        foreach innerlist in l1 do begin\n            l2.Add(innerlist.GetRange(1, innerlist.Count));\n        end;\n    end;\n```\n> WARNING\n> 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.\n```al\n> listRec.Value := ‘Some Value’;​\n> listRec.Insert();​\n> ```\n\n## Example\n\nIn 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.\n\n```al\nprocedure WorkWithListOfCustomers()\nvar\n    customerNames : List of [Text];\nbegin\n    // Adding an element to the list\n    customerNames.Add('John');\n\n    // Checking if the list contains an element\n    if customerNames.Contains('John') then\n        Message('John is in the list')\n    else\n        Message('John is not in the list')\nend;\n\n```\n## Related information\nGet Started with AL<../../devenv-get-started>\nDeveloping Extensions<../../devenv-dev-overview>\n../dictionary/dictionary-data-type"}